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 5002c2d6a2.
PrevUpHomeNext

Query

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("https://www.example.com/get-customer.php?id=409&name=Joe&individual");
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.

assert(url_view("https://www.example.com/get-customer.php?").has_query());
assert(!url_view("https://www.example.com/get-customer.php").has_query());

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("https://www.example.com/get-customer.php?name=John%26Doe");
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("https://www.example.com/get-customer.php?id=409&name=Joe&individual");
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");
++it;
assert((*it).key == "name");
assert((*it).value == "Joe");
++it;
assert((*it).key == "individual");
assert(!(*it).has_value);
[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("https://www.example.com/get-customer.php?key-1=value-1&key-2=&key-3&&=value-4");
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:

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

3) A key with no value:

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

4) A key with no value:

++it;
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("https://www.example.com/get-customer.php?email=joe@email.com&code=a:2@/!");
assert(u.has_query());

PrevUpHomeNext