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:

The query string is composed of a series of key-value pairs.
Within each pair, the field name and value are separated by an equals sign, "=".
The series of pairs is separated by the ampersand, "&".
Most web frameworks allow multiple values to have the same key.
Key comparisons are usually case sensitive, but the receiving authority is ultimately responsible for deciding this.

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( core::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.

Boost C++ Libraries

Params