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