Boost C++ Libraries

...one of the most highly regarded and expertly designed C++ library projects in the world. Herb Sutter and Andrei Alexandrescu, C++ Coding Standards

This is the documentation for a snapshot of the master branch, built from commit 20a7dc9240.
PrevUpHomeNext

Params

While the query is specified as a plain string, it is usually interpreted as a set of key-value pairs commonly referred to as URL Parameters, although here we use the term query parameters or params for short. There is no official, standard specification of the query parameters format, but the W3C recommendations and HTML 5 have this to say:

This URL has two query parameters, first and last whose values are "John" and "Doe" respectively:

http://www.example.com?first=John&last=Doe

Like the path, the library permits access to the params as using these separate, bidirectional view types which reference the underlying URL:

Table 1.29. Params Types

Type

Accessor

Description

params_view

params

A read-only range of decoded params.

params_ref

params

A modifiable range of decoded params.

params_encoded_view

encoded_params

A read-only range of params.

params_encoded_ref

encoded_params

A modifiable range of params.


A param always has a key, even if it is the empty string. The value is optional; an empty string is distinct from no value. To represent individual params the library uses these types, distinguished by their ownership model and whether or not percent-escapes are possible:

Table 1.30. Param Types

Type

String Type

Description

param

std::string

A key-value pair with ownership of the strings. This can be used to hold decoded strings, or to allow the caller to take ownership of a param by making a copy.

param_view

string_view

A key-value pair without percent-escapes, referencing externally managed character buffers.

param_pct_view

pct_string_view

A key-value pair which may contain percent-escapes, referencing externally managed character buffers.


Param types can be constructed from initializer lists, allowing for convenient notation. To represent a missing value, the constant no_value or nullptr may be used. This table shows some examples of initializer lists used to construct a param type, and the resulting data members:

Table 1.31. Param Initializers

Statement

qp.key

qp.value

qp.has_value

param qp = { "first", "John" };

"First"

"John"

true

param qp = { "first", "" };

"First"

""

true

param qp = { "first", no_value };

"First"

""

false

param qp = { "", "Doe" };

""

"Doe"

true


To understand the relationship between the query and the resulting range of params, first we define this function parms which returns a list of params corresponding to the elements in a container of params:

auto parms( string_view s ) -> std::list< param >
{
    url_view u( s );
    std::list< param > seq;
    for( auto qp : u.params() )
        seq.push_back( qp );
    return seq;
}

In the table below we show the result of invoking parms with different queries. This demonstrates how the syntax of the query maps to the parameter structure:

Table 1.32. Params Sequences

s

parms( s )

"?first=John&last=Doe"

{ { "first", "John" }, { "last", "Doe" } }

"?id=42&unsorted"

{ { "id", "42" }, { "last", no_value } }

"?col=cust&row="

{ { "col", "cust" }, { "row", "" } }

"?justify=left&"

{ { "justify", "left" }, { "", no_value } }

"?"

{ { "", no_value } }

""

{ }


It may be surprising that an empty query string ("?") produces a sequence with one empty param. This is by design, otherwise the sequence would not be distinguishable from the case where there is no query string (last two rows of the table above).

For complete details on containers used to represent query strings as params please view the reference.


PrevUpHomeNext