Params

While the query is specified as a plain string, it is usually interpreted as a set of key-value pairs commonly referred to as URL, although here we use the term query or params for short. There is no official, standard specification of the query parameters format, but the W3C recommendations and HTML 5 have this to say:

  • The query string is composed of a series of key-value pairs.

  • Within each pair, the field name and value are separated by an equals sign, "=".

  • The series of pairs is separated by the ampersand, "&".

  • Most web frameworks allow multiple values to have the same key.

  • Key comparisons are usually case sensitive, but the receiving authority is ultimately responsible for deciding this.

This URL has two query parameters, first and last whose values are "John" and "Doe" respectively:

http://www.example.com?first=John&last=Doe

Like the path, the library permits access to the params as using these separate, bidirectional view types which reference the underlying URL:

A param always has a key, even if it is the empty string. The value is optional; an empty string is distinct from no value. To represent individual params the library uses these types, distinguished by their ownership model and whether or not percent-escapes are possible:

Param types can be constructed from initializer lists, allowing for convenient notation. To represent a missing value, the constant no_value or nullptr may be used. This table shows some examples of initializer lists used to construct a param type, and the resulting data members:

To understand the relationship between the query and the resulting range of params, first we define this function parms which returns a list of params corresponding to the elements in a container of params:

// code_container_5_1

In the table below we show the result of invoking parms with different queries. This demonstrates how the syntax of the query maps to the parameter structure:

It may be surprising that an empty query string ("?") produces a sequence with one empty param. This is by design, otherwise the sequence would not be distinguishable from the case where there is no query string (last two rows of the table above).

For complete details on containers used to represent query strings as params please view the reference.