Containers
Three containers are provided for interacting with URLs:
Inheritance provides the observer and modifier
public members; class
url_view_base
has all the observers, while class
url_base
has all the modifiers.
Although the members are public, these base classes can only be
constructed by the library as needed to support the implementation.
The class hierarchy looks like this:
Throughout this documentation and especially below, when an observer
is discussed, it is applicable to all three derived containers
shown in the table above.
When a modifier is discussed, it is relevant to the containers
url and static_url.
The tables and exposition which follow describe the available
observers and modifiers, along with notes relating important
behaviors or special requirements.
Scheme
The scheme is represented as a case-insensitive string, along with an enumeration constant which acts as a numeric indentifier when the string matches one of the well-known schemes: http, https, ws, wss, file, and ftp. Characters in the scheme are never escaped; only letters and numbers are allowed, and the first character must be a letter.
These members are used to inspect and modify the scheme:
Authority
The authority is an optional part whose presence is indicated by an unescaped double slash ("//") immediately following the scheme, or at the beginning if the scheme is not present. It contains three components: an optional userinfo, the host, and an optional port. The authority in this diagram has all three components:
An empty authority, corresponding to just a zero-length host component, is distinct from the absence of an authority. These members are used to inspect and modify the authority as a whole string:
The paragraphs and tables that follow describe how to interact with the individual parts of the authority.
Userinfo
An authority may have an optional userinfo, which consists of a user and optional password. The presence of the userinfo is indicated by an unescaped at sign ("@") which comes afterwards. The password if present is prefixed by an unescaped colon (":"). An empty password string is distinct from no password. This table shows various URLs with userinfos, and the corresponding user and password:
These members are used to inspect and modify the userinfo:
Host
The host portion of the authority is a string which can be a host name, an IPv4 address, an IPv6 address, or an IPvFuture address depending on the contents. The host is always defined if an authority is present, even if the resulting host string would be zero length.
These members are used to inspect and modify the host:
Port
The port is a string of digits, possibly of zero length. The presence of a port is indicated by a colon prefix (":") appearing after the host and userinfo. A zero length port string is distinct from the absence of a port. The library represents the port with both a decimal string and an unsigned 16-bit integer. If the numeric value of the string would exceed the range of the integer, then it is mapped to the number zero.
These members are used to inspect and modify the port:
Path
Depending on the scheme, the path may be treated as a string, or as a hierarchically structured sequence of segments delimited by unescaped forward-slashes ("/"). A path is always defined for every URL, even if it is the empty string.
These members are used to inspect and modify the path:
The segments-based containers
segments_view, segments_ref,
segments_encoded_view, and segments_encoded_ref
are discussed in a later section.
Query
Depending on the scheme, the query may be treated as a string, or as a structured series of key-value pairs (called "params") separated by unescaped ampersands ("&"). The query is optional; an empty query string is distinct from no query.
These members are used to inspect and modify the query:
The params-based containers
params_view, params_ref,
params_encoded_view, and params_encoded_ref
are discussed in a later section.