Authority

Notation

The authority is a hierarchical element which names an entity governing the name space defined by the remainder of the URL. It divides into three subcomponents:

authority = [userinfo "@"] host [":" port]

The host subcomponent of the authority can be a registered name or an IP address.
The optional port number subcomponent is preceded by a colon ":"
The optional userinfo subcomponent consists of a username and an optional password

In a URL, the authority component is always preceded by a double slash ("//").

Table 1.12. Authority BNF

authority       = [ userinfo "@" ] host [ ":" port ]

userinfo        = user [ ":" [ password ] ]

host            = IP-literal / IPv4address / reg-name

port            = *DIGIT

user            = *( unreserved / pct-encoded / sub-delims )
password        = *( unreserved / pct-encoded / sub-delims / ":" )

IP-literal      = "[" ( IPv6address / IPvFuture  ) "]"

reg-name        = *( unreserved / pct-encoded / "-" / ".")

Member Functions

The functions for inspecting all or part of the authority in a url_view are as follows:

Table 1.13. Userinfo Observers

Function	Description
`has_password`	Return true if an password is present.
`has_userinfo`	Return true if a userinfo is present.
`encoded_password`	Return the password as a percent-encoded string.
`encoded_user`	Return the user as a percent-encoded string.
`encoded_userinfo`	Return the userinfo as a percent-encoded string.
`password`	Return the password as a string with percent-decoding applied.
`user`	Return the user as a string with percent-decoding applied.
`userinfo`	Return the userinfo as a string with percent-decoding applied.

Table 1.14. Host Observers

Function	Description
`encoded_host`	Return the host as a percent-encoded string.
`encoded_host_and_port`	Return the host and port as a percent-encoded string.
`has_port`	Return true if an port is present.
`host`	Return the type of host specified, if any.
`ipv4_address`	Return the IPv4 address of the host, if applicable.
`ipv6_address`	Return the IPv6 address of the host, if applicable.
`ipv_future`	Return the IPv-future address of the host, if applicable.
`port`	Return the port string of the host, if applicable.
`port_number`	Return the port number of the host, if applicable.

Table 1.15. Authority Observers

Function	Description
`has_authority`	Return true if an authority is present.
`encoded_authority`	Return the authority as a percent-encoded string.

Observers

The function encoded_authority can be used to obtain the authority from a url_view:

Code	Output
urls::string_view s = "https://www.boost.org/users/download/"; urls::url_view u = urls::parse_uri( s ).value(); std::cout << u << "\n" "scheme: " << u.scheme() << "\n" "has authority: " << u.has_authority() << "\n" "authority: " << u.encoded_authority() << "\n" "path: " << u.encoded_path() << "\n";	https://www.boost.org/users/download/ scheme: https has authority: 1 authority: www.boost.org path: /users/download/

Code

Output

urls::string_view s = "https://www.boost.org/users/download/";
urls::url_view u = urls::parse_uri( s ).value();
std::cout << u << "\n"
    "scheme:        " << u.scheme()   << "\n"
    "has authority: " << u.has_authority()     << "\n"
    "authority:     " << u.encoded_authority() << "\n"
    "path:          " << u.encoded_path()      << "\n";

https://www.boost.org/users/download/
scheme:        https
has authority: 1
authority:     www.boost.org
path:          /users/download/

These functions do not throw. If the URL has no authority, encoded_authority returns an empty string.

The function has_authority can be used to check whether this empty string means there is no authority or an empty authority in the URL.

Code	Output
urls::string_view s = "https:///path/to_resource"; urls::url_view u = urls::parse_uri( s ).value(); std::cout << u << "\n" "scheme: " << u.scheme() << "\n" "has authority: " << u.has_authority() << "\n" "authority: " << u.encoded_authority() << "\n" "path: " << u.encoded_path() << "\n";	https:///path/to_resource scheme: https has authority: 1 authority: path: /path/to_resource
urls::string_view s = "mailto://John.Doe@example.com"; urls::url_view u = urls::parse_uri( s ).value(); std::cout << u << "\n" "scheme: " << u.scheme() << "\n" "has authority: " << u.has_authority() << "\n" "authority: " << u.encoded_authority() << "\n" "path: " << u.encoded_path() << "\n";	mailto://John.Doe@example.com scheme: mailto has authority: 1 authority: John.Doe@example.com path:

Code

Output

urls::string_view s = "https:///path/to_resource";
urls::url_view u = urls::parse_uri( s ).value();
std::cout << u << "\n"
    "scheme:        " << u.scheme()            << "\n"
    "has authority: " << u.has_authority()     << "\n"
    "authority:     " << u.encoded_authority() << "\n"
    "path:          " << u.encoded_path()      << "\n";

https:///path/to_resource
scheme:        https
has authority: 1
authority:
path:          /path/to_resource

urls::string_view s = "mailto://John.Doe@example.com";
urls::url_view u = urls::parse_uri( s ).value();
std::cout << u << "\n"
    "scheme:        " << u.scheme()   << "\n"
    "has authority: " << u.has_authority()     << "\n"
    "authority:     " << u.encoded_authority() << "\n"
    "path:          " << u.encoded_path()      << "\n";

mailto://John.Doe@example.com
scheme:        mailto
has authority: 1
authority:     John.Doe@example.com
path:

Notice that there is no decoded counterpart of encoded_authority. The reason is any decoded character / could make it ambiguous with the path component.

The host subcomponent represents where resources are located. The functions encoded_host and host can be used to obtain the host from a url_view, while encoded_host_and_port allows us to directly obtain the host with the corresponding port number.

The host might be a registered name

Code	Output
urls::string_view s = "https://john.doe@www.example.com:123/forum/questions/"; urls::url_view u = urls::parse_uri( s ).value(); std::cout << u << "\n" "encoded host: " << u.encoded_host() << "\n" "host: " << u.host() << "\n" "host and port: " << u.encoded_host_and_port() << "\n" "port: " << u.port() << "\n" "port number: " << u.port_number() << "\n";	https://john.doe@www.example.com:123/forum/questions/ encoded host: www.example.com host: www.example.com host and port: www.example.com:123 port: 123 port number: 123

Code

Output

urls::string_view s = "https://john.doe@www.example.com:123/forum/questions/";
urls::url_view u = urls::parse_uri( s ).value();
std::cout << u << "\n"
    "encoded host:  " << u.encoded_host()          << "\n"
    "host:          " << u.host()                  << "\n"
    "host and port: " << u.encoded_host_and_port() << "\n"
    "port:          " << u.port()                  << "\n"
    "port number:   " << u.port_number()           << "\n";

https://john.doe@www.example.com:123/forum/questions/
encoded host:  www.example.com
host:          www.example.com
host and port: www.example.com:123
port:          123
port number:   123

or an IP address

Code	Output
urls::string_view s = "https://john.doe@192.168.2.1:123/forum/questions/"; urls::url_view u = urls::parse_uri( s ).value(); std::cout << u << "\n" "encoded host: " << u.encoded_host() << "\n" "host: " << u.host() << "\n" "host and port: " << u.encoded_host_and_port() << "\n" "port: " << u.port() << "\n" "port number: " << u.port_number() << "\n";	https://john.doe@192.168.2.1:123/forum/questions/ encoded host: 192.168.2.1 host: 192.168.2.1 host and port: 192.168.2.1:123 port: 123 port number: 123

Code

Output

urls::string_view s = "https://john.doe@192.168.2.1:123/forum/questions/";
urls::url_view u = urls::parse_uri( s ).value();
std::cout << u << "\n"
    "encoded host:  " << u.encoded_host()          << "\n"
    "host:          " << u.host()                  << "\n"
    "host and port: " << u.encoded_host_and_port() << "\n"
    "port:          " << u.port()                  << "\n"
    "port number:   " << u.port_number()           << "\n";

https://john.doe@192.168.2.1:123/forum/questions/
encoded host:  192.168.2.1
host:          192.168.2.1
host and port: 192.168.2.1:123
port:          123
port number:   123

Although this is not mandatory, note that the encoded host is rarely different from its encoded counterpart. The function port_number returns the decoded port as an integer.

Registered names usually need to be handled differently from IP addresses. The function host_type can be used to identify which type of host is described in the URL.

urls::string_view s = "https://www.boost.org/users/download/";
urls::url_view u = urls::parse_uri( s ).value();
switch (u.host_type())
{
case urls::host_type::name:
    // resolve name
case urls::host_type::ipv4:
case urls::host_type::ipv6:
case urls::host_type::ipvfuture:
    // connect to ip
    break;
case urls::host_type::none:
    // handle empty host URL
    break;
}

When the host_type matches an IP address, the functions ipv4_address, ipv6_address can be used to obtain the decoded addresses as integers.

Userinfo

The optional userinfo subcomponent consists of a user name and an optional password. The function encoded_userinfo can be used to retrieve the userinfo from a url_view. Analogous functions are provided for the userinfo subcomponents.

Code	Output
urls::string_view s = "https://john.doe:123456@www.somehost.com/forum/questions/"; urls::url_view u = urls::parse_uri( s ).value(); std::cout << u << "\n\n" // userinfo "has_userinfo: " << u.has_userinfo() << "\n" "encoded_userinfo: " << u.encoded_userinfo() << "\n" "userinfo: " << u.userinfo() << "\n\n" // user "encoded_user: " << u.encoded_user() << "\n" "user: " << u.user() << "\n\n" // password "has_password: " << u.has_password() << "\n" "encoded_password: " << u.encoded_password() << "\n" "password: " << u.password() << "\n";	https://john.doe:123456@www.somehost.com/forum/questions/ has_userinfo: 1 encoded_userinfo: john.doe:123456 userinfo: john.doe:123456 encoded_user: john.doe user: john.doe has_password: 1 encoded_password: 123456 password: 123456

Code

Output

urls::string_view s = "https://john.doe:123456@www.somehost.com/forum/questions/";
urls::url_view u = urls::parse_uri( s ).value();
std::cout << u << "\n\n"
    // userinfo
    "has_userinfo:     " << u.has_userinfo()     << "\n"
    "encoded_userinfo: " << u.encoded_userinfo() << "\n"
    "userinfo:         " << u.userinfo()         << "\n\n"
    // user
    "encoded_user:     " << u.encoded_user()     << "\n"
    "user:             " << u.user()             << "\n\n"
    // password
    "has_password:     " << u.has_password()     << "\n"
    "encoded_password: " << u.encoded_password() << "\n"
    "password:         " << u.password()         << "\n";

https://john.doe:123456@www.somehost.com/forum/questions/

has_userinfo:     1
encoded_userinfo: john.doe:123456
userinfo:         john.doe:123456

encoded_user:     john.doe
user:             john.doe

has_password:     1
encoded_password: 123456
password:         123456

Analogous to other observers, the functions has_userinfo and has_password are provided to differentiate empty components from absent components.

Note that there is no function has_user. The user component is available whenever userinfo exists.

Note

	Note
Although the specification allows the format `username:password`, the password component should be used with care. It is not recommended to transfer password data through URLs unless this is an empty string indicating no password.

Although the specification allows the format username:password, the password component should be used with care.

It is not recommended to transfer password data through URLs unless this is an empty string indicating no password.

Authority View

In contexts where an authority can appear by itself, the library provides the authority_view, a read-only container to a non-owning character buffer containing a valid authority.

As an example, the grammar for the request-target of an HTTP/1 CONNECT request uses authority-form. This is what such a request looks like:

CONNECT www.example.com:80 HTTP/1.1

In that case, we have an authority that cannot be parsed directly with parse_uri as a URL. Instead, we can use the analogous function parse_authority to obtain an authority_view.

Code	Output
urls::string_view s = "www.example.com:80"; urls::authority_view a = urls::parse_authority( s ).value(); std::cout << a << "\n\n" // host and port "encoded_host_and_port: " << a.encoded_host_and_port() << "\n" "encoded_host: " << a.encoded_host() << "\n" "host: " << a.host() << "\n" "port: " << a.port() << "\n" "port number: " << a.port_number() << "\n\n" // userinfo "has_userinfo: " << a.has_userinfo() << "\n" "encoded_userinfo: " << a.encoded_userinfo() << "\n" "userinfo: " << a.userinfo() << "\n\n" // user "encoded_user: " << a.encoded_user() << "\n" "user: " << a.user() << "\n\n" // password "has_password: " << a.has_password() << "\n" "encoded_password: " << a.encoded_password() << "\n" "password: " << a.password() << "\n";	www.example.com:80 encoded_host_and_port: www.example.com:80 encoded_host: www.example.com host: www.example.com port: 80 port number: 80 has_userinfo: 0 encoded_userinfo: userinfo: encoded_user: user: has_password: 0 encoded_password: password:

Code

Output

urls::string_view s = "www.example.com:80";
urls::authority_view a = urls::parse_authority( s ).value();
std::cout << a << "\n\n"
    // host and port
    "encoded_host_and_port: " << a.encoded_host_and_port()  << "\n"
    "encoded_host:          " << a.encoded_host() << "\n"
    "host:                  " << a.host()         << "\n"
    "port:                  " << a.port()         << "\n"
    "port number:           " << a.port_number()  << "\n\n"
    // userinfo
    "has_userinfo:          " << a.has_userinfo()     << "\n"
    "encoded_userinfo:      " << a.encoded_userinfo() << "\n"
    "userinfo:              " << a.userinfo()         << "\n\n"
    // user
    "encoded_user:          " << a.encoded_user()     << "\n"
    "user:                  " << a.user()             << "\n\n"
    // password
    "has_password:          " << a.has_password()     << "\n"
    "encoded_password:      " << a.encoded_password() << "\n"
    "password:              " << a.password()         << "\n";

www.example.com:80

encoded_host_and_port: www.example.com:80
encoded_host:          www.example.com
host:                  www.example.com
port:                  80
port number:           80

has_userinfo:          0
encoded_userinfo:
userinfo:

encoded_user:
user:

has_password:          0
encoded_password:
password:

The authority view provides the subset of observer member functions found in url_view which are relevant to the authority. However, when an authority is parsed on its own, the leading double slashes ("//") are not present.

The following authority string is also valid for parse_authority:

user:pass@www.example.com:443

Code	Output
urls::string_view s = "user:pass@www.example.com:443"; urls::authority_view a = urls::parse_authority( s ).value(); std::cout << a << "\n\n" // host and port "encoded_host_and_port: " << a.encoded_host_and_port() << "\n" "encoded_host: " << a.encoded_host() << "\n" "host: " << a.host() << "\n" "port: " << a.port() << "\n" "port number: " << a.port_number() << "\n\n" // userinfo "has_userinfo: " << a.has_userinfo() << "\n" "encoded_userinfo: " << a.encoded_userinfo() << "\n" "userinfo: " << a.userinfo() << "\n\n" // user "encoded_user: " << a.encoded_user() << "\n" "user: " << a.user() << "\n\n" // password "has_password: " << a.has_password() << "\n" "encoded_password: " << a.encoded_password() << "\n" "password: " << a.password() << "\n";	user:pass@www.example.com:443 encoded_host_and_port: www.example.com:443 encoded_host: www.example.com host: www.example.com port: 443 port number: 443 has_userinfo: 1 encoded_userinfo: user:pass userinfo: user:pass encoded_user: user user: user has_password: 1 encoded_password: pass password: pass

Code

Output

urls::string_view s = "user:pass@www.example.com:443";
urls::authority_view a = urls::parse_authority( s ).value();
std::cout << a << "\n\n"
    // host and port
    "encoded_host_and_port: " << a.encoded_host_and_port()  << "\n"
    "encoded_host:          " << a.encoded_host() << "\n"
    "host:                  " << a.host()         << "\n"
    "port:                  " << a.port()         << "\n"
    "port number:           " << a.port_number()  << "\n\n"
    // userinfo
    "has_userinfo:          " << a.has_userinfo()     << "\n"
    "encoded_userinfo:      " << a.encoded_userinfo() << "\n"
    "userinfo:              " << a.userinfo()         << "\n\n"
    // user
    "encoded_user:          " << a.encoded_user()     << "\n"
    "user:                  " << a.user()             << "\n\n"
    // password
    "has_password:          " << a.has_password()     << "\n"
    "encoded_password:      " << a.encoded_password() << "\n"
    "password:              " << a.password()         << "\n";

user:pass@www.example.com:443

encoded_host_and_port: www.example.com:443
encoded_host:          www.example.com
host:                  www.example.com
port:                  443
port number:           443

has_userinfo:          1
encoded_userinfo:      user:pass
userinfo:              user:pass

encoded_user:          user
user:                  user

has_password:          1
encoded_password:      pass
password:              pass

Use Cases

Note that if an authority is present, the host is always defined even if it is the empty string (corresponding to a zero-length reg-name in the BNF).

  https:///path/to_resource
  \____/\/\_______________/
    |   |          |
scheme authority  path

Component	Value
URL	`https:///path/to_resource`
Scheme	`https`
Has authority	Yes
Authority
Path	`/path/to_resource`

The authority component also influences how we should interpret the URL path. If the authority is present, the path component must either be empty or begin with a slash.

This is a common pattern where the path is empty:

https://www.boost.org
\___/   \___________/
scheme    authority    (path is empty)

Component	Value
URL	`https://www.boost.org`
Scheme	`https`
Has authority	Yes
Authority	`www.boost.org`
Path

When both the authority and path exist, the path needs to begin with a slash:

https://www.boost.org/users/download/
\___/   \___________/\______________/
scheme    authority        path (begins with a slash)

Component	Value
URL	`https://www.boost.org/users/download/`
Scheme	`https`
Has authority	Yes
Authority	`www.boost.org`
Path	`/users/download/`

This rule also affects the path "/":

https://www.boost.org/
\___/   \___________/\/
scheme    authority  path (begins with a slash)

Component	Value
URL	`https://www.boost.org/`
Scheme	`https`
Has authority	Yes
Authority	`www.boost.org`
Path	`/`

When there is no authority component, the path cannot begin with an empty segment. This means the path cannot begin with two slashes // to avoid these characters being interpreted as the beginning of the authority component.

For instance, consider the following valid URL:

mailto:John.Doe@example.com
\____/ \__________________/
scheme          path

Component	Value
URL	`mailto:John.Doe@example.com`
Scheme	`mailto`
Has authority	No
Authority
Path	`John.Doe@example.com`

Note how including a double slash would make the path be interpreted as the authority:

mailto://John.Doe@example.com
\____/ \____________________/
scheme       authority

Component	Value
URL	`mailto://John.Doe@example.com`
Scheme	`mailto`
Has authority	Yes
Authority	`John.Doe@example.com`
Path

In complete authority components, we can also extract the userinfo and port subcomponents.

        userinfo       host      port
        /------\ /-------------\ /-\
https://john.doe@www.example.com:123/forum/questions/
\___/   \__________________________/\_______________/
scheme          authority                  path

Component	Value
URL	`https://john.doe@www.example.com:123/forum/questions/`
Scheme	`https`
Has authority	Yes
Authority	`john.doe@www.example.com:123`
Host	`www.example.com`
Userinfo	`john.doe`
Port	`123`
Path	`/forum/questions/`