Query

Notation

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

Although there is no mandatory syntax for interpreting queries, its strings are often interpreted as key-value parameters delimited by the '&' or ';' character. 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":

https://www.example.com/get-customer.php?id=409&name=Joe&individual

A query is indicated by a leading question mark ('?') character as seen in the BNF below:

Table 1.20. Query BNF

query           = *( pchar / "/" / "?" )

absolute-URI    = scheme ":" hier-part [ "?" query ]

relative-ref    = relative-part [ "?" query ] [ "#" fragment ]

URI             = scheme ":" hier-part [ "?" query ] [ "#" fragment ]

URI-reference   = URI / relative-ref

This table shows the BNF for a query string interpreted as parameters:

Table 1.21. Query Params BNF

query-params    = query-param *( "&" query-param )

query-param     = key [ "=" value ]

key             = *qpchar
value           = *( qpchar / "=" )

qpchar          = unreserved
                / pct-encoded
                / "!" / "$" / "'" / "(" / ")"
                / "*" / "+" / "," / ";"
                / ":" / "@" / "/" / "?"

Member Functions

The functions for interacting with the query in a url_view are as follows:

Table 1.22. Query Observers

Function	Description
`has_query`	Return true if a query is present
`encoded_query`	Return the percent-encoded query.
`query`	Return the query as a string with percent-decoding applied.

A URL query is usually interpreted as parameters. The library provides two observers and read-only containers for interacting with the parameters in a URL's query:

Table 1.23. Query Params Observers

Function	Description
`encoded_params`	Return the query parameters as a read-only container of percent-encoded strings.
`params`	Return the query parameters as a read-only container of strings with percent-decoding applied.

Table 1.24. Params View Types

Type	Description
`params_encoded_view`	A read-only forward range of query parameters returned as percent-encoded strings.
`params_view`	A read-only forward range of query parameters returned as strings with percent-decoding applied.

Observers

The function encoded_query can be used to obtain the query string from a url_view:

Code	Output
urls::string_view s = "https://www.example.com/get-customer.php?name=joe"; urls::url_view u = urls::parse_uri(s).value(); std::cout << u << "\n" "encoded query: " << u.encoded_query() << "\n";	https://www.example.com/get-customer.php?name=joe encoded query: name=joe

Code

Output

urls::string_view s = "https://www.example.com/get-customer.php?name=joe";
urls::url_view u = urls::parse_uri(s).value();
std::cout << u << "\n"
          "encoded query: " << u.encoded_query() << "\n";

https://www.example.com/get-customer.php?name=joe
encoded query: name=joe

These functions do not throw. If the URL has no query, encoded_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.

Code	Output
urls::string_view s = "https://www.example.com/get-customer.php"; urls::url_view u = urls::parse_uri(s).value(); std::cout << u << "\n" "has query: " << u.has_query() << "\n" "encoded query: " << u.encoded_query() << "\n";	https://www.example.com/get-customer.php has query: 0 encoded query:

Code

Output

urls::string_view s = "https://www.example.com/get-customer.php";
urls::url_view u = urls::parse_uri(s).value();
std::cout << u << "\n"
          "has query:     " << u.has_query()     << "\n"
          "encoded query: " << u.encoded_query() << "\n";

https://www.example.com/get-customer.php
has query:     0
encoded query:

We can also use the function query to obtain the decoded counterpart of the query string.

Code	Output
urls::string_view s = "https://www.example.com/get-customer.php?name=John%20Doe"; urls::url_view u = urls::parse_uri(s).value(); std::cout << u << "\n" "has query: " << u.has_query() << "\n" "encoded query: " << u.encoded_query() << "\n" "query: " << u.query() << "\n";	https://www.example.com/get-customer.php?name=John%20Doe has query: 1 encoded query: name=John%20Doe query: name=John Doe

Code

Output

urls::string_view s = "https://www.example.com/get-customer.php?name=John%20Doe";
urls::url_view u = urls::parse_uri(s).value();
std::cout << u << "\n"
          "has query:     " << u.has_query()     << "\n"
          "encoded query: " << u.encoded_query() << "\n"
          "query:         " << u.query()         << "\n";

https://www.example.com/get-customer.php?name=John%20Doe
has query:     1
encoded query: name=John%20Doe
query:         name=John Doe

When using the query string as parameters, note that decoded query strings might include ambiguous & and = characters.

Code	Output
urls::string_view s = "https://www.example.com/get-customer.php?name=John%26Doe"; urls::url_view u = urls::parse_uri(s).value(); std::cout << u << "\n" "has query: " << u.has_query() << "\n" "encoded query: " << u.encoded_query() << "\n" "query: " << u.query() << "\n";	https://www.example.com/get-customer.php?name=John%26Doe has query: 1 encoded query: name=John%26Doe query: name=John&Doe

Code

Output

urls::string_view s = "https://www.example.com/get-customer.php?name=John%26Doe";
urls::url_view u = urls::parse_uri(s).value();
std::cout << u << "\n"
          "has query:     " << u.has_query()     << "\n"
          "encoded query: " << u.encoded_query() << "\n"
          "query:         " << u.query()         << "\n";

https://www.example.com/get-customer.php?name=John%26Doe
has query:     1
encoded query: name=John%26Doe
query:         name=John&Doe

In this example, the decoded query seems to imply there are two query parameters while there is only one parameter whose value includes a & character.

The reason the decoded variant of query string is still allowed is because query strings are not required to be interpreted as query parameters, in which case the & character is not ambiguous.

Parameter View

Parameter views are lightweight references to the underlying path string. 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.

Code	Output
urls::string_view s = "https://www.example.com/get-customer.php?id=409&name=Joe&individual"; urls::url_view u = urls::parse_uri(s).value(); std::cout << u << "\n" "has query: " << u.has_query() << "\n" "encoded query: " << u.encoded_query() << "\n" "query: " << u.query() << "\n"; std::cout << u.encoded_params().size() << " parameters\n"; for (auto p: u.encoded_params()) { if (p.has_value) { std::cout << "parameter: <" << p.key << ", " << p.value << ">\n"; } else { std::cout << "parameter: " << p.key << "\n"; } }	https://www.example.com/get-customer.php?id=409&name=Joe&individual has query: 1 encoded query: id=409&name=Joe&individual query: id=409&name=Joe&individual 3 parameters parameter: <id, 409> parameter: <name, Joe> parameter: individual

Code

Output

urls::string_view s = "https://www.example.com/get-customer.php?id=409&name=Joe&individual";
urls::url_view u = urls::parse_uri(s).value();
std::cout << u << "\n"
          "has query:     " << u.has_query()     << "\n"
          "encoded query: " << u.encoded_query() << "\n"
          "query:         " << u.query()         << "\n";
std::cout << u.encoded_params().size() << " parameters\n";
for (auto p: u.encoded_params())
{
    if (p.has_value)
    {
        std::cout <<
            "parameter: <" << p.key <<
            ", " << p.value << ">\n";
    } else {
        std::cout << "parameter: " << p.key << "\n";
    }
}

https://www.example.com/get-customer.php?id=409&name=Joe&individual
has query:     1
encoded query: id=409&name=Joe&individual
query:         id=409&name=Joe&individual
3 parameters
parameter: <id, 409>
parameter: <name, Joe>
parameter: individual

Each parameter is represented as a query_param_view structure, with fields to refer to the key and value. An extra field has_value is used to indicate whether the value is absent.

Use Cases

The most common formulation for the query in a URL is to define a set of key and value pairs of percent-encoded strings, using the ampersand ('&') character to delimit each pair after the first. 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 accessor functions which treat the query as a single string, the library provides container adaptors modeling ranges of query parameters. The following URL contains three query parameters:

Component	Value
URL	`https://www.example.com/get-customer.php?id=409&name=Joe&individual`
Has Query	Yes
Query	`id=409&name=Joe&individual`
Parameter 1	Key `id`, Value `409`
Parameter 2	Key `name`, Value `Joe`
Parameter 3	Key `individual`, No value

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 demonstrate all the ways that keys and values may appear in query parameters:

Component	Value
URL	`https://www.example.com/get-customer.php?key-1=value-1&key-2=&key-3&&=value-5`
Has Query	Yes
Query	`key-1=value-1&key-2=&key-3&&=value-5`
Parameter 1	Key `key-1`, Value `value-1`
Parameter 2	Key `key-2`, Value (empty)
Parameter 3	Key `key-3`, No value
Parameter 4	Key (empty), No value
Parameter 5	Key (empty), Value `value-5`

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

Component	Value
URL	`https://www.example.com/get-customer.php?email=joe@email.com&code=a:2@/!`
Has Query	Yes
Query	`email=joe@email.com&code=a:2@/!`
Parameter 1	Key `email`, Value `joe@email.com`
Parameter 2	Key `code`, Value `a:2@/!`