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:

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:

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

query-param     = key [ "=" value ]

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

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

Observers

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

string_view s = "https://www.example.com/get-customer.php?name=joe";
url_view u = parse_uri(s).value();
std::cout << u << "\n"
          "query: " << u.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, query and encoded_query return 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.

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

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

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

string_view s = "https://www.example.com/get-customer.php?name=John%26Doe";
url_view u = 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. In this case, the decoded parameters can be accessed safely through a parameter view.

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.

string_view s = "https://www.example.com/get-customer.php?id=409&name=Joe&individual";
url_view u = parse_uri(s).value();
std::cout << u << "\n"
          "has query:     " << u.has_query()     << "\n"
          "query:         " << u.query()         << "\n";
std::cout << u.params().size() << " parameters\n";

for (auto p: u.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
query:         id=409&name=Joe&individual
3 parameters
parameter: <id, 409>
parameter: <name, Joe>
parameter: individual

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.

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:

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:

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

Member Functions

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

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

The functions for modifying the query in a url are as follows:

A URL query is usually interpreted as parameters. A url provides two modifiable containers for interacting with the parameters in a URL's query: