Components

Containers

Three containers are provided for interacting with URLs:

Name Description

Name	Description
`url`	A valid, modifiable URL which performs dynamic memory allocation to store the character buffer.
`url_view`	A read-only reference to a character buffer containing a valid URL. The view does not retain ownership of the underlying character buffer; instead, it is managed by the caller.
`static_url`	A valid, modifiable URL which stores the character buffer inside the class itself. This is a class template, where the maximum buffer size is a non-type template parameter.

url

A valid, modifiable URL which performs dynamic memory allocation to store the character buffer.

url_view

A read-only reference to a character buffer containing a valid URL. The view does not retain ownership of the underlying character buffer; instead, it is managed by the caller.

static_url

A valid, modifiable URL which stores the character buffer inside the class itself. This is a class template, where the maximum buffer size is a non-type template parameter.

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 most important part is the scheme, whose production rule is:

scheme        = ALPHA *( ALPHA / DIGIT / "+" / "-" / "." )

The scheme, which some informal texts incorrectly refer to as "protocol", defines how the rest of the URL is interpreted. Public schemes are registered and managed by the Internet Assigned Numbers Authority (IANA). Here are some registered schemes and their corresponding specifications:

Scheme	Specification
http	http URI Scheme (rfc7230)
magnet	Magnet URI scheme
mailto	The 'mailto' URI Scheme (rfc6068)
payto	The 'payto' URI Scheme for Payments (rfc8905)
telnet	The telnet URI Scheme (rfc4248)
urn	URN Syntax

Scheme

Specification

http

http URI Scheme (rfc7230)

magnet

Magnet URI scheme

mailto

The 'mailto' URI Scheme (rfc6068)

payto

The 'payto' URI Scheme for Payments (rfc8905)

telnet

The telnet URI Scheme (rfc4248)

urn

URN Syntax

Private schemes are possible, defined by organizations to enumerate internal resources such as documents or physical devices, or to facilitate the operation of their software. These are not subject to the same rigor as the registered ones; they can be developed and modified by the organization to meet specific needs with less concern for interoperability or backward compatibility. Note that private does not imply secret; some private schemes such as Amazon’s "s3" have publicly available specifications and are quite popular. Here are some examples:

Scheme	Specification
app	app: URL Scheme
odbc	ODBC URI Scheme
slack	Reference: Deep linking into Slack

Scheme

Specification

app

app: URL Scheme

odbc

ODBC URI Scheme

slack

Reference: Deep linking into Slack

In some cases the scheme is implied by the surrounding context and therefore omitted. Here is a complete HTTP/1.1 GET request for the target URL "/index.htm":

GET /index.htm HTTP/1.1
Host: www.example.com
Accept: text/html
User-Agent: Beast

The scheme of "http" is implied here because the context is already an HTTP request. The production rule for the URL in the request above is called origin-form, defined in the HTTP specification thusly:

origin-form    = absolute-path [ "?" query ]

absolute-path  = 1*( "/" segment )

All URLs have a scheme, whether it is explicit or implicit. The scheme determines what the rest of the URL means.

Here are some more examples of URLs using various schemes (and one example of something that is not a URL):

URL Notes

URL	Notes
`https://www.boost.org/index.html`	Hierarchical URL with `https` protocol. Resource in the HTTP protocol.
`ftp://host.dom/etc/motd`	Hierarchical URL with `ftp` scheme. Resource in the FTP protocol.
`urn:isbn:045145052`	Opaque URL with `urn` scheme. Identifies `isbn` resource.
`mailto:person@example.com`	Opaque URL with `mailto` scheme. Identifies e-mail address.
`index.html`	URL reference. Missing scheme and authority.
`www.boost.org`	A Protocol-Relative Link (PRL). Not a URL.

https://www.boost.org/index.html

Hierarchical URL with https protocol. Resource in the HTTP protocol.

ftp://host.dom/etc/motd

Hierarchical URL with ftp scheme. Resource in the FTP protocol.

urn:isbn:045145052

Opaque URL with urn scheme. Identifies isbn resource.

mailto:person@example.com

Opaque URL with mailto scheme. Identifies e-mail address.

index.html

URL reference. Missing scheme and authority.

www.boost.org

A Protocol-Relative Link (PRL). Not a URL.

API Reference

The scheme is represented as a case-insensitive string, along with an enumeration constant which acts as a numeric identifier 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:

Function Return Type Description

Function	Return Type	Description
`has_scheme`	`bool`	Return `true` if a scheme is present.
`scheme`	`string_view`	Return the scheme as a string, or the empty string if there is no scheme.
`scheme_id`	`scheme`	Return the scheme as an enumerated constant, the value `scheme::unknown` if the scheme is not one of the well-known schemes, or the value `scheme::none` if there is no scheme.

has_scheme

bool

Return true if a scheme is present.

scheme

string_view

Return the scheme as a string, or the empty string if there is no scheme.

scheme_id

scheme

Return the scheme as an enumerated constant, the value scheme::unknown if the scheme is not one of the well-known schemes, or the value scheme::none if there is no scheme.

Function Parameters Description

Function	Parameters	Description
`set_scheme`	`string_view`	Set the scheme to a string.
`set_scheme_id`	`scheme`	Set the scheme to a well-known scheme constant.
`remove_scheme`		Remove the scheme if present. This includes the trailing colon (":").

set_scheme

string_view

Set the scheme to a string.

set_scheme_id

scheme

Set the scheme to a well-known scheme constant.

remove_scheme

Remove the scheme if present. This includes the trailing colon (":").

Some package managers (pip, npm) and tools use compound schemes like git+https:// or svn+ssh:// where a plus sign separates a protocol from a transport mechanism. Boost.URL treats these as single scheme strings per RFC 3986 (which allows plus signs). To extract the transport suffix, use a helper like scheme_ex:

// Helper function to extract transport scheme from compound schemes
boost::core::string_view
scheme_ex(boost::core::string_view s)
{
    // Find the last '+' in the scheme
    // Examples: "git+https" -> "https", "svn+ssh" -> "ssh"
    auto pos = s.rfind('+');
    if (pos != boost::core::string_view::npos)
        return s.substr(pos + 1);
    return {};
}

This is an informal convention, not a URL standard. See WHATWG discussion.

Authority

The authority determines how a resource can be accessed. It contains two parts: the userinfo that holds identity credentials, and the host and port which identify a communication endpoint having dominion over the resource described in the remainder of the URL. This is the ABNF specification for the authority part:

authority   = [ user [ ":" password ] "@" ] host [ ":" port ]

The combination of user and optional password is called the userinfo.

Some observations:

The use of the password field is deprecated.
The authority always has a defined host field, even if empty.
The host can be a name, or an IPv4, an IPv6, or an IPvFuture address.
All but the port field use percent-encoding to escape delimiters.

The host subcomponent represents where resources are located.

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).

url_view u( "https:///path/to_resource" );
assert( u.has_authority() );
assert( u.authority().buffer().empty() );
assert( u.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.

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.

API Reference

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.

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:

Function Return Type Description

Function	Return Type	Description
`has_authority`	`bool`	Return `true` if an authority is present.
`authority`	`authority_view`	Return the authority as a decoded string.
`encoded_authority`	`pct_string_view`	Return the authority as a read-only view.

has_authority

bool

Return true if an authority is present.

authority

authority_view

Return the authority as a decoded string.