Algorithms which parse URLs return a view which references the underlying character buffer without taking ownership, avoiding memory allocations and copies. The following example parses a string literal containing a URI:

result< url_view > r = parse_uri( "https://www.example.com/path/to/file.txt" );

The function returns a result which holds a url_view if the string is a valid URL. Otherwise it holds an error_code. It is impossible to construct a url_view which refers to an invalid URL.

	Warning
	The caller is responsible for ensuring that the lifetime of the character buffer extends until it is no longer referenced by the view. These are the same semantics as that of std::string_view.

When a view is directly constructed from a string_view it parses it according to the URI-reference grammar, throwing an exception upon failure:

url_view u( "https://www.example.com/path/to/file.txt" );

The URL is stored in its serialized form. Therefore, it can always be easily output, sent, or embedded as part of a protocol:

std::cout << u;

A url is an allocating container which owns its character buffer. Upon construction from url_view, it allocates dynamic storage to hold a copy of the string.

result< url > rv = parse_uri_reference( "https://www.example.com/path/to/file.txt" );

static_assert( std::is_convertible< result< url_view >, result< url > >::value, "" );

A static_url is a container which owns its character buffer for a URL whose maximum size is known. Upon construction from url_view, it does not perform any dynamic memory allocations.

result< static_url<1024> > rv = parse_uri_reference( "https://www.example.com/path/to/file.txt" );

static_assert( std::is_convertible< result< static_url<1024> >, result< url > >::value, "" );

Result Type

In many places, functions in the library have a return type which uses the result alias template. This class allows the parsing algorithms to report errors without referring to exceptions.

The functions result::has_value and result::has_error can be used to check if the result contains an error.

result< url_view > r = parse_uri( "https://www.example.com/path/to/file.txt" );

This ensures result::value will not throw an error. In contexts where it is acceptable to throw errors, result::value can be used directly.

Check the reference for result for a synopsis of the type. For complete information please consult the full result documentation in Boost.System.

URL types

Parsing functions are functions which start with the word "parse", and are suffixed with the name of the grammar applied to the string. For example, the function parse_relative_ref parses the grammar found in 4.2.Relative Reference (rfc3986). A URL string can also be parsed using one of the following functions:

The functions parse_uri and parse_absolute_uri are only valid if the URL contains the scheme component. On the other hand, relative URI references are not required to have a scheme. For instance, we can parse a relative URL that only contains a path as

result< url_view > r0 = parse_relative_ref( "/path/to/file.txt" );
assert( r0.has_value() );

These relative references can be combined with base absolute URLs:

result< url_view > r1 = parse_uri( "https://www.example.com" );
assert( r1.has_value() );
url dest;
resolve(r1.value(), r0.value(), dest);
assert(dest.buffer() == "https://www.example.com/path/to/file.txt");

The Help Card provides a visual summary of all of the member functions and types used by the library with URL containers. In the sections that follow we discuss each of the five major parts of the URL and how they may be inspected and modified.