Boost C++ Libraries Home Libraries People FAQ More



The URL query augments the information in the path to identify a resource within the scope of the scheme and authority. Unlike the URL path, the query string always contains non-hierarchical data.

Although the field is opaque and there is no mandatory syntax for interpreting queries, its strings are usually interpreted as key-value parameters delimited by the '&' or ';' character. In contexts where a query is interpreted as key/value pairs, it is called the query parameters, query params, or just params. In addition to interacting with the query as a single string, the library provides container adaptors modeling ranges of individual query parameters.

The URL below contains the query "?id=409&name=Joe&individual" with the three parameters "id=409", "name=Joe", and "individual":

url_view u("");
assert( u.query() == "id=409&name=Joe&individual" );

If the URL has no query, query returns an empty string. The function has_query can be used to determine whether this empty string means there is no query or an empty query string in the URL.


When using the query string as parameters, note that decoded query strings might include ambiguous & and = characters. In the following example, the decoded query implies there are two query parameters while there is only one parameter whose value includes a & character.

url_view u("");
assert(u.query() == "name=John&Doe");

The reason the decoded variant of a query is still allowed is because protocols are also allowed to interpret queries as opaque strings, in which case the & character is not ambiguous.

When the query string represents parameters, the decoded parameters can be accessed safely through a parameter view.

url_view u("");
params_view ps = u.params();
assert(ps.size() == 3);

Parameter views are lightweight references to the underlying path string. Each parameter is represented as a structure with fields to refer to the key and value. An extra field has_value is used to indicate whether the value is absent.

auto it = ps.begin();
assert((*it).key == "id");
assert((*it).value == "409");
assert((*it).key == "name");
assert((*it).value == "Joe");
assert((*it).key == "individual");
[Warning] Warning

Ownership of the string is not transferred; the caller is responsible for ensuring that the lifetime of the string extends until the container is destroyed.

In addition to accessor functions which treat the query as a single string, the library provides container adaptors modeling ranges of query parameters.

Note that a parameter value might be either empty or absent. The presence of a value is indicated by the presence of an equals ('=') sign appearing after the key. This means the value may be absent, empty, or contain characters.

The key of a query parameter might also be empty. This means that a query parameter may be completely empty. In this case the parameter is said to have a zero-length or empty key, and no value.

The URL below demonstrates all the ways that keys and values may appear in query parameters:

url_view u("");
params_view ps = u.params();
assert(ps.size() == 5);

1) The regular key and value pair:

auto it = ps.begin();
assert((*it).key == "key-1");
assert((*it).value == "value-1");

2) A key with an empty value:

assert((*it).key == "key-2");
assert((*it).value == "");

3) A key with no value:

assert((*it).key == "key-3");

4) A key with no value:

assert((*it).key == "");
assert((*it).value == "value-4");
[Note] Note

The URL reserved characters :, @, ?, and / may appear unencoded with URL queries, as they are not ambiguous with other URL components.

url_view u("!");