Parsing

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:

// code_urls_parsing_1

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.

For convenience, a URL view can be constructed directly from the character buffer in a string_view. In this case, it parses the string according to the URI-reference grammar, throwing an exception upon failure. The following two statements are equivalent:

// code_urls_parsing_2

In this library, free functions which parse things are named with the word "parse" followed by the name of the grammar used to match the string. There are several varieties of URLs, and depending on the use-case a particular grammar may be needed. In the target of an HTTP GET request for example, the scheme and fragment are omitted. This corresponds to the origin-form production rule described in rfc7230. The function parse_origin_form is suited for this purpose. All the URL parsing functions are listed here:

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

// snippet_parsing_url_1bb

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.

// snippet_parsing_url_1bc

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.

// snippet_parsing_url_1bd

Result Type

These functions 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::operator bool() and result::operator* can be used to check if the result contains an error.

// snippet_parsing_url_1

Since result::operator bool() is already checking if result contains an error, result::operator* provides an unchecked alternative to get a value from result. In contexts where it is acceptable to throw errors, result::value can be used directly.

// snippet_parsing_url_1b

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