Reference

Namespaces

Name	Description
`boost`

Namespaces

Name	Description
`urls`

Namespaces

Name	Description
`error_types`
`grammar`
`implementation_defined`
`see_below`
`string_token`

Types

Name	Description
`authority_view`	A non-owning reference to a valid authority
`decode_view`	A reference to a valid, percent-encoded string
`encoding_opts`	Percent-encoding options
`ignore_case_param`	An optional parameter to determine case-sensitivity
`ipv4_address`	An IP version 4 style address.
`ipv6_address`	An IP version 6 style address.
`no_value_t`	The type of no_value
`optional`	The type of optional used by the library
`param`	A query parameter
`param_pct_view`	A query parameter
`param_view`	A query parameter
`params_base`	Common functionality for containers
`params_encoded_base`	Common functionality for containers
`params_encoded_ref`	A view representing query parameters in a URL
`params_encoded_view`	A view representing query parameters in a URL
`params_ref`	A view representing query parameters in a URL
`params_view`	A view representing query parameters in a URL
`pct_string_view`	A reference to a valid percent-encoded string
`segments_base`	Common functionality for containers
`segments_encoded_base`	Common functionality for containers
`segments_encoded_ref`	A view representing path segments in a URL
`segments_encoded_view`	A view representing path segments in a URL
`segments_ref`	A view representing path segments in a URL
`segments_view`	A view representing path segments in a URL
`static_url`	A modifiable container for a URL.
`static_url_base`	Common implementation for all static URLs
`string_view`	The type of string_view used by the library
`url`	A modifiable container for a URL.
`url_base`	Common functionality for containers
`url_view`	A non-owning reference to a valid URL
`url_view_base`	Common functionality for containers
`variant`	The type of variant used by the library

Enums

Name	Description
`error`	Error codes returned the library
`host_type`	Identifies the type of host in a URL.
`scheme`	Identifies a known URL scheme

Functions

Name	Description
`arg`	Designate a named argument for a replacement field
`default_port`	Return the default port for a known scheme
`encode`	Apply percent-encoding to a string Return a percent-encoded string
`encoded_size`	Return the buffer size needed for percent-encoding
`format`	Format arguments into a URL
`format_to`	Format arguments into a URL
`make_pct_string_view`	Return a valid percent-encoded string
`operator!=`	Compare two decode views for inequality Return the result of comparing two URLs Return the result of comparing two authorities The authorities are compared component by component as if they were first normalized. Return true if two addresses are not equal
`operator<`	Compare two decode views for less than Return the result of comparing two URLs Return the result of comparing two authorities The authorities are compared component by component as if they were first normalized.
`operator<<`	Format the address to an output stream. Format the address to an output stream Format the encoded authority to the output stream Format the string with percent-decoding applied to the output stream Format the url to the output stream Format to an output stream
`operator<=`	Compare two decode views for less than or equal Return the result of comparing two URLs Return the result of comparing two authorities The authorities are compared component by component as if they were first normalized.
`operator==`	Compare two decode views for equality Return the result of comparing two URLs Return the result of comparing two authorities The authorities are compared component by component as if they were first normalized. Return true if two addresses are equal
`operator>`	Compare two decode views for greater than Return the result of comparing two URLs Return the result of comparing two authorities The authorities are compared component by component as if they were first normalized.
`operator>=`	Compare two decode views for greater than or equal Return the result of comparing two URLs Return the result of comparing two authorities The authorities are compared component by component as if they were first normalized.
`parse_absolute_uri`	Return a reference to a parsed URL string
`parse_authority`	Parse an authority
`parse_ipv4_address`	Return an IPv4 address from an IP address string in dotted decimal form
`parse_ipv6_address`	Parse a string containing an IPv6 address.
`parse_origin_form`	Return a reference to a parsed URL string
`parse_path`	Parse a string and return an encoded segment view
`parse_query`	Parse a string and return an encoded params view
`parse_relative_ref`	Return a reference to a parsed URL string
`parse_uri`	Return a reference to a parsed URL string
`parse_uri_reference`	Return a reference to a parsed URL string
`pct_encoded_rule`	Rule for a string with percent-encoded escapes
`resolve`	Resolve a URL reference against a base URL
`string_to_scheme`	Return the known scheme for a non-normalized string, if known
`swap`	Swap
`to_string`	Return the normalized string for a known scheme

Variables

Name	Description
`absolute_uri_rule`	Rule for absolute-URI
`authority_rule`	Rule for authority
`gen_delim_chars`	The gen-delims character set
`ignore_case`	Ignore case when comparing
`ipv4_address_rule`	Rule for an IP version 4 style address
`ipv6_address_rule`	Rule for An IP version 6 style address
`no_value`	Constant indicating no value in a param
`origin_form_rule`	Rule for origin-form
`pchars`	The path character set
`query_rule`	Rule for query
`relative_ref_rule`	Rule for relative-ref
`reserved_chars`	The reserved character set
`sub_delim_chars`	The sub-delims character set
`unreserved_chars`	The unreserved character set
`uri_reference_rule`	Rule for URI-reference
`uri_rule`	Rule for URI

Using Directives

Name	Description
`error_types`

Namespaces

Name	Description
`implementation_defined`
`see_below`

Types

Name	Description
`aligned_storage`	Provides an aligned storage buffer aligned for T
`ci_equal`	A case-insensitive equals predicate for strings
`ci_hash`	A case-insensitive hash function object for strings
`ci_less`	A case-insensitive less predicate for strings
`is_charset`	Alias for `std::true_type` if T satisfies CharSet .
`is_rule`	Determine if T meets the requirements of Rule
`literal_rule`
`lut_chars`	A set of characters
`range`	A forward range of parsed elements
`recycled`	A thread-safe collection of instances of T
`recycled_ptr`	A pointer to a shared instance of T
`string_view_base`	Common functionality for string views
`unsigned_rule`	Match an unsigned decimal

Enums

Name	Description
`condition`	Error conditions for errors received from rules
`error`	Error codes returned when using rules

Functions

Name	Description
`ci_compare`	Return the case-insensitive comparison of s0 and s1
`ci_digest`	Return the case-insensitive digest of a string
`ci_is_equal`	Return true if s0 equals s1 using case-insensitive comparison
`ci_is_less`	Return true if s0 is less than s1 using case-insensitive comparison
`delim_rule`	Match a character literal Match a single character from a character set
`find_if`	Find the first character in the string that is in the set.
`find_if_not`	Find the first character in the string that is not in CharSet
`hexdig_value`	Return the decimal value of a hex character
`not_empty_rule`	Match another rule, if the result is not empty
`operator!=`	Compare two string views for inequality
`operator+`	Return the union of two character sets.
`operator-`	Return a new character set by subtracting
`operator<`	Compare two string views for less than
`operator<<`	Format a string to an output stream
`operator<=`	Compare two string views for less than or equal
`operator==`	Compare two string views for equality
`operator>`	Compare two string views for greater than
`operator>=`	Compare two string views for greater than or equal
`optional_rule`	Match a rule, or the empty string
`parse`	Parse a character buffer using a rule
`range_rule`	Match a repeating number of elements
`ref`	Return a reference to a character set Return a reference to a rule
`squelch`	Squelch the value of a rule
`to_lower`	Return c converted to lowercase
`to_upper`	Return c converted to uppercase
`token_rule`	Match a non-empty string of characters from a set
`tuple_rule`	Match a series of rules in order
`variant_rule`	Match one of a set of rules

Variables

Name	Description
`all_chars`	The set of all characters
`alnum_chars`	The set of letters and digits
`alpha_chars`	The set of all letters
`dec_octet_rule`	Match a decimal octet
`digit_chars`	The set of decimal digits
`hexdig_chars`	The set of hexadecimal digits
`vchars`	The set of visible characters

Types

Name	Description
`all_chars_t`
`alnum_chars_t`
`alpha_chars_t`
`ch_delim_rule`
`charset_ref`
`cs_delim_rule`
`dec_octet_rule_t`
`digit_chars_t`
`hexdig_chars_t`
`not_empty_rule_t`
`optional_rule_t`
`range_rule_t`
`range_rule_t<R>`
`rule_ref`
`squelch_rule_t`
`token_rule_t`
`tuple_rule_t`
`variant_rule_t`
`vchars_t`

Synopsis

Declared in <include/boost/url/grammar/alnum_chars.hpp>


struct alnum_chars_t;

Member Functions

Name	Description
`operator()`

Synopsis

Declared in <include/boost/url/grammar/alnum_chars.hpp>


constexpr
bool
operator()(char c) const noexcept;

Synopsis

Declared in <include/boost/url/grammar/alpha_chars.hpp>


struct alpha_chars_t;

Member Functions

Name	Description
`alpha_chars_t` [constructor]
`operator()`

Synopsis

Declared in <include/boost/url/grammar/alpha_chars.hpp>


constexpr
alpha_chars_t() noexcept = default;

Synopsis

Declared in <include/boost/url/grammar/alpha_chars.hpp>


constexpr
bool
operator()(char c) const noexcept;

Synopsis

Declared in <include/boost/url/grammar/charset.hpp>


template<class CharSet>
struct charset_ref;

Member Functions

Name	Description
`find_if`
`find_if_not`
`operator()`

Data Members

Name	Description
`cs_`

Synopsis

Declared in <include/boost/url/grammar/charset.hpp>


CharSet const& cs_;

Synopsis

Declared in <include/boost/url/grammar/charset.hpp>


constexpr
bool
operator()(char ch) const noexcept;

Synopsis

Declared in <include/boost/url/grammar/charset.hpp>


char const*
find_if(
    char const* first,
    char const* last) const noexcept;

Synopsis

Declared in <include/boost/url/grammar/charset.hpp>


char const*
find_if_not(
    char const* first,
    char const* last) const noexcept;

Synopsis

Declared in <include/boost/url/grammar/dec_octet_rule.hpp>


struct dec_octet_rule_t;

Types

Name	Description
`value_type`

Member Functions

Name	Description
`parse`

Synopsis

Declared in <include/boost/url/grammar/dec_octet_rule.hpp>


using value_type = unsigned char;

Synopsis

Declared in <include/boost/url/grammar/dec_octet_rule.hpp>


system::result<    _implementation-defined_>
parse(
    char const*& it,
    char const* end) const noexcept;

Synopsis

Declared in <include/boost/url/grammar/delim_rule.hpp>


struct ch_delim_rule;

Types

Name	Description
`value_type`

Member Functions

Name	Description
`ch_delim_rule` [constructor]
`parse`

Synopsis

Declared in <include/boost/url/grammar/delim_rule.hpp>


using value_type = core::string_view;

Synopsis

Declared in <include/boost/url/grammar/delim_rule.hpp>


constexpr
ch_delim_rule(char ch) noexcept;

Synopsis

Declared in <include/boost/url/grammar/delim_rule.hpp>


system::result<    _implementation-defined_>
parse(
    char const*& it,
    char const* end) const noexcept;

Synopsis

Declared in <include/boost/url/grammar/delim_rule.hpp>


template<class CharSet>
struct cs_delim_rule;

Types

Name	Description
`value_type`

Member Functions

Name	Description
`cs_delim_rule` [constructor]
`parse`

Synopsis

Declared in <include/boost/url/grammar/delim_rule.hpp>


using value_type = core::string_view;

Synopsis

Declared in <include/boost/url/grammar/delim_rule.hpp>


constexpr
cs_delim_rule(CharSet const& cs) noexcept;

Synopsis

Declared in <include/boost/url/grammar/delim_rule.hpp>


system::result<    _implementation-defined_>
parse(
    char const*& it,
    char const* end) const noexcept;

Synopsis

Declared in <include/boost/url/grammar/digit_chars.hpp>


struct digit_chars_t;

Member Functions

Name	Description
`operator()`

Synopsis

Declared in <include/boost/url/grammar/digit_chars.hpp>


constexpr
bool
operator()(char c) const noexcept;

Synopsis

Declared in <include/boost/url/grammar/hexdig_chars.hpp>


struct hexdig_chars_t;

Member Functions

Name	Description
`operator()`	Return true if c is in the character set.

Return true if c is in the character set.

Synopsis

Declared in <include/boost/url/grammar/hexdig_chars.hpp>


constexpr
bool
operator()(char c) const noexcept;

Synopsis

Declared in <include/boost/url/grammar/not_empty_rule.hpp>


template<class R>
struct not_empty_rule_t;

Types

Name	Description
`value_type`

Member Functions

Name	Description
`not_empty_rule_t` [constructor]
`parse`

Synopsis

Declared in <include/boost/url/grammar/not_empty_rule.hpp>


using value_type = R::value_type;

Synopsis

Declared in <include/boost/url/grammar/not_empty_rule.hpp>


system::result<    _implementation-defined_>
parse(
    char const*& it,
    char const* end) const;

Synopsis

Declared in <include/boost/url/grammar/not_empty_rule.hpp>


constexpr
not_empty_rule_t(R const& r) noexcept;

Synopsis

Declared in <include/boost/url/grammar/parse.hpp>


template<class Rule>
struct rule_ref;

Types

Name	Description
`value_type`

Member Functions

Name	Description
`parse`

Data Members

Name	Description
`r_`

Synopsis

Declared in <include/boost/url/grammar/parse.hpp>


Rule const& r_;

Synopsis

Declared in <include/boost/url/grammar/parse.hpp>


using value_type = Rule::value_type;

Synopsis

Declared in <include/boost/url/grammar/parse.hpp>


system::result<    _implementation-defined_>
parse(
    char const*& it,
    char const* end) const;

Synopsis

Declared in <include/boost/url/grammar/optional_rule.hpp>


template<class Rule>
struct optional_rule_t;

Types

Name	Description
`value_type`

Member Functions

Name	Description
`optional_rule_t` [constructor]
`parse`

Synopsis

Declared in <include/boost/url/grammar/optional_rule.hpp>


using value_type = boost::optional<Rule::value_type>;

Synopsis

Declared in <include/boost/url/grammar/optional_rule.hpp>


system::result<    _implementation-defined_>
parse(
    char const*& it,
    char const* end) const;

Synopsis

Declared in <include/boost/url/grammar/optional_rule.hpp>


constexpr
optional_rule_t(Rule const& r) noexcept;

Synopsis

Declared in <include/boost/url/grammar/range_rule.hpp>


template<
    class R0,
    class R1 = void>
struct range_rule_t;

Types

Name	Description
`value_type`

Member Functions

Name	Description
`parse`
`range_rule_t` [constructor]

Synopsis

Declared in <include/boost/url/grammar/range_rule.hpp>


using value_type = range<R0::value_type>;

Synopsis

Declared in <include/boost/url/grammar/range_rule.hpp>


system::result<    _implementation-defined_>
parse(
    char const*& it,
    char const* end) const;

Synopsis

Declared in <include/boost/url/grammar/range_rule.hpp>


constexpr
range_rule_t(
    R0 const& first,
    R1 const& next,
    std::size_t N,
    std::size_t M) noexcept;

Synopsis

Declared in <include/boost/url/grammar/range_rule.hpp>


template<class R>
struct range_rule_t<R>;

Types

Name	Description
`value_type`

Member Functions

Name	Description
`parse`
`range_rule_t` [constructor]

Synopsis

Declared in <include/boost/url/grammar/range_rule.hpp>


using value_type = range<R::value_type>;

Synopsis

Declared in <include/boost/url/grammar/range_rule.hpp>


system::result<    _implementation-defined_>
parse(
    char const*& it,
    char const* end) const;

Synopsis

Declared in <include/boost/url/grammar/range_rule.hpp>


constexpr
range_rule_t(
    R const& next,
    std::size_t N,
    std::size_t M) noexcept;

Synopsis

Declared in <include/boost/url/grammar/token_rule.hpp>


template<class CharSet>
struct token_rule_t;

Types

Name	Description
`value_type`

Member Functions

Name	Description
`parse`
`token_rule_t` [constructor]

Synopsis

Declared in <include/boost/url/grammar/token_rule.hpp>


using value_type = core::string_view;

Synopsis

Declared in <include/boost/url/grammar/token_rule.hpp>


system::result<    _implementation-defined_>
parse(
    char const*& it,
    char const* end) const noexcept;

Synopsis

Declared in <include/boost/url/grammar/token_rule.hpp>


constexpr
token_rule_t(CharSet const& cs) noexcept;

Synopsis

Declared in <include/boost/url/grammar/tuple_rule.hpp>


template<
    class R0,
    class... Rn>
class tuple_rule_t;

Types

Name	Description
`value_type`

Member Functions

Name	Description
`parse`
`tuple_rule_t` [constructor]

Synopsis

Declared in <include/boost/url/grammar/tuple_rule.hpp>


using value_type = mp11::mp_eval_if_c<IsList,     _implementation-defined_, mp_first,     _implementation-defined_>;

Synopsis

Declared in <include/boost/url/grammar/tuple_rule.hpp>


constexpr
tuple_rule_t(
    R0 const& r0,
    Rn const&... rn) noexcept;

Synopsis

Declared in <include/boost/url/grammar/tuple_rule.hpp>


system::result<    _implementation-defined_>
parse(
    char const*& it,
    char const* end) const;

Synopsis

Declared in <include/boost/url/grammar/tuple_rule.hpp>


template<class Rule>
struct squelch_rule_t
    : empty_value<Rule>;

Types

Name	Description
`value_type`

Member Functions

Name	Description
`parse`
`squelch_rule_t` [constructor]

Synopsis

Declared in <include/boost/url/grammar/tuple_rule.hpp>


using value_type = void;

Synopsis

Declared in <include/boost/url/grammar/tuple_rule.hpp>


constexpr
squelch_rule_t(Rule const& r) noexcept;

Synopsis

Declared in <include/boost/url/grammar/tuple_rule.hpp>


system::result<    _implementation-defined_>
parse(
    char const*& it,
    char const* end) const;

Synopsis

Declared in <include/boost/url/grammar/variant_rule.hpp>


template<
    class R0,
    class... Rn>
class variant_rule_t;

Types

Name	Description
`value_type`

Member Functions

Name	Description
`parse`
`variant_rule_t` [constructor]

Synopsis

Declared in <include/boost/url/grammar/variant_rule.hpp>


using value_type = variant2::variant<R0::value_type, Rn::value_type...>;

Synopsis

Declared in <include/boost/url/grammar/variant_rule.hpp>


system::result<    _implementation-defined_>
parse(
    char const*& it,
    char const* end) const;

Synopsis

Declared in <include/boost/url/grammar/variant_rule.hpp>


constexpr
variant_rule_t(
    R0 const& r0,
    Rn const&... rn) noexcept;

Synopsis

Declared in <include/boost/url/grammar/vchars.hpp>


struct vchars_t;

Member Functions

Name	Description
`operator()`

Synopsis

Declared in <include/boost/url/grammar/vchars.hpp>


constexpr
bool
operator()(char c) const noexcept;

Synopsis

Declared in <include/boost/url/grammar/all_chars.hpp>


struct all_chars_t;

Member Functions

Name	Description
`all_chars_t` [constructor]
`operator()`

Synopsis

Declared in <include/boost/url/grammar/all_chars.hpp>


constexpr
all_chars_t() noexcept = default;

Synopsis

Declared in <include/boost/url/grammar/all_chars.hpp>


constexpr
bool
operator()(char) const noexcept;

The set of letters and digits

Synopsis

Declared in <include/boost/url/grammar/alnum_chars.hpp>


constexpr
    _implementation-defined_ alnum_chars = {};

Description

Character sets are used with rules and the

functions find_if and find_if_not .


system::result< core::string_view > = parse( "Johnny42", token_rule( alnumchars ) );


ALNUM       = ALPHA / DIGIT

ALPHA       = %x41-5A / %x61-7A
            ; A-Z / a-z

DIGIT       = %x30-39
            ; 0-9

B.1. Core Rules (rfc5234)

Synopsis

Declared in <include/boost/url/grammar/alpha_chars.hpp>


constexpr
    _implementation-defined_ alpha_chars = alpha_chars{};

Description

Character sets are used with rules and the

functions find_if and find_if_not .


system::result< core::string_view > rv = parse( "JohnDoe", token_rule( alpha_chars ) );


ALPHA       = %x41-5A / %x61-7A
            ; A-Z / a-z

B.1. Core Rules (rfc5234)

Types

Name	Description
`aligned_storage_impl`
`ci_equal`
`ci_hash`
`ci_less`
`is_charset`
`is_charset<T, void_t<decltype(std::declval<bool&>() = std::declval<T const&>().operator()( std::declval<char>()))>>`
`is_rule`
`is_rule<T, void_t<decltype(std::declval<system::result<typename T::value_type>&>() = std::declval<T const&>().parse( std::declval<char const&>(), std::declval<char const>()))>>`

Functions

Name	Description
`nearest_pow2`
`recycled_add`
`recycled_add_impl`
`recycled_remove`
`recycled_remove_impl`

Synopsis

Declared in <include/boost/url/grammar/charset.hpp>


template<
    class T,
    class = void>
struct is_charset
    : std::false_type;

Synopsis

Declared in <include/boost/url/grammar/charset.hpp>


template<class T>
struct is_charset<T, void_t<decltype(std::declval<bool&>() =
        std::declval<T const&>().operator()(
            std::declval<char>()))>>
    : std::true_type;

Synopsis

Declared in <include/boost/url/grammar/ci_string.hpp>


struct ci_hash;

Types

Name	Description
`is_transparent`

Member Functions

Name	Description
`operator()`

Synopsis

Declared in <include/boost/url/grammar/ci_string.hpp>


using is_transparent = void;

Synopsis

Declared in <include/boost/url/grammar/ci_string.hpp>


std::size_t
operator()(core::string_view s) const noexcept;

Synopsis

Declared in <include/boost/url/grammar/ci_string.hpp>


struct ci_equal;

Types

Name	Description
`is_transparent`

Member Functions

Name	Description
`operator()`

Synopsis

Declared in <include/boost/url/grammar/ci_string.hpp>


using is_transparent = void;

Synopsis

Declared in <include/boost/url/grammar/ci_string.hpp>


template<
    class String0,
    class String1>
bool
operator()(
    String0 s0,
    String1 s1) const noexcept;

Synopsis

Declared in <include/boost/url/grammar/ci_string.hpp>


struct ci_less;

Types

Name	Description
`is_transparent`

Member Functions

Name	Description
`operator()`

Synopsis

Declared in <include/boost/url/grammar/ci_string.hpp>


using is_transparent = void;

Synopsis

Declared in <include/boost/url/grammar/ci_string.hpp>


std::size_t
operator()(
    core::string_view s0,
    core::string_view s1) const noexcept;

Synopsis

Declared in <include/boost/url/grammar/type_traits.hpp>


template<
    class T,
    class = void>
struct is_rule
    : std::false_type;

Synopsis

Declared in <include/boost/url/grammar/type_traits.hpp>


template<class T>
struct is_rule<T, void_t<decltype(std::declval<system::result<typename T::value_type>&>() =
        std::declval<T const&>().parse(
            std::declval<char const*&>(),
            std::declval<char const*>()))>>
    : std::is_nothrow_copy_constructible<T>;

Synopsis

Declared in <include/boost/url/grammar/detail/recycled.hpp>


template<
    std::size_t Size,
    std::size_t Align>
struct aligned_storage_impl;

Member Functions

Name	Description
`addr`

Synopsis

Declared in <include/boost/url/grammar/detail/recycled.hpp>


void*
addr() noexcept;

» more...


void const*
addr() const noexcept;

» more...

Synopsis

Declared in <include/boost/url/grammar/detail/recycled.hpp>


void*
addr() noexcept;

Synopsis

Declared in <include/boost/url/grammar/detail/recycled.hpp>


void const*
addr() const noexcept;

Synopsis

Declared in <include/boost/url/grammar/detail/recycled.hpp>


constexpr
std::size_t
nearest_pow2(
    std::size_t x,
    std::size_t f = 0) noexcept;

Synopsis

Declared in <include/boost/url/grammar/detail/recycled.hpp>


void
recycled_add_impl(std::size_t) noexcept;

Synopsis

Declared in <include/boost/url/grammar/detail/recycled.hpp>


void
recycled_remove_impl(std::size_t) noexcept;

Synopsis

Declared in <include/boost/url/grammar/detail/recycled.hpp>


void
recycled_add(std::size_t) noexcept;

Synopsis

Declared in <include/boost/url/grammar/detail/recycled.hpp>


void
recycled_remove(std::size_t) noexcept;

Alias for `std::true_type` if T satisfies CharSet .

Synopsis

Declared in <include/boost/url/grammar/charset.hpp>


template<class T>
using is_charset =     _see-below_;

Description

This metafunction determines if the type `T` meets these requirements of CharSet :

An instance of `T` is invocable with this equivalent function signature:


bool T::operator()( char ) const noexcept;

Use with `enable_if` on the return value:


template< class CharSet >
typename std::enable_if< is_charset::value >::type
func( CharSet const& cs );

Template Parameters

Name	Description
T	the type to check.

Find the first character in the string that is in the set.

Synopsis

Declared in <include/boost/url/grammar/charset.hpp>


template<class CharSet>
char const*
find_if(
    char const const* first,
    char const const* last,
    CharSet const& cs) noexcept;

Description

Throws nothing.

Return Value

A pointer to the found character, otherwise the value `last`.

Parameters

Name	Description
first	A pointer to the first character in the string to search.
last	A pointer to one past the last character in the string to search.
cs	The character set to use.

Synopsis

Declared in <include/boost/url/grammar/charset.hpp>


template<class CharSet>
char const*
find_if_not(
    char const const* first,
    char const const* last,
    CharSet const& cs) noexcept;

Description

Throws nothing.

Return Value

A pointer to the found character, otherwise the value `last`.

Parameters

Name	Description
first	A pointer to the first character in the string to search.
last	A pointer to one past the last character in the string to search.
cs	The character set to use.

Synopsis

Declared in <include/boost/url/grammar/charset.hpp>


template<class CharSet>
constexpr
    _implementation-defined_
ref(CharSet const& cs) noexcept;

» more...


template<class Rule>
constexpr
    _implementation-defined_
ref(Rule const& r) noexcept;

» more...

Description

This function returns a character set which references the specified object. This is used to reduce the number of bytes of storage (`sizeof`) required by a combinator when it stores a copy of the object. Ownership of the object is not transferred; the caller is responsible for ensuring the lifetime of the object is extended until it is no longer referenced. For best results, `ref` should only be used with compile-time constants.

Parameters

Name	Description
r	The rule to use

Return a reference to a character set

Synopsis

Declared in <include/boost/url/grammar/charset.hpp>


template<class CharSet>
constexpr
    _implementation-defined_
ref(CharSet const& cs) noexcept;

Description

Return a reference to a rule

Synopsis

Declared in <include/boost/url/grammar/parse.hpp>


template<class Rule>
constexpr
    _implementation-defined_
ref(Rule const& r) noexcept;

Description

This function returns a rule which references the specified object. This is used to reduce the number of bytes of storage (`sizeof`) required by a combinator when it stores a copy of the object. Ownership of the object is not transferred; the caller is responsible for ensuring the lifetime of the object is extended until it is no longer referenced. For best results, `ref` should only be used with compile-time constants.

Parameters

Name	Description
r	The rule to use

Return c converted to lowercase

Synopsis

Declared in <include/boost/url/grammar/ci_string.hpp>


constexpr
char
to_lower(char c) noexcept;

Description

This function returns the character, converting it to lowercase if it is uppercase. The function is defined only for low-ASCII characters.


assert( to_lower( 'A' ) == 'a' );

Throws nothing.

Return Value

The converted character

Parameters

Name	Description
c	The character to convert

Synopsis

Declared in <include/boost/url/grammar/ci_string.hpp>


constexpr
char
to_upper(char c) noexcept;

Description

This function returns the character, converting it to uppercase if it is lowercase. The function is defined only for low-ASCII characters.


assert( to_upper( 'a' ) == 'A' );

Throws nothing.

Return Value

The converted character

Parameters

Name	Description
c	The character to convert

Synopsis

Declared in <include/boost/url/grammar/ci_string.hpp>


int
ci_compare(
    core::string_view s0,
    core::string_view s1) noexcept;

Description

This returns the lexicographical comparison of two strings, ignoring case. The function is defined only for strings containing low-ASCII characters.


assert( ci_compare( "boost", "Boost" ) == 0 );

Throws nothing.

Return Value

0 if the strings are equal, -1 if `s0` is less than `s1`, or 1 if `s0` is greater than s1.

Parameters

Name	Description
s0	The first string
s1	The second string

Synopsis

Declared in <include/boost/url/grammar/ci_string.hpp>


std::size_t
ci_digest(core::string_view s) noexcept;

Description

The hash function is non-cryptographic and not hardened against algorithmic complexity attacks. Returned digests are suitable for usage in unordered containers. The function is defined only for strings containing low-ASCII characters.

Return Value

The digest

Parameters

Name	Description
s	The string

Return true if s0 equals s1 using case-insensitive comparison

Synopsis

Declared in <include/boost/url/grammar/ci_string.hpp>


template<
    class String0,
    class String1>
bool
ci_is_equal(
    String0 const& s0,
    String1 const& s1);

» more...


bool
ci_is_equal(
    core::string_view s0,
    core::string_view s1) noexcept;

» more...

Description

The function is defined only for strings containing low-ASCII characters.


assert( ci_is_equal( "Boost", "boost" ) );

Synopsis

Declared in <include/boost/url/grammar/ci_string.hpp>


template<
    class String0,
    class String1>
bool
ci_is_equal(
    String0 const& s0,
    String1 const& s1);

Description

The function is defined only for strings containing low-ASCII characters.


assert( ci_is_equal( "Boost", "boost" ) );

Synopsis

Declared in <include/boost/url/grammar/ci_string.hpp>


bool
ci_is_equal(
    core::string_view s0,
    core::string_view s1) noexcept;

Description

The function is defined only for strings containing low-ASCII characters.


assert( ci_is_equal( "Boost", "boost" ) );

Synopsis

Declared in <include/boost/url/grammar/ci_string.hpp>


bool
ci_is_less(
    core::string_view s0,
    core::string_view s1) noexcept;

Description

The comparison algorithm implements a case-insensitive total order on the set of all strings; however, it is not a lexicographical comparison. The function is defined only for strings containing low-ASCII characters.


assert( ! ci_is_less( "Boost", "boost" ) );

Synopsis

Declared in <include/boost/url/grammar/ci_string.hpp>


using ci_hash =     _see-below_;

Description

The hash function is non-cryptographic and not hardened against algorithmic complexity attacks. This is a suitable hash function for unordered containers. The function is defined only for strings containing low-ASCII characters.


boost::unordered_map< std::string, std::string, ci_hash, ci_equal > m1;

std::unordered_map  < std::string, std::string, ci_hash, ci_equal > m2; // (since C++20)

Synopsis

Declared in <include/boost/url/grammar/ci_string.hpp>


using ci_equal =     _see-below_;

Description

The function object returns `true` when two strings are equal, ignoring case. This is a suitable equality predicate for unordered containers. The function is defined only for strings containing low-ASCII characters.


boost::unordered_map< std::string, std::string, ci_hash, ci_equal > m1;

std::unordered_map  < std::string, std::string, ci_hash, ci_equal > m2; // (since C++20)

Synopsis

Declared in <include/boost/url/grammar/ci_string.hpp>


using ci_less =     _see-below_;

Description

The comparison algorithm implements a case-insensitive total order on the set of all ASCII strings; however, it is not a lexicographical comparison. This is a suitable predicate for ordered containers. The function is defined only for strings containing low-ASCII characters.


boost::container::map< std::string, std::string, ci_less > m1;

std::map< std::string, std::string, ci_less > m2; // (since C++14)

Synopsis

Declared in <include/boost/url/grammar/dec_octet_rule.hpp>


constexpr
    _implementation-defined_ dec_octet_rule = {};

Description

A decimal octet is precise way of saying a number from 0 to 255. These are commonly used in IPv4 addresses.


using value_type = unsigned char;

Rules are used with the function

parse .


system::result< unsigned char > rv = parse( "255", dec_octet_rule );


dec-octet   = DIGIT                 ; 0-9
            / %x31-39 DIGIT         ; 10-99
            / "1" 2DIGIT            ; 100-199
            / "2" %x30-34 DIGIT     ; 200-249
            / "25" %x30-35          ; 250-255

3.2.2. Host (rfc3986)

Synopsis

Declared in <include/boost/url/grammar/error.hpp>


enum error : int;

Members

Name	Description
need_more	More input is needed to match the rule
mismatch	The rule did not match the input.
end_of_range	A rule reached the end of a range
leftover	Leftover input remaining after match.
invalid	A rule encountered unrecoverable invalid input.
out_of_range	An integer overflowed during parsing.
syntax	An unspecified syntax error was found.

Synopsis

Declared in <include/boost/url/grammar/error.hpp>


need_more = 1

Description

A rule reached the end of the input, resulting in a partial match. The error is recoverable; the caller may obtain more input if possible and attempt to parse the character buffer again. Custom rules should only return this error if it is completely unambiguous that the rule cannot be matched without more input.

The rule did not match the input.

Synopsis

Declared in <include/boost/url/grammar/error.hpp>


mismatch

Description

This error is returned when a rule fails to match the input. The error is recoverable; the caller may rewind the input pointer and attempt to parse again using a different rule.

A rule reached the end of a range

Synopsis

Declared in <include/boost/url/grammar/error.hpp>


end_of_range

Description

This indicates that the input was consumed when parsing a range . The range_rule avoids rewinding the input buffer when this error is returned. Thus the consumed characters are be considered part of the range without contributing additional elements.

Leftover input remaining after match.

Synopsis

Declared in <include/boost/url/grammar/error.hpp>


leftover

A rule encountered unrecoverable invalid input.

Synopsis

Declared in <include/boost/url/grammar/error.hpp>


invalid

Description

This error is returned when input is matching but one of the requirements is violated. For example if a percent escape is found, but one or both characters that follow are not valid hexadecimal digits. This is usually an unrecoverable error.

An integer overflowed during parsing.

Synopsis

Declared in <include/boost/url/grammar/error.hpp>


out_of_range

An unspecified syntax error was found.

Synopsis

Declared in <include/boost/url/grammar/error.hpp>


syntax

Error conditions for errors received from rules

Synopsis

Declared in <include/boost/url/grammar/error.hpp>


enum condition : int;

Members

Name	Description
fatal	A fatal error in syntax was encountered.

Synopsis

Declared in <include/boost/url/grammar/error.hpp>


fatal = 1

Description

This indicates that parsing cannot continue.

Determine if T meets the requirements of Rule

Synopsis

Declared in <include/boost/url/grammar/type_traits.hpp>


template<class T>
using is_rule =     _see-below_;

Description

This is an alias for `std::true_type` if `T` meets the requirements, otherwise it is an alias for `std::false_type`.


struct U
{
    struct value_type;

    auto
    parse(
        char const*& it,
        char const* end) const ->
            system::result
};

static_assert( is_rule::value, "Requirements not met" );

Synopsis

Declared in <include/boost/url/grammar/delim_rule.hpp>


constexpr
    _implementation-defined_
delim_rule(char ch) noexcept;

» more...


template<class CharSet>
constexpr
    _implementation-defined_
delim_rule(CharSet const& cs) noexcept;

» more...

Description

This matches the specified character. The value is a reference to the character in the underlying buffer, expressed as a `core::string_view`. The function squelch may be used to turn this into `void` instead. If there is no more input, the error code error::need_more is returned.


using value_type = core::string_view;

Rules are used with the function

parse .


system::result< core::string_view > rv = parse( ".", delim_rule('.') );


char        = %00-FF

Parameters

Name	Description
ch	The character to match
cs	The character set to use.

Synopsis

Declared in <include/boost/url/grammar/delim_rule.hpp>


constexpr
    _implementation-defined_
delim_rule(char ch) noexcept;

Description


using value_type = core::string_view;

Rules are used with the function

parse .


system::result< core::string_view > rv = parse( ".", delim_rule('.') );


char        = %00-FF

Parameters

Name	Description
ch	The character to match

Synopsis

Declared in <include/boost/url/grammar/delim_rule.hpp>


template<class CharSet>
constexpr
    _implementation-defined_
delim_rule(CharSet const& cs) noexcept;

Description

This matches exactly one character which belongs to the specified character set. The value is a reference to the character in the underlying buffer, expressed as a `core::string_view`. The function squelch may be used to turn this into `void` instead. If there is no more input, the error code error::need_more is returned.


using value_type = core::string_view;

Rules are used with the function

parse .


system::result< core::string_view > rv = parse( "X", delim_rule( alpha_chars ) );

Parameters

Name	Description
cs	The character set to use.

Synopsis

Declared in <include/boost/url/grammar/digit_chars.hpp>


constexpr
    _implementation-defined_ digit_chars = {};

Description

Character sets are used with rules and the

functions find_if and find_if_not .


system::result< core::string_view > rv = parse( "2022", token_rule( digit_chars ) );


DIGIT       = %x30-39
            ; 0-9

B.1. Core Rules (rfc5234)

Synopsis

Declared in <include/boost/url/grammar/hexdig_chars.hpp>


constexpr
    _implementation-defined_ hexdig_chars = {};

Description

Character sets are used with rules and the

functions find_if and find_if_not .


system::result< core::string_view > rv = parse( "8086FC19", token_rule( hexdig_chars ) );


HEXDIG      = DIGIT
            / "A" / "B" / "C" / "D" / "E" / "F"
            / "a" / "b" / "c" / "d" / "e" / "f"

NOTE

The RFCs are inconsistent on the case sensitivity of hexadecimal digits. Existing uses suggest case-insensitivity is a de-facto standard.

B.1. Core Rules (rfc5234)

1.2. Syntax Notation (rfc7230)

2.3. Uppercase or Lowercase (rfc5952)

4.3. Lowercase (rfc5952)

Synopsis

Declared in <include/boost/url/grammar/hexdig_chars.hpp>


signed char
hexdig_value(char ch) noexcept;

Description

This function returns the decimal value of a hexadecimal character, or -1 if the argument is not a valid hexadecimal digit.


HEXDIG      = DIGIT
            / "A" / "B" / "C" / "D" / "E" / "F"
            / "a" / "b" / "c" / "d" / "e" / "f"

Return Value

The decimal value or -1

Parameters

Name	Description
ch	The character to check

Synopsis

Declared in <include/boost/url/grammar/literal_rule.hpp>


class literal_rule;

Types

Name	Description
`value_type`

Member Functions

Name	Description
`literal_rule` [constructor]
`parse`

Synopsis

Declared in <include/boost/url/grammar/literal_rule.hpp>


using value_type = core::string_view;

Synopsis

Declared in <include/boost/url/grammar/literal_rule.hpp>


constexpr
explicit
literal_rule(char const* s) noexcept;

Synopsis

Declared in <include/boost/url/grammar/literal_rule.hpp>


system::result<value_type>
parse(
    char const*& it,
    char const* end) const noexcept;

A set of characters

Synopsis

Declared in <include/boost/url/grammar/lut_chars.hpp>


class lut_chars;

Member Functions

Name	Description
`lut_chars` [constructor]	Constructor
`operator()`	Return true if ch is in the character set.
`operator~`	Return a new character set which is the complement of another character set.

Friends

Name	Description
`operator+`	Return the union of two character sets.
`operator-`	Return a new character set by subtracting

Description

The characters defined by instances of this set are provided upon construction. The `constexpr` implementation allows these to become compile-time constants.

Character sets are used with rules and the

functions find_if and find_if_not .


constexpr lut_chars vowel_chars = "AEIOU" "aeiou";

system::result< core::string_view > rv = parse( "Aiea", token_rule( vowel_chars ) );

Synopsis

Declared in <include/boost/url/grammar/lut_chars.hpp>


constexpr
lut_chars(char ch) noexcept;

» more...


constexpr
lut_chars(char const* s) noexcept;

» more...


template<
    class Pred,
    class = void>
constexpr
lut_chars(Pred const& pred) noexcept;

» more...

Description

This function constructs a character set which has as a single member, the character `ch`.


constexpr lut_chars asterisk( '*' );

Constant.

Throws nothing.

Parameters

Name	Description
ch	A character.
s	A null-terminated string.

Constructor

Synopsis

Declared in <include/boost/url/grammar/lut_chars.hpp>


constexpr
lut_chars(char ch) noexcept;

Description

This function constructs a character set which has as a single member, the character `ch`.


constexpr lut_chars asterisk( '*' );

Constant.

Throws nothing.

Parameters

Name	Description
ch	A character.

Constructor

Synopsis

Declared in <include/boost/url/grammar/lut_chars.hpp>


constexpr
lut_chars(char const* s) noexcept;

Description

This function constructs a character set which has as members, all of the characters present in the null-terminated string `s`.


constexpr lut_chars digits = "0123456789";

Linear in `::strlen(s)`, or constant

if `s` is a constant expression.

Throws nothing.

Parameters

Name	Description
s	A null-terminated string.

Synopsis

Declared in <include/boost/url/grammar/lut_chars.hpp>


template<
    class Pred,
    class = void>
constexpr
lut_chars(Pred const& pred) noexcept;

Return true if ch is in the character set.

Synopsis

Declared in <include/boost/url/grammar/lut_chars.hpp>


constexpr
bool
operator()(unsigned char ch) const noexcept;

» more...


constexpr
bool
operator()(char ch) const noexcept;

» more...

Description

This function returns true if the character `ch` is in the set, otherwise it returns false.

Constant.

Throws nothing.

Parameters

Name	Description
ch	The character to test.

Return true if ch is in the character set.

Synopsis

Declared in <include/boost/url/grammar/lut_chars.hpp>


constexpr
bool
operator()(unsigned char ch) const noexcept;

Description

This function returns true if the character `ch` is in the set, otherwise it returns false.

Constant.

Throws nothing.

Parameters

Name	Description
ch	The character to test.

Return true if ch is in the character set.

Synopsis

Declared in <include/boost/url/grammar/lut_chars.hpp>


constexpr
bool
operator()(char ch) const noexcept;

Description

This function returns true if the character `ch` is in the set, otherwise it returns false.

Constant.

Throws nothing.

Parameters

Name	Description
ch	The character to test.

Return the union of two character sets.

Synopsis

Declared in <include/boost/url/grammar/lut_chars.hpp>


friend
constexpr
lut_chars
operator+(
    lut_chars const& cs0,
    lut_chars const& cs1) noexcept;

Description

This function returns a new character set which contains all of the characters in `cs0` as well as all of the characters in `cs`.

This creates a character set which

includes all letters and numbers


constexpr lut_chars alpha_chars(
    "ABCDEFGHIJKLMNOPQRSTUVWXYZ"
    "abcdefghijklmnopqrstuvwxyz");

constexpr lut_chars alnum_chars = alpha_chars + "0123456789";

Constant.

Return Value

The new character set.

Parameters

Name	Description
cs0	A character to join
cs1	A character to join

Return a new character set by subtracting

Synopsis

Declared in <include/boost/url/grammar/lut_chars.hpp>


friend
constexpr
lut_chars
operator-(
    lut_chars const& cs0,
    lut_chars const& cs1) noexcept;

Description

This function returns a new character set which is formed from all of the characters in `cs0` which are not in `cs`.

This statement declares a character set

containing all the lowercase letters which are not vowels:


constexpr lut_chars consonants = lut_chars("abcdefghijklmnopqrstuvwxyz") - "aeiou";

Constant.

Return Value

The new character set.

Parameters

Name	Description
cs0	A character set to join.
cs1	A character set to join.

Return a new character set which is the complement of another character set.

Synopsis

Declared in <include/boost/url/grammar/lut_chars.hpp>


constexpr
lut_chars
operator~() const noexcept;

Description

This function returns a new character set which contains all of the characters that are not in `*this`.

This statement declares a character set

containing everything but vowels:


constexpr lut_chars not_vowels = ~lut_chars( "AEIOU" "aeiou" );

Constant.

Throws nothing.

Return Value

The new character set.

Return the union of two character sets.

Synopsis

Declared in <include/boost/url/grammar/lut_chars.hpp>


constexpr
lut_chars
operator+(
    lut_chars const& cs0,
    lut_chars const& cs1) noexcept;

Description

This function returns a new character set which contains all of the characters in `cs0` as well as all of the characters in `cs`.

This creates a character set which

includes all letters and numbers


constexpr lut_chars alpha_chars(
    "ABCDEFGHIJKLMNOPQRSTUVWXYZ"
    "abcdefghijklmnopqrstuvwxyz");

constexpr lut_chars alnum_chars = alpha_chars + "0123456789";

Constant.

Return Value

The new character set.

Parameters

Name	Description
cs0	A character to join
cs1	A character to join

Return a new character set by subtracting

Synopsis

Declared in <include/boost/url/grammar/lut_chars.hpp>


constexpr
lut_chars
operator-(
    lut_chars const& cs0,
    lut_chars const& cs1) noexcept;

Description

This function returns a new character set which is formed from all of the characters in `cs0` which are not in `cs`.

This statement declares a character set

containing all the lowercase letters which are not vowels:


constexpr lut_chars consonants = lut_chars("abcdefghijklmnopqrstuvwxyz") - "aeiou";

Constant.

Return Value

The new character set.

Parameters

Name	Description
cs0	A character set to join.
cs1	A character set to join.

Match another rule, if the result is not empty

Synopsis

Declared in <include/boost/url/grammar/not_empty_rule.hpp>


template<class Rule>
constexpr
    _implementation-defined_
not_empty_rule(Rule const& r);

Description

This adapts another rule such that when an empty string is successfully parsed, the result is an error.


using value_type = typename Rule::value_type;

Rules are used with the function

parse .


system::result< decode_view > rv = parse( "Program%20Files",
    not_empty_rule( pct_encoded_rule( unreserved_chars ) ) );

Parameters

Name	Description
r	The rule to match

Synopsis

Declared in <include/boost/url/grammar/parse.hpp>


template<class Rule>
system::result<Rule::value_type>
parse(
    char const*& it,
    char const* end,
    Rule const& r);

» more...


template<class Rule>
system::result<Rule::value_type>
parse(
    core::string_view s,
    Rule const& r);

» more...

Return Value

The parsed value upon success, otherwise an error.

Parameters

Name	Description
it	A pointer to the start. The caller's variable is changed to reflect the amount of input consumed.
end	A pointer to the end.
r	The rule to use
s	The input string

Parse a character buffer using a rule

Synopsis

Declared in <include/boost/url/grammar/parse.hpp>


template<class Rule>
system::result<Rule::value_type>
parse(
    char const*& it,
    char const* end,
    Rule const& r);

Return Value

The parsed value upon success, otherwise an error.

Parameters

Name	Description
it	A pointer to the start. The caller's variable is changed to reflect the amount of input consumed.
end	A pointer to the end.
r	The rule to use

Parse a character buffer using a rule

Synopsis

Declared in <include/boost/url/grammar/parse.hpp>


template<class Rule>
system::result<Rule::value_type>
parse(
    core::string_view s,
    Rule const& r);

Description

This function parses a complete string into the specified sequence of rules. If the string is not completely consumed, an error is returned instead.

Return Value

The parsed value upon success, otherwise an error.

Parameters

Name	Description
s	The input string
r	The rule to use

Match a rule, or the empty string

Synopsis

Declared in <include/boost/url/grammar/optional_rule.hpp>


template<class Rule>
constexpr
    _implementation-defined_
optional_rule(Rule const& r);

Description

Optional BNF elements are denoted with square brackets. If the specified rule returns any error it is treated as if the rule did not match.


using value_type = optional< typename Rule::value_type >;

Rules are used with the function

grammar::parse .


system::result< optional< core::string_view > > rv = parse( "", optional_rule( token_rule( alpha_chars ) ) );


optional     = [ rule ]

3.8. Optional Sequence (rfc5234)

Parameters

Name	Description
r	The rule to match

Synopsis

Declared in <include/boost/url/grammar/range_rule.hpp>


template<class T>
class range;

Types

Name	Description
`const_iterator`	A constant, forward iterator to elements of the range
`const_reference`	The type of each element of the range
`difference_type`	The type used to represent signed integers
`iterator`	A constant, forward iterator to elements of the range
`pointer`	Provided for compatibility, unused
`reference`	The type of each element of the range
`size_type`	The type used to represent unsigned integers
`value_type`	The type of each element of the range

Member Functions

Name	Description
`begin`	Return an iterator to the beginning
`empty`	Return true if the range is empty
`end`	Return an iterator to the end
`operator=`	Assignment
`range` [constructor]	Constructor
`size`	Return the number of elements in the range
`string`	Return the matching part of the string
`~range` [destructor]	Destructor

Description

Objects of this type are forward ranges returned when parsing using the range_rule . Iteration is performed by re-parsing the underlying character buffer. Ownership of the buffer is not transferred; the caller is responsible for ensuring that the lifetime of the buffer extends until it is no longer referenced by the range.

NOTE

The implementation may use temporary, recycled storage for type-erasure. Objects of type `range` are intended to be used ephemerally. That is, for short durations such as within a function scope. If it is necessary to store the range for a long period of time or with static storage duration, it is necessary to copy the contents to an object of a different type.

Template Parameters

Name	Description
T	The value type of the range

Synopsis

Declared in <include/boost/url/grammar/range_rule.hpp>


using value_type = T;

The type of each element of the range

Synopsis

Declared in <include/boost/url/grammar/range_rule.hpp>


using reference = T const&;

The type of each element of the range

Synopsis

Declared in <include/boost/url/grammar/range_rule.hpp>


using const_reference = T const&;

Provided for compatibility, unused

Synopsis

Declared in <include/boost/url/grammar/range_rule.hpp>


using pointer = void const*;

The type used to represent unsigned integers

Synopsis

Declared in <include/boost/url/grammar/range_rule.hpp>


using size_type = std::size_t;

The type used to represent signed integers

Synopsis

Declared in <include/boost/url/grammar/range_rule.hpp>


using difference_type = std::ptrdiff_t;

A constant, forward iterator to elements of the range

Synopsis

Declared in <include/boost/url/grammar/impl/range_rule.hpp>


class iterator;

Types

Name	Description
`difference_type`
`iterator_category`
`pointer`
`reference`
`value_type`

Member Functions

Name	Description
`iterator` [constructor]
`operator!=`
`operator*`
`operator++`
`operator=`
`operator==`

Synopsis

Declared in <include/boost/url/grammar/impl/range_rule.hpp>


using value_type = T;

Synopsis

Declared in <include/boost/url/grammar/impl/range_rule.hpp>


using reference = T const&;

Synopsis

Declared in <include/boost/url/grammar/impl/range_rule.hpp>


using pointer = void const*;

Synopsis

Declared in <include/boost/url/grammar/impl/range_rule.hpp>


using difference_type = std::ptrdiff_t;

Synopsis

Declared in <include/boost/url/grammar/impl/range_rule.hpp>


using iterator_category = std::forward_iterator_tag;

Synopsis

Declared in <include/boost/url/grammar/impl/range_rule.hpp>


iterator() = default;

» more...


iterator(iterator const&) = default;

» more...

Synopsis

Declared in <include/boost/url/grammar/impl/range_rule.hpp>


iterator() = default;

Synopsis

Declared in <include/boost/url/grammar/impl/range_rule.hpp>


iterator(iterator const&) = default;

Synopsis

Declared in <include/boost/url/grammar/impl/range_rule.hpp>


iterator&
operator=(iterator const&) = default;

Synopsis

Declared in <include/boost/url/grammar/impl/range_rule.hpp>


reference
operator*() const noexcept;

Synopsis

Declared in <include/boost/url/grammar/impl/range_rule.hpp>


bool
operator==(iterator const& other) const noexcept;

Synopsis

Declared in <include/boost/url/grammar/impl/range_rule.hpp>


bool
operator!=(iterator const& other) const noexcept;

Synopsis

Declared in <include/boost/url/grammar/impl/range_rule.hpp>


iterator&
operator++() noexcept;

» more...


iterator
operator++(int) noexcept;

» more...

Synopsis

Declared in <include/boost/url/grammar/impl/range_rule.hpp>


iterator&
operator++() noexcept;

Synopsis

Declared in <include/boost/url/grammar/impl/range_rule.hpp>


iterator
operator++(int) noexcept;

A constant, forward iterator to elements of the range

Synopsis

Declared in <include/boost/url/grammar/range_rule.hpp>


using const_iterator = iterator;

Destructor

Synopsis

Declared in <include/boost/url/grammar/range_rule.hpp>


~range();

Constructor

Synopsis

Declared in <include/boost/url/grammar/range_rule.hpp>


range() noexcept;

» more...


range(range&& other) noexcept;

» more...


range(range const& other) noexcept;


range&
operator=(range&& other) noexcept;

» more...


range&
operator=(range const& other) noexcept;

» more...

Description

After the move, this references the same underlying character buffer. Ownership is not transferred; the caller is responsible for ensuring that the lifetime of the buffer extends until it is no longer referenced. The moved-from object becomes as if default-constructed.

Throws nothing.

Assignment

Synopsis

Declared in <include/boost/url/grammar/range_rule.hpp>


range&
operator=(range&& other) noexcept;

Description

Throws nothing.

Assignment

Synopsis

Declared in <include/boost/url/grammar/range_rule.hpp>


range&
operator=(range const& other) noexcept;

Description


template<class Rule>
constexpr
    _implementation-defined_
range_rule(
    Rule const& next,
    std::size_t N = 0,
    std::size_t M = std::size_t(-1)) noexcept;

» more...


template<
    class Rule1,
    class Rule2>
constexpr
    _implementation-defined_
range_rule(
    Rule1 const& first,
    Rule2 const& next,
    std::size_t N = 0,
    std::size_t M = std::size_t(-1)) noexcept;

» more...

Description

Elements are matched using the passed rule. Normally when the rule returns an error, the range ends and the input is rewound to one past the last character that matched successfully. However, if the rule returns the special value error::end_of_range , the input is not rewound. This allows for rules which consume input without producing elements in the range. For example, to relax the grammar for a comma-delimited list by allowing extra commas in between elements.


using value_type = range< typename Rule::value_type >;

Rules are used with the function

parse .


// range    = 1*( ";" token )

system::result< range > rv = parse( ";alpha;xray;charlie",
    range_rule(
        tuple_rule(
            squelch( delim_rule( ';' ) ),
            token_rule( alpha_chars ) ),
        1 ) );


range        = *next

3.6. Variable Repetition (rfc5234)

Parameters

Name	Description
next	The rule to use for matching each element. The range extends until this rule returns an error.
N	The minimum number of elements for the range to be valid. If omitted, this defaults to zero.
M	The maximum number of elements for the range to be valid. If omitted, this defaults to unlimited.
first	The rule to use for matching the first element. If this rule returns an error, the range is empty.

Synopsis

Declared in <include/boost/url/grammar/range_rule.hpp>


template<class Rule>
constexpr
    _implementation-defined_
range_rule(
    Rule const& next,
    std::size_t N = 0,
    std::size_t M = std::size_t(-1)) noexcept;

Description


using value_type = range< typename Rule::value_type >;

Rules are used with the function

parse .


// range    = 1*( ";" token )

system::result< range > rv = parse( ";alpha;xray;charlie",
    range_rule(
        tuple_rule(
            squelch( delim_rule( ';' ) ),
            token_rule( alpha_chars ) ),
        1 ) );


range        = *next

3.6. Variable Repetition (rfc5234)

Parameters

Name	Description
next	The rule to use for matching each element. The range extends until this rule returns an error.
N	The minimum number of elements for the range to be valid. If omitted, this defaults to zero.
M	The maximum number of elements for the range to be valid. If omitted, this defaults to unlimited.

Synopsis

Declared in <include/boost/url/grammar/range_rule.hpp>


template<
    class Rule1,
    class Rule2>
constexpr
    _implementation-defined_
range_rule(
    Rule1 const& first,
    Rule2 const& next,
    std::size_t N = 0,
    std::size_t M = std::size_t(-1)) noexcept;

Description

Two rules are used for match. The rule `first` is used for matching the first element, while the `next` rule is used to match every subsequent element. Normally when the rule returns an error, the range ends and the input is rewound to one past the last character that matched successfully. However, if the rule returns the special value error::end_of_range , the input is not rewound. This allows for rules which consume input without producing elements in the range. For example, to relax the grammar for a comma-delimited list by allowing extra commas in between elements.


using value_type = range< typename Rule::value_type >;

Rules are used with the function

parse .


// range    = [ token ] *( "," token )

system::result< range< core::string_view > > rv = parse( "whiskey,tango,foxtrot",
    range_rule(
        token_rule( alpha_chars ),          // first
        tuple_rule(                      // next
            squelch( delim_rule(',') ),
            token_rule( alpha_chars ) ) ) );


range       = <1>*<1>first
            / first *next

3.6. Variable Repetition (rfc5234)

Parameters

Name	Description
first	The rule to use for matching the first element. If this rule returns an error, the range is empty.
next	The rule to use for matching each subsequent element. The range extends until this rule returns an error.
N	The minimum number of elements for the range to be valid. If omitted, this defaults to zero.
M	The maximum number of elements for the range to be valid. If omitted, this defaults to unlimited.

Synopsis

Declared in <include/boost/url/grammar/recycled.hpp>


template<class T>
using aligned_storage =     _see-below_;

Description


template
struct aligned_storage
{
    /// Return a pointer to the aligned storage area
    void* addr() noexcept;

    /// Return a pointer to the aligned storage area
    void const* addr() const noexcept;
};

A thread-safe collection of instances of T

Synopsis

Declared in <include/boost/url/grammar/recycled.hpp>


template<class T>
class recycled;

Member Functions

Name	Description
`recycled` [constructor]	Constructor
`~recycled` [destructor]	Destructor

Description

Instances of this type may be used to control where recycled instances of T come from when used with recycled_ptr .


static recycled< std::string > bin;

recycled_ptr< std::string > ps( bin );

// Put the string into a known state
ps->clear();

Synopsis

Declared in <include/boost/url/grammar/recycled.hpp>


~recycled();

Description

All recycled instances of T are destroyed. Undefined behavior results if there are any recycled_ptr which reference this recycle bin.

Constructor

Synopsis

Declared in <include/boost/url/grammar/recycled.hpp>


constexpr
recycled() = default;

A pointer to a shared instance of T

Synopsis

Declared in <include/boost/url/grammar/recycled.hpp>


template<class T>
class recycled_ptr;

Member Functions

Name	Description
`acquire`	Return the referenced object
`bin`	Return the referenced recycle bin
`empty`	Return true if this does not reference an object
`get`	Return the referenced object
`operator bool`	Return true if this references an object
`operator*`	Return the referenced object
`operator->`	Return the referenced object
`operator=`	Assignment
`recycled_ptr` [constructor]	Constructor
`release`	Release the referenced object
`~recycled_ptr` [destructor]	Destructor

Description

This is a smart pointer container which can acquire shared ownership of an instance of `T` upon or after construction. The instance is guaranteed to be in a valid, but unknown state. Every recycled pointer references a valid recycle bin.


static recycled< std::string > bin;

recycled_ptr< std::string > ps( bin );

// Put the string into a known state
ps->clear();

Template Parameters

Name	Description
T	the type of object to acquire, which must be DefaultConstructible .

Destructor

Synopsis

Declared in <include/boost/url/grammar/recycled.hpp>


~recycled_ptr();

Description

If this is not empty, shared ownership of the pointee is released. If this was the last reference, the object is returned to the original recycle bin.


this->release();

Constructor

Synopsis

Declared in <include/boost/url/grammar/recycled.hpp>


explicit
recycled_ptr(recycled<T>& bin);

» more...


recycled_ptr(
    recycled<T>& bin,
    std::nullptr_t) noexcept;

» more...


recycled_ptr();

» more...


recycled_ptr(std::nullptr_t) noexcept;

» more...


recycled_ptr(recycled_ptr const& other) noexcept;

» more...


recycled_ptr(recycled_ptr&& other) noexcept;

» more...

Description

Upon construction, this acquires exclusive access to an object of type `T` which is either recycled from the specified bin, or newly allocated. The object is in an unknown but valid state.


static recycled< std::string > bin;

recycled_ptr< std::string > ps( bin );

// Put the string into a known state
ps->clear();


&this->bin() == &bin && ! this->empty()

Parameters

Name	Description
bin	The recycle bin to use
other	The pointer to copy

Synopsis

Declared in <include/boost/url/grammar/recycled.hpp>


explicit
recycled_ptr(recycled<T>& bin);

Description

Upon construction, this acquires exclusive access to an object of type `T` which is either recycled from the specified bin, or newly allocated. The object is in an unknown but valid state.


static recycled< std::string > bin;

recycled_ptr< std::string > ps( bin );

// Put the string into a known state
ps->clear();


&this->bin() == &bin && ! this->empty()

Parameters

Name	Description
bin	The recycle bin to use

Synopsis

Declared in <include/boost/url/grammar/recycled.hpp>


recycled_ptr(
    recycled<T>& bin,
    std::nullptr_t) noexcept;

Description

After construction, this is empty and refers to the specified recycle bin.


static recycled< std::string > bin;

recycled_ptr< std::string > ps( bin, nullptr );

// Acquire a string and put it into a known state
ps->acquire();
ps->clear();


&this->bin() == &bin && this->empty()

Throws nothing.

Parameters

Name	Description
bin	The recycle bin to use

Synopsis

Declared in <include/boost/url/grammar/recycled.hpp>


recycled_ptr();

Description

Upon construction, this acquires exclusive access to an object of type `T` which is either recycled from a global recycle bin, or newly allocated. The object is in an unknown but valid state.


recycled_ptr< std::string > ps;

// Put the string into a known state
ps->clear();


&this->bin() != nullptr && ! this->empty()

Synopsis

Declared in <include/boost/url/grammar/recycled.hpp>


recycled_ptr(std::nullptr_t) noexcept;

Description

After construction, this is empty and refers to a global recycle bin.


recycled_ptr< std::string > ps( nullptr );

// Acquire a string and put it into a known state
ps->acquire();
ps->clear();


&this->bin() != nullptr && this->empty()

Throws nothing.

Synopsis

Declared in <include/boost/url/grammar/recycled.hpp>


recycled_ptr(recycled_ptr const& other) noexcept;

Description

If `other` references an object, the newly constructed pointer acquires shared ownership. Otherwise this is empty. The new pointer references the same recycle bin as `other`.


&this->bin() == &other->bin() && this->get() == other.get()

Throws nothing.

Parameters

Name	Description
other	The pointer to copy

Constructor

Synopsis

Declared in <include/boost/url/grammar/recycled.hpp>


recycled_ptr(recycled_ptr&& other) noexcept;

Description

If `other` references an object, ownership is transferred including a reference to the recycle bin. After the move, the moved-from object is empty.


&this->bin() == &other->bin() && ! this->empty() && other.empty()

Throws nothing.

Parameters

Name	Description
other	The pointer to move from

Assignment

Synopsis

Declared in <include/boost/url/grammar/recycled.hpp>


recycled_ptr&
operator=(recycled_ptr&& other) noexcept;

» more...


recycled_ptr&
operator=(recycled_ptr const& other) noexcept;

» more...

Description

If `other` references an object, ownership is transferred including a reference to the recycle bin. After the move, the moved-from object is empty.


this->release()


&this->bin() == &other->bin()

Throws nothing.

Parameters

Name	Description
other	The pointer to move from

Assignment

Synopsis

Declared in <include/boost/url/grammar/recycled.hpp>


recycled_ptr&
operator=(recycled_ptr&& other) noexcept;

Description

If `other` references an object, ownership is transferred including a reference to the recycle bin. After the move, the moved-from object is empty.


this->release()


&this->bin() == &other->bin()

Throws nothing.

Parameters

Name	Description
other	The pointer to move from

Assignment

Synopsis

Declared in <include/boost/url/grammar/recycled.hpp>


recycled_ptr&
operator=(recycled_ptr const& other) noexcept;

Description

If `other` references an object, this acquires shared ownership and references the same recycle bin as `other`. The previous object if any is released.


this->release()


&this->bin() == &other->bin() && this->get() == other.get()

Throws nothing.

Parameters

Name	Description
other	The pointer to copy from

Return true if this does not reference an object

Synopsis

Declared in <include/boost/url/grammar/recycled.hpp>


bool
empty() const noexcept;

Description

Throws nothing.

Return true if this references an object

Synopsis

Declared in <include/boost/url/grammar/recycled.hpp>


explicit
operator bool() const noexcept;

Description


return ! this->empty();

Throws nothing.

Return the referenced recycle bin

Synopsis

Declared in <include/boost/url/grammar/recycled.hpp>


recycled<T>&
bin() const noexcept;

Description

Throws nothing.

Return the referenced object

Synopsis

Declared in <include/boost/url/grammar/recycled.hpp>


T*
get() const noexcept;

Description

If this is empty, `nullptr` is returned.

Throws nothing.

Return the referenced object

Synopsis

Declared in <include/boost/url/grammar/recycled.hpp>


T*
operator->() const noexcept;

Description

If this is empty, `nullptr` is returned.

Throws nothing.

Return the referenced object

Synopsis

Declared in <include/boost/url/grammar/recycled.hpp>


T&
operator*() const noexcept;

Description


not this->empty()

Return the referenced object

Synopsis

Declared in <include/boost/url/grammar/recycled.hpp>


T&
acquire();

Description

If this references an object, it is returned. Otherwise, exclusive ownership of a new object of type `T` is acquired and returned.


not this->empty()

Release the referenced object

Synopsis

Declared in <include/boost/url/grammar/recycled.hpp>


void
release() noexcept;

Description

If this references an object, it is released to the referenced recycle bin. The pointer continues to reference the same recycle bin.


this->empty()

Throws nothing.

Synopsis

Declared in <include/boost/url/grammar/string_token.hpp>


namespace string_token = boost::urls::string_token;

Common functionality for string views

Synopsis

Declared in <include/boost/url/grammar/string_view_base.hpp>


class string_view_base;

Types

Name	Description
`const_iterator`	The const iterator type
`const_pointer`	The const pointer type
`const_reference`	The const reference type
`const_reverse_iterator`	The const reverse iterator type
`difference_type`	The difference type
`iterator`	The iterator type
`pointer`	The pointer type
`reference`	The reference type
`reverse_iterator`	The reverse iterator type
`size_type`	The size type
`traits_type`	The character traits
`value_type`	The value type

Member Functions

Name	Description
`at`	Access a character
`back`	Return the last character
`begin`	Return an iterator to the beginning
`cbegin`	Return an iterator to the beginning
`cend`	Return an iterator to the end
`compare`	Return the result of comparing to another string
`contains`	Return true if matching characters are found
`copy`	Copy the characters to another buffer
`crbegin`	Return a reverse iterator to the end
`crend`	Return a reverse iterator to the beginning
`data`	Return a pointer to the character buffer
`empty`	Return true if the string is empty
`end`	Return an iterator to the end
`ends_with`	Return true if a matching suffix exists
`find`	Return the position of matching characters
`find_first_not_of`	Return the position of the first non-match
`find_first_of`	Return the position of the first match
`find_last_not_of`	Return the position of the last non-match
`find_last_of`	Return the position of the last match
`front`	Return the first character
`length`	Return the size
`max_size`	Return the maximum allowed size
`operator std::string`	Conversion
`operator core::string_view`	Conversion
`operator[]`	Access a character
`rbegin`	Return a reverse iterator to the end
`rend`	Return a reverse iterator to the beginning
`rfind`	Return the position of matching characters
`size`	Return the size
`starts_with`	Return true if a matching prefix exists
`substr`	Return a view to part of the string

Static Data Members

Name	Description
`npos`	A constant used to represent "no position"

Friends

Name	Description
`operator!=`	Compare two string views for inequality
`operator<`	Compare two string views for less than
`operator<<`	Format a string to an output stream
`operator<=`	Compare two string views for less than or equal
`operator==`	Compare two string views for equality
`operator>`	Compare two string views for greater than
`operator>=`	Compare two string views for greater than or equal

Description

This base class is used to provide common member functions for reference types that behave like string views. This cannot be instantiated directly; Instead, derive from the type and provide constructors which offer any desired preconditions and invariants.

The character traits

Synopsis

Declared in <include/boost/url/grammar/string_view_base.hpp>


typedef std::char_traits<char> traits_type;

The value type

Synopsis

Declared in <include/boost/url/grammar/string_view_base.hpp>


typedef char value_type;

The pointer type

Synopsis

Declared in <include/boost/url/grammar/string_view_base.hpp>


typedef char* pointer;

The const pointer type

Synopsis

Declared in <include/boost/url/grammar/string_view_base.hpp>


typedef char const* const_pointer;

The reference type

Synopsis

Declared in <include/boost/url/grammar/string_view_base.hpp>


typedef char& reference;

The const reference type

Synopsis

Declared in <include/boost/url/grammar/string_view_base.hpp>


typedef char const& const_reference;

The const iterator type

Synopsis

Declared in <include/boost/url/grammar/string_view_base.hpp>


typedef char const* const_iterator;

The iterator type

Synopsis

Declared in <include/boost/url/grammar/string_view_base.hpp>


typedef const_iterator iterator;

The const reverse iterator type

Synopsis

Declared in <include/boost/url/grammar/string_view_base.hpp>


typedef std::reverse_iterator<const_iterator> const_reverse_iterator;

The reverse iterator type

Synopsis

Declared in <include/boost/url/grammar/string_view_base.hpp>


typedef const_reverse_iterator reverse_iterator;

The size type

Synopsis

Declared in <include/boost/url/grammar/string_view_base.hpp>


typedef std::size_t size_type;

The difference type

Synopsis

Declared in <include/boost/url/grammar/string_view_base.hpp>


typedef std::ptrdiff_t difference_type;

A constant used to represent "no position"

Synopsis

Declared in <include/boost/url/grammar/string_view_base.hpp>


constexpr
static
std::size_t const npos = core::string_view::npos;

Conversion

Synopsis

Declared in <include/boost/url/grammar/string_view_base.hpp>


operator core::string_view() const noexcept;

Conversion

Synopsis

Declared in <include/boost/url/grammar/string_view_base.hpp>


explicit
operator std::string() const noexcept;

Description

Conversion to std::string is explicit because assigning to string using an implicit constructor does not preserve capacity.

Return an iterator to the beginning

Synopsis

Declared in <include/boost/url/grammar/string_view_base.hpp>


constexpr
const_iterator
begin() const noexcept;

Description

See `core::string_view::begin`

Return an iterator to the end

Synopsis

Declared in <include/boost/url/grammar/string_view_base.hpp>


constexpr
const_iterator
end() const noexcept;

Description

See `core::string_view::end`

Return an iterator to the beginning

Synopsis

Declared in <include/boost/url/grammar/string_view_base.hpp>


constexpr
const_iterator
cbegin() const noexcept;

Description

See `core::string_view::cbegin`

Return an iterator to the end

Synopsis

Declared in <include/boost/url/grammar/string_view_base.hpp>


constexpr
const_iterator
cend() const noexcept;

Description

See `core::string_view::cend`

Return a reverse iterator to the end

Synopsis

Declared in <include/boost/url/grammar/string_view_base.hpp>


constexpr
const_reverse_iterator
rbegin() const noexcept;

Description

See `core::string_view::rbegin`

Return a reverse iterator to the beginning

Synopsis

Declared in <include/boost/url/grammar/string_view_base.hpp>


constexpr
const_reverse_iterator
rend() const noexcept;

Description

See `core::string_view::rend`

Return a reverse iterator to the end

Synopsis

Declared in <include/boost/url/grammar/string_view_base.hpp>


constexpr
const_reverse_iterator
crbegin() const noexcept;

Description

See `core::string_view::crbegin`

Return a reverse iterator to the beginning

Synopsis

Declared in <include/boost/url/grammar/string_view_base.hpp>


constexpr
const_reverse_iterator
crend() const noexcept;

Description

See `core::string_view::crend`

Return the size

Synopsis

Declared in <include/boost/url/grammar/string_view_base.hpp>


constexpr
size_type
size() const noexcept;

Description

See `core::string_view::size`

Return the size

Synopsis

Declared in <include/boost/url/grammar/string_view_base.hpp>


constexpr
size_type
length() const noexcept;

Description

See `core::string_view::length`

Return the maximum allowed size

Synopsis

Declared in <include/boost/url/grammar/string_view_base.hpp>


constexpr
size_type
max_size() const noexcept;

Description

See `core::string_view::max_size`

Return true if the string is empty

Synopsis

Declared in <include/boost/url/grammar/string_view_base.hpp>


constexpr
bool
empty() const noexcept;

Description

See `core::string_view::size`

Access a character

Synopsis

Declared in <include/boost/url/grammar/string_view_base.hpp>


constexpr
const_reference
operator[](size_type pos) const noexcept;

Description

See `core::string_view::operator[]`

Access a character

Synopsis

Declared in <include/boost/url/grammar/string_view_base.hpp>


constexpr
const_reference
at(size_type pos) const;

Description

See `core::string_view::at`

Return the first character

Synopsis

Declared in <include/boost/url/grammar/string_view_base.hpp>


constexpr
const_reference
front() const noexcept;

Description

See `core::string_view::front`

Return the last character

Synopsis

Declared in <include/boost/url/grammar/string_view_base.hpp>


constexpr
const_reference
back() const noexcept;

Description

See `core::string_view::back`

Return a pointer to the character buffer

Synopsis

Declared in <include/boost/url/grammar/string_view_base.hpp>


constexpr
const_pointer
data() const noexcept;

Description

See `core::string_view::data`

Copy the characters to another buffer

Synopsis

Declared in <include/boost/url/grammar/string_view_base.hpp>


constexpr
size_type
copy(
    char* s,
    size_type n,
    size_type pos = 0) const;

Description

See `core::string_view::copy`

Return a view to part of the string

Synopsis

Declared in <include/boost/url/grammar/string_view_base.hpp>


constexpr
core::string_view
substr(
    size_type pos = 0,
    size_type n = core::string_view::npos) const;

Description

See `core::string_view::substr`

Return the result of comparing to another string

Synopsis

Declared in <include/boost/url/grammar/string_view_base.hpp>


constexpr
int
compare(core::string_view str) const noexcept;

» more...


constexpr
int
compare(
    size_type pos1,
    size_type n1,
    core::string_view str) const;

» more...


constexpr
int
compare(
    size_type pos1,
    size_type n1,
    core::string_view str,
    size_type pos2,
    size_type n2) const;

» more...


constexpr
int
compare(char const* s) const noexcept;

» more...


constexpr
int
compare(
    size_type pos1,
    size_type n1,
    char const* s) const;

» more...


constexpr
int
compare(
    size_type pos1,
    size_type n1,
    char const* s,
    size_type n2) const;


constexpr
bool
starts_with(core::string_view x) const noexcept;

» more...


constexpr
bool
starts_with(char x) const noexcept;

» more...


constexpr
bool
starts_with(char const* x) const noexcept;


constexpr
bool
ends_with(core::string_view x) const noexcept;

» more...


constexpr
bool
ends_with(char x) const noexcept;

» more...


constexpr
bool
ends_with(char const* x) const noexcept;


constexpr
size_type
find(
    core::string_view str,
    size_type pos = 0) const noexcept;

» more...


constexpr
size_type
find(
    char c,
    size_type pos = 0) const noexcept;

» more...


constexpr
size_type
find(
    char const* s,
    size_type pos,
    size_type n) const noexcept;

» more...


constexpr
size_type
find(
    char const* s,
    size_type pos = 0) const noexcept;


constexpr
size_type
rfind(
    core::string_view str,
    size_type pos = core::string_view::npos) const noexcept;

» more...


constexpr
size_type
rfind(
    char c,
    size_type pos = core::string_view::npos) const noexcept;

» more...


constexpr
size_type
rfind(
    char const* s,
    size_type pos,
    size_type n) const noexcept;

» more...


constexpr
size_type
rfind(
    char const* s,
    size_type pos = core::string_view::npos) const noexcept;


constexpr
size_type
find_first_of(
    core::string_view str,
    size_type pos = 0) const noexcept;

» more...


constexpr
size_type
find_first_of(
    char c,
    size_type pos = 0) const noexcept;

» more...


constexpr
size_type
find_first_of(
    char const* s,
    size_type pos,
    size_type n) const noexcept;

» more...


constexpr
size_type
find_first_of(
    char const* s,
    size_type pos = 0) const noexcept;


constexpr
size_type
find_last_of(
    core::string_view str,
    size_type pos = core::string_view::npos) const noexcept;

» more...


constexpr
size_type
find_last_of(
    char c,
    size_type pos = core::string_view::npos) const noexcept;

» more...


constexpr
size_type
find_last_of(
    char const* s,
    size_type pos,
    size_type n) const noexcept;

» more...


constexpr
size_type
find_last_of(
    char const* s,
    size_type pos = core::string_view::npos) const noexcept;


constexpr
size_type
find_first_not_of(
    core::string_view str,
    size_type pos = 0) const noexcept;

» more...


constexpr
size_type
find_first_not_of(
    char c,
    size_type pos = 0) const noexcept;

» more...


constexpr
size_type
find_first_not_of(
    char const* s,
    size_type pos,
    size_type n) const noexcept;

» more...


constexpr
size_type
find_first_not_of(
    char const* s,
    size_type pos = 0) const noexcept;


constexpr
size_type
find_last_not_of(
    core::string_view str,
    size_type pos = core::string_view::npos) const noexcept;

» more...


constexpr
size_type
find_last_not_of(
    char c,
    size_type pos = core::string_view::npos) const noexcept;

» more...


constexpr
size_type
find_last_not_of(
    char const* s,
    size_type pos,
    size_type n) const noexcept;

» more...


constexpr
size_type
find_last_not_of(
    char const* s,
    size_type pos = core::string_view::npos) const noexcept;


constexpr
bool
contains(core::string_view sv) const noexcept;

» more...


constexpr
bool
contains(char c) const noexcept;

» more...


constexpr
bool
contains(char const* s) const noexcept;


friend
std::ostream&
operator<<(
    std::ostream& os,
    string_view_base const& s);

Compare two string views for equality

Synopsis

Declared in <include/boost/url/grammar/string_view_base.hpp>


template<
    class S0,
    class S1>
constexpr
bool
operator==(
    S0 const& s0,
    S1 const& s1) noexcept;

Description

This function is only enabled if both arguments are convertible to `core::string_view` and at least one of the arguments is derived from `string_view_base`.

Compare two string views for inequality

Synopsis

Declared in <include/boost/url/grammar/string_view_base.hpp>


template<
    class S0,
    class S1>
constexpr
bool
operator!=(
    S0 const& s0,
    S1 const& s1) noexcept;

Description

This function is only enabled if both arguments are convertible to `core::string_view` and at least one of the arguments is derived from `string_view_base`.

Compare two string views for less than

Synopsis

Declared in <include/boost/url/grammar/string_view_base.hpp>


template<
    class S0,
    class S1>
constexpr
bool
operator<(
    S0 const& s0,
    S1 const& s1) noexcept;

Description

This function is only enabled if both arguments are convertible to `core::string_view` and at least one of the arguments is derived from `string_view_base`.

Compare two string views for less than or equal

Synopsis

Declared in <include/boost/url/grammar/string_view_base.hpp>


template<
    class S0,
    class S1>
constexpr
bool
operator<=(
    S0 const& s0,
    S1 const& s1) noexcept;

Description

This function is only enabled if both arguments are convertible to `core::string_view` and at least one of the arguments is derived from `string_view_base`.

Compare two string views for greater than

Synopsis

Declared in <include/boost/url/grammar/string_view_base.hpp>


template<
    class S0,
    class S1>
constexpr
bool
operator>(
    S0 const& s0,
    S1 const& s1) noexcept;

Description

This function is only enabled if both arguments are convertible to `core::string_view` and at least one of the arguments is derived from `string_view_base`.

Compare two string views for greater than or equal

Synopsis

Declared in <include/boost/url/grammar/string_view_base.hpp>


template<
    class S0,
    class S1>
constexpr
bool
operator>=(
    S0 const& s0,
    S1 const& s1) noexcept;

Description

This function is only enabled if both arguments are convertible to `core::string_view` and at least one of the arguments is derived from `string_view_base`.

Format a string to an output stream

Synopsis

Declared in <include/boost/url/grammar/string_view_base.hpp>


std::ostream&
operator<<(
    std::ostream& os,
    string_view_base const& s);

Match a non-empty string of characters from a set

Synopsis

Declared in <include/boost/url/grammar/token_rule.hpp>


template<class CharSet>
constexpr
    _implementation-defined_
token_rule(CharSet const& cs) noexcept;

Description

If there is no more input, the error code error::need_more is returned.


using value_type = core::string_view;

Rules are used with the function

parse .


system::result< core::string_view > rv = parse( "abcdef", token_rule( alpha_chars ) );


token     = 1*( ch )

Parameters

Name	Description
cs	The character set to use

Synopsis

Declared in <include/boost/url/grammar/tuple_rule.hpp>


template<
    class R0,
    class... Rn>
constexpr
    _implementation-defined_
tuple_rule(
    R0 const& r0,
    Rn const&... rn) noexcept;

Description

This matches a series of rules in the order specified. Upon success the input is adjusted to point to the first unconsumed character. There is no implicit specification of linear white space between each rule.


using value_type = __see_below__;

The sequence rule usually returns a `std::tuple` containing the the `value_type` of each corresponding rule in the sequence, except that `void` values are removed. However, if there is exactly one non-void value type `T`, then the sequence rule returns `system::result` instead of `system::result>`.

Rules are used with the function

parse .


system::result< std::tuple< unsigned char, unsigned char, unsigned char, unsigned char > > rv =
    parse( "192.168.0.1",
        tuple_rule(
            dec_octet_rule,
            squelch( delim_rule('.') ),
            dec_octet_rule,
            squelch( delim_rule('.') ),
            dec_octet_rule,
            squelch( delim_rule('.') ),
            dec_octet_rule ) );


sequence     = rule1 rule2 rule3...

3.1. Concatenation (rfc5234)

Parameters

Name	Description
rn	A list of one or more rules to match

Synopsis

Declared in <include/boost/url/grammar/tuple_rule.hpp>


template<class Rule>
constexpr
    _implementation-defined_
squelch(Rule const& r) noexcept;

Description

This function returns a new rule which matches the specified rule, and converts its value type to `void`. This is useful for matching delimiters in a grammar, where the value for the delimiter is not needed.


using value_type = void;

With `squelch`:


system::result< std::tuple< decode_view, core::string_view > > rv = parse(
    "www.example.com:443",
    tuple_rule(
        pct_encoded_rule(unreserved_chars + '-' + '.'),
        squelch( delim_rule( ':' ) ),
        token_rule( digit_chars ) ) );

Without `squelch`:


system::result< std::tuple< decode_view, core::string_view, core::string_view > > rv = parse(
    "www.example.com:443",
    tuple_rule(
        pct_encoded_rule(unreserved_chars + '-' + '.'),
        delim_rule( ':' ),
        token_rule( digit_chars ) ) );

Parameters

Name	Description
r	The rule to squelch

Synopsis

Declared in <include/boost/url/grammar/unsigned_rule.hpp>


template<class Unsigned>
struct unsigned_rule;

Types

Name	Description
`value_type`

Member Functions

Name	Description
`parse`

Description

Extra leading zeroes are disallowed.


using value_type = Unsigned;

Rules are used with the function

parse .


system::result< unsigned short > rv = parse( "32767", unsigned_rule< unsigned short >{} );


unsigned      = "0" / ( ["1"..."9"] *DIGIT )

Template Parameters

Name	Description
Unsigned	The unsigned integer type used to store the result.

Synopsis

Declared in <include/boost/url/grammar/unsigned_rule.hpp>


using value_type = Unsigned;

Synopsis

Declared in <include/boost/url/grammar/unsigned_rule.hpp>


system::result<value_type>
parse(
    char const*& it,
    char const* end) const noexcept;

Match one of a set of rules

Synopsis

Declared in <include/boost/url/grammar/variant_rule.hpp>


template<
    class R0,
    class... Rn>
constexpr
    _implementation-defined_
variant_rule(
    R0 const& r0,
    Rn const&... rn) noexcept;

Description

Each specified rule is tried in sequence. When the first match occurs, the result is stored and returned in the variant. If no match occurs, an error is returned.


using value_type = variant< typename Rules::value_type... >;

Rules are used with the function

parse .


// request-target = origin-form
//                / absolute-form
//                / authority-form
//                / asterisk-form

system::result< variant< url_view, url_view, authority_view, core::string_view > > rv = grammar::parse(
    "/index.html?width=full",
    variant_rule(
        origin_form_rule,
        absolute_uri_rule,
        authority_rule,
        delim_rule('*') ) );


variant     = rule1 / rule2 / rule3...

3.2. Alternatives (rfc5234)

5.3. Request Target (rfc7230)

Synopsis

Declared in <include/boost/url/grammar/vchars.hpp>


constexpr
    _implementation-defined_ vchars = {};

Description

Character sets are used with rules and the

functions find_if and find_if_not .


system::result< core::string_view > rv = parse( "JohnDoe", token_rule( vchars ) );


VCHAR       = 0x21-0x7E
            ; visible (printing) characters

B.1. Core Rules (rfc5234)

Synopsis

Declared in <include/boost/url/grammar/all_chars.hpp>


constexpr
    _implementation-defined_ all_chars = all_chars{};

Description

Character sets are used with rules and the

functions find_if and find_if_not .


system::result< core::string_view > rv = parse( "JohnDoe", token_rule( all_chars ) );


ALL       = %x00-FF

Types

Name	Description
`error_category`	The type of error category used by the library
`error_code`	The type of error code used by the library
`error_condition`	The type of error condition used by the library
`result`	The type of result returned by library functions
`system_error`	The type of system error thrown by the library

The type of error category used by the library

Synopsis

Declared in <include/boost/url/error_types.hpp>


using error_category = boost::system::error_category;

Description

WARNING

This alias is no longer supported and should not be used in new code. Please use `system::error_category` instead.

This alias is included for backwards compatibility with earlier versions of the library.

However, it will be removed in future releases, and using it in new code is not recommended.

Please use the updated version instead to ensure compatibility with future versions of the library.

The type of error code used by the library

Synopsis

Declared in <include/boost/url/error_types.hpp>


using error_code = boost::system::error_code;

Description

WARNING

This alias is no longer supported and should not be used in new code. Please use `system::error_code` instead.

This alias is included for backwards compatibility with earlier versions of the library.

However, it will be removed in future releases, and using it in new code is not recommended.

Please use the updated version instead to ensure compatibility with future versions of the library.

The type of error condition used by the library

Synopsis

Declared in <include/boost/url/error_types.hpp>


using error_condition = boost::system::error_condition;

Description

WARNING

This alias is no longer supported and should not be used in new code. Please use `system::error_condition` instead.

This alias is included for backwards compatibility with earlier versions of the library.

However, it will be removed in future releases, and using it in new code is not recommended.

Please use the updated version instead to ensure compatibility with future versions of the library.

The type of system error thrown by the library

Synopsis

Declared in <include/boost/url/error_types.hpp>


using system_error = boost::system::system_error;

Description

WARNING

This alias is no longer supported and should not be used in new code. Please use `system::system_error` instead.

This alias is included for backwards compatibility with earlier versions of the library.

However, it will be removed in future releases, and using it in new code is not recommended.

Please use the updated version instead to ensure compatibility with future versions of the library.

A function to return the generic error category used by the library

Synopsis

Declared in <include/boost/url/error_types.hpp>


using boost::system::generic_category;

Description

WARNING

This alias is no longer supported and should not be used in new code. Please use `core::string_view` instead.

This alias is included for backwards compatibility with earlier versions of the library.

However, it will be removed in future releases, and using it in new code is not recommended.

Please use the updated version instead to ensure compatibility with future versions of the library.

A function to return the system error category used by the library

Synopsis

Declared in <include/boost/url/error_types.hpp>


using boost::system::system_category;

Description

WARNING

This alias is no longer supported and should not be used in new code. Please use `core::string_view` instead.

This alias is included for backwards compatibility with earlier versions of the library.

However, it will be removed in future releases, and using it in new code is not recommended.

Please use the updated version instead to ensure compatibility with future versions of the library.

The set of constants used for cross-platform error codes

Synopsis

Declared in <include/boost/url/error_types.hpp>


namespace errc = boost::system::errc;

Description

WARNING

This alias is no longer supported and should not be used in new code. Please use `core::string_view` instead.

This alias is included for backwards compatibility with earlier versions of the library.

However, it will be removed in future releases, and using it in new code is not recommended.

Please use the updated version instead to ensure compatibility with future versions of the library.

The type of result returned by library functions

Synopsis

Declared in <include/boost/url/error_types.hpp>


template<class T>
using result = boost::system::result<T, system::error_code>;

Description

WARNING

This alias is no longer supported and should not be used in new code. Please use `system::result` instead.

This alias is included for backwards compatibility with earlier versions of the library.

However, it will be removed in future releases, and using it in new code is not recommended.

Please use the updated version instead to ensure compatibility with future versions of the library.

This is an alias template used as the return type for functions that can either return a container, or fail with an error code. This is a brief synopsis of the type:


template< class T >
class result
{
public:
    //
    // Return true if the result contains an error
    //
    constexpr bool has_error() const noexcept;

    //
    // Return the error
    //
    constexpr system::error_code error() const noexcept;

    //
    // Return true if the result contains a value
    //
    constexpr bool has_value() const noexcept;
    constexpr explicit operator bool() const noexcept;

    //
    // Return the value, or throw an exception
    //
    constexpr T& value();
    constexpr T const& value() const;

    // Return the value.
    // Precondition: has_value()==true
    //
    constexpr T& operator*() noexcept;
    constexpr T* operator->() noexcept;
    constexpr T const& operator*() const noexcept;
    constexpr T const* operator->() const noexcept;

    ...more

Given the function

parse_uri with this signature:


system::result< url_view > parse_uri( core::string_view s ) noexcept;

The following statement captures the value in a variable upon success, otherwise throws:


url_view u = parse_uri( "http://example.com/path/to/file.txt" ).value();

This statement captures the result in a local variable and inspects the error condition:


system::result< url_view > rv = parse_uri( "http://example.com/path/to/file.txt" );

if(! rv )
    std::cout << rv.error();
else
    std::cout << *rv;

`boost::system::result`

Template Parameters

Name	Description
T	The type of value held by the result.

Synopsis

Declared in <include/boost/url/optional.hpp>


template<class T>
using optional = boost::optional<T>;

Description

WARNING

This alias is no longer supported and should not be used in new code. Please use `boost::optional` instead.

This alias is included for backwards compatibility with earlier versions of the library.

However, it will be removed in future releases, and using it in new code is not recommended.

Please use the updated version instead to ensure compatibility with future versions of the library.

Error codes returned the library

Synopsis

Declared in <include/boost/url/error.hpp>


enum error : int;

Members

Name	Description
success	The operation completed successfully.
illegal_null	Null encountered in pct-encoded.
illegal_reserved_char	Illegal reserved character in encoded string.
non_canonical	A grammar element was not in canonical form.
bad_pct_hexdig	Bad hexadecimal digit.
incomplete_encoding	The percent-encoded sequence is incomplete.
missing_pct_hexdig	Missing hexadecimal digit.
no_space	No space in output buffer
not_a_base	The URL is not a base URL

The operation completed successfully.

Synopsis

Declared in <include/boost/url/error.hpp>


success = 0

Null encountered in pct-encoded.

Synopsis

Declared in <include/boost/url/error.hpp>


illegal_null

Illegal reserved character in encoded string.

Synopsis

Declared in <include/boost/url/error.hpp>


illegal_reserved_char

A grammar element was not in canonical form.

Synopsis

Declared in <include/boost/url/error.hpp>


non_canonical

Bad hexadecimal digit.

Synopsis

Declared in <include/boost/url/error.hpp>


bad_pct_hexdig

Description

This error condition is fatal.

The percent-encoded sequence is incomplete.

Synopsis

Declared in <include/boost/url/error.hpp>


incomplete_encoding

Description

This error condition is fatal.

Missing hexadecimal digit.

Synopsis

Declared in <include/boost/url/error.hpp>


missing_pct_hexdig

Description

This error condition is fatal.

No space in output buffer

Synopsis

Declared in <include/boost/url/error.hpp>


no_space

Description

This error is returned when a provided output buffer was too small to hold the complete result of an algorithm.

The URL is not a base URL

Synopsis

Declared in <include/boost/url/error.hpp>


not_a_base

Namespaces

Name	Description
`implementation_defined`
`see_below`

Types

Name	Description
`arg`	Base class for string tokens, and algorithm parameters
`is_token`	Metafunction returning true if T is a StringToken
`return_string`	A token for returning a plain string

Functions

Name	Description
`append_to`	Create a token for appending to a plain string
`assign_to`	A token for assigning to a plain string
`preserve_size`	A token for producing a durable core::string_view from a temporary string

Base class for string tokens, and algorithm parameters

Synopsis

Declared in <include/boost/url/grammar/string_token.hpp>


struct arg;

Member Functions

Name	Description
`arg` [constructor]	Default constructor Default move constructor Deleted copy constructor
`operator=`	Deleted copy assignment Deleted move assignment
`prepare`	Return a modifiable character buffer
`~arg` [destructor]	Virtual destructor

Description

This abstract interface provides a means for an algorithm to generically obtain a modifiable, contiguous character buffer of prescribed size. As the author of an algorithm simply declare an rvalue reference as a parameter type.

Instances of this type are intended only to be used once and then destroyed.

The declared function accepts any

temporary instance of `arg` to be used for writing:


void algorithm( string_token::arg&& dest );

To implement the interface for your type or use-case, derive from the class and implement the prepare function.

Return a modifiable character buffer

Synopsis

Declared in <include/boost/url/grammar/string_token.hpp>


virtual
char*
prepare(std::size_t n) = 0;

Description

This function attempts to obtain a character buffer with space for at least `n` characters. Upon success, a pointer to the beginning of the buffer is returned. Ownership is not transferred; the caller should not attempt to free the storage. The buffer shall remain valid until `this` is destroyed.

NOTE

This function may only be called once. After invoking the function, the only valid operation is destruction.

Virtual destructor

Synopsis

Declared in <include/boost/url/grammar/string_token.hpp>


constexpr
virtual
~arg() = default;

Default constructor

Synopsis

Declared in <include/boost/url/grammar/string_token.hpp>


constexpr
arg() = default;

» more...


constexpr
arg(arg&&) = default;

» more...


arg(arg const&) = delete;

» more...

Default constructor

Synopsis

Declared in <include/boost/url/grammar/string_token.hpp>


constexpr
arg() = default;

Default move constructor

Synopsis

Declared in <include/boost/url/grammar/string_token.hpp>


constexpr
arg(arg&&) = default;

Deleted copy constructor

Synopsis

Declared in <include/boost/url/grammar/string_token.hpp>


arg(arg const&) = delete;

Deleted move assignment

Synopsis

Declared in <include/boost/url/grammar/string_token.hpp>


arg&
operator=(arg&&) = delete;

» more...


arg&
operator=(arg const&) = delete;

» more...

Deleted move assignment

Synopsis

Declared in <include/boost/url/grammar/string_token.hpp>


arg&
operator=(arg&&) = delete;

Deleted copy assignment

Synopsis

Declared in <include/boost/url/grammar/string_token.hpp>


arg&
operator=(arg const&) = delete;

Types

Name	Description
`is_token`	Metafunction returning true if T is a StringToken
`is_token<T, void_t<decltype(std::declval<T&>().prepare( std::declval<std::size_t>())), decltype(std::declval<T&>().result())>>`	Metafunction returning true if T is a StringToken

Metafunction returning true if T is a StringToken

Synopsis

Declared in <include/boost/url/grammar/string_token.hpp>


template<
    class T,
    class = void>
struct is_token
    : std::false_type;

Metafunction returning true if T is a StringToken

Synopsis

Declared in <include/boost/url/grammar/string_token.hpp>


template<class T>
struct is_token<T, void_t<decltype(std::declval<T&>().prepare(
        std::declval<std::size_t>())), decltype(std::declval<T&>().result())>>
    : std::integral_constant<bool, std::is_convertible<decltype(std::declval<T &>().result()), typename T::result_type>::value && std::is_same<decltype(std::declval<T &>().prepare(0)), char *>::value && std::is_base_of<arg, T>::value && std::is_convertible<const volatile T *, const volatile arg *>::value>;

Metafunction returning true if T is a StringToken

Synopsis

Declared in <include/boost/url/grammar/string_token.hpp>


template<class T>
using is_token =     _see-below_;

Types

Name	Description
`append_to_t`
`assign_to_t`
`preserve_size_t`
`return_string`

Synopsis

Declared in <include/boost/url/grammar/string_token.hpp>


struct return_string
    : arg;

Types

Name	Description
`result_type`

Member Functions

Name Description

operator=

Deleted copy assignment

Deleted move assignment

prepare

Return a modifiable character buffer

result

Synopsis

Declared in <include/boost/url/grammar/string_token.hpp>


using result_type = std::string;

Synopsis

Declared in <include/boost/url/grammar/string_token.hpp>


virtual
char*
prepare(std::size_t n) override;

Synopsis

Declared in <include/boost/url/grammar/string_token.hpp>


    _implementation-defined_
result() noexcept;

Synopsis

Declared in <include/boost/url/grammar/string_token.hpp>


template<class Alloc>
struct append_to_t
    : arg;

Types

Name	Description
`result_type`
`string_type`

Member Functions

Name	Description
`append_to_t` [constructor]
`operator=`	Deleted copy assignment Deleted move assignment
`prepare`	Return a modifiable character buffer
`result`

Synopsis

Declared in <include/boost/url/grammar/string_token.hpp>


using string_type = std::basic_string<char, std::char_traits<char>, Alloc>;

Synopsis

Declared in <include/boost/url/grammar/string_token.hpp>


using result_type =     _implementation-defined_&;

Synopsis

Declared in <include/boost/url/grammar/string_token.hpp>


explicit
append_to_t(    _implementation-defined_& s) noexcept;

Synopsis

Declared in <include/boost/url/grammar/string_token.hpp>


virtual
char*
prepare(std::size_t n) override;

Synopsis

Declared in <include/boost/url/grammar/string_token.hpp>


    _implementation-defined_
result() noexcept;

Synopsis

Declared in <include/boost/url/grammar/string_token.hpp>


template<class Alloc>
struct assign_to_t
    : arg;

Types

Name	Description
`result_type`
`string_type`

Member Functions

Name	Description
`assign_to_t` [constructor]
`operator=`	Deleted copy assignment Deleted move assignment
`prepare`	Return a modifiable character buffer
`result`

Synopsis

Declared in <include/boost/url/grammar/string_token.hpp>


using string_type = std::basic_string<char, std::char_traits<char>, Alloc>;

Synopsis

Declared in <include/boost/url/grammar/string_token.hpp>


using result_type =     _implementation-defined_&;

Synopsis

Declared in <include/boost/url/grammar/string_token.hpp>


explicit
assign_to_t(    _implementation-defined_& s) noexcept;

Synopsis

Declared in <include/boost/url/grammar/string_token.hpp>


virtual
char*
prepare(std::size_t n) override;

Synopsis

Declared in <include/boost/url/grammar/string_token.hpp>


    _implementation-defined_
result() noexcept;

Synopsis

Declared in <include/boost/url/grammar/string_token.hpp>


template<class Alloc>
struct preserve_size_t
    : arg;

Types

Name	Description
`result_type`
`string_type`

Member Functions

Name	Description
`operator=`	Deleted copy assignment Deleted move assignment
`prepare`	Return a modifiable character buffer
`preserve_size_t` [constructor]
`result`

Synopsis

Declared in <include/boost/url/grammar/string_token.hpp>


using result_type = core::string_view;

Synopsis

Declared in <include/boost/url/grammar/string_token.hpp>


using string_type = std::basic_string<char, std::char_traits<char>, Alloc>;

Synopsis

Declared in <include/boost/url/grammar/string_token.hpp>


explicit
preserve_size_t(    _implementation-defined_& s) noexcept;

Synopsis

Declared in <include/boost/url/grammar/string_token.hpp>


virtual
char*
prepare(std::size_t n) override;

Synopsis

Declared in <include/boost/url/grammar/string_token.hpp>


    _implementation-defined_
result() noexcept;

A token for returning a plain string

Synopsis

Declared in <include/boost/url/grammar/string_token.hpp>


using return_string =     _implementation-defined_;

Create a token for appending to a plain string

Synopsis

Declared in <include/boost/url/grammar/string_token.hpp>


template<class Alloc = std::allocator<char>>
    _implementation-defined_
append_to(std::basic_string<char, std::char_traits<char>, Alloc>& s);

A token for assigning to a plain string

Synopsis

Declared in <include/boost/url/grammar/string_token.hpp>


template<class Alloc = std::allocator<char>>
    _implementation-defined_
assign_to(std::basic_string<char, std::char_traits<char>, Alloc>& s);

A token for producing a durable core::string_view from a temporary string

Synopsis

Declared in <include/boost/url/grammar/string_token.hpp>


template<class Alloc = std::allocator<char>>
    _implementation-defined_
preserve_size(std::basic_string<char, std::char_traits<char>, Alloc>& s);

The type of variant used by the library

Synopsis

Declared in <include/boost/url/variant.hpp>


template<class... Ts>
using variant = boost::variant2::variant<Ts...>;

Description

WARNING

This alias is no longer supported and should not be used in new code. Please use `boost::variant2::variant` instead.

This alias is included for backwards compatibility with earlier versions of the library.

However, it will be removed in future releases, and using it in new code is not recommended.

Please use the updated version instead to ensure compatibility with future versions of the library.

Identifies the type of host in a URL.

Synopsis

Declared in <include/boost/url/host_type.hpp>


enum host_type : int;

Members

Name	Description
none	No host is specified.
name	A host is specified by reg-name.
ipv4	A host is specified by ipv4_address .
ipv6	A host is specified by ipv6_address .
ipvfuture	A host is specified by IPvFuture.

Description

Values of this type are returned by URL views and containers to indicate the type of host present in a URL.

No host is specified.

Synopsis

Declared in <include/boost/url/host_type.hpp>


none

A host is specified by reg-name.

Synopsis

Declared in <include/boost/url/host_type.hpp>


name

A host is specified by ipv4_address .

Synopsis

Declared in <include/boost/url/host_type.hpp>


ipv4

A host is specified by ipv6_address .

Synopsis

Declared in <include/boost/url/host_type.hpp>


ipv6

A host is specified by IPvFuture.

Synopsis

Declared in <include/boost/url/host_type.hpp>


ipvfuture

An IP version 4 style address.

Synopsis

Declared in <include/boost/url/ipv4_address.hpp>


class ipv4_address;

Types

Name	Description
`bytes_type`	The type used to represent an address as an array of bytes
`uint_type`	The type used to represent an address as an unsigned integer

Member Functions

Name	Description
`ipv4_address` [constructor]	Construct from a string. Construct from an array of bytes. Construct from an unsigned integer. Constructor.
`is_loopback`	Return true if the address is a loopback address
`is_multicast`	Return true if the address is a multicast address
`is_unspecified`	Return true if the address is unspecified
`operator=`	Copy Assignment.
`to_buffer`	Write a dotted decimal string representing the address to a buffer
`to_bytes`	Return the address as bytes, in network byte order.
`to_string`	Return the address as a string in dotted decimal format
`to_uint`	Return the address as an unsigned integer.

Static Member Functions

Name	Description
`any`	Return an address object that represents any address
`broadcast`	Return an address object that represents the broadcast address
`loopback`	Return an address object that represents the loopback address

Static Data Members

Name	Description
`max_str_len`	The number of characters in the longest possible IPv4 string.

Friends

Name	Description
`operator!=`	Return true if two addresses are not equal
`operator<<`	Format the address to an output stream.
`operator==`	Return true if two addresses are equal

Description

Objects of this type are used to construct, parse, and manipulate IP version 6 addresses.


IPv4address = dec-octet "." dec-octet "." dec-octet "." dec-octet

dec-octet   = DIGIT                 ; 0-9
            / %x31-39 DIGIT         ; 10-99
            / "1" 2DIGIT            ; 100-199
            / "2" %x30-34 DIGIT     ; 200-249
            / "25" %x30-35          ; 250-255

IPv4 (Wikipedia)

3.2.2. Host (rfc3986)

Synopsis

Declared in <include/boost/url/ipv4_address.hpp>


constexpr
static
std::size_t const max_str_len = 15;

Description

The longest ipv4 address string is "255.255.255.255".

The type used to represent an address as an unsigned integer

Synopsis

Declared in <include/boost/url/ipv4_address.hpp>


using uint_type = std::uint_least32_t;

The type used to represent an address as an array of bytes

Synopsis

Declared in <include/boost/url/ipv4_address.hpp>


using bytes_type = std::array<unsigned char, 4>;

Constructor.

Synopsis

Declared in <include/boost/url/ipv4_address.hpp>


constexpr
ipv4_address() = default;

» more...


constexpr
ipv4_address(ipv4_address const&) = default;

» more...


explicit
ipv4_address(uint_type u) noexcept;

» more...


explicit
ipv4_address(bytes_type const& bytes) noexcept;

» more...


explicit
ipv4_address(core::string_view s);

» more...

Exceptions

Name	Thrown on
`[object Object]`	input failed to parse correctly.

Parameters

Name	Description
u	The integer to construct from.
bytes	The value to construct from.
s	The string to parse.

Constructor.

Synopsis

Declared in <include/boost/url/ipv4_address.hpp>


constexpr
ipv4_address() = default;

Constructor.

Synopsis

Declared in <include/boost/url/ipv4_address.hpp>


constexpr
ipv4_address(ipv4_address const&) = default;

Construct from an unsigned integer.

Synopsis

Declared in <include/boost/url/ipv4_address.hpp>


explicit
ipv4_address(uint_type u) noexcept;

Description

This function constructs an address from the unsigned integer `u`, where the most significant byte forms the first octet of the resulting address.

Parameters

Name	Description
u	The integer to construct from.

Construct from an array of bytes.

Synopsis

Declared in <include/boost/url/ipv4_address.hpp>


explicit
ipv4_address(bytes_type const& bytes) noexcept;

Description

This function constructs an address from the array in `bytes`, which is interpreted in big-endian.

Parameters

Name	Description
bytes	The value to construct from.

Construct from a string.

Synopsis

Declared in <include/boost/url/ipv4_address.hpp>


explicit
ipv4_address(core::string_view s);

Description

This function constructs an address from the string `s`, which must contain a valid IPv4 address string or else an exception is thrown.

NOTE

For a non-throwing parse function, use parse_ipv4_address .

Exceptions thrown on invalid input.

3.2.2. Host (rfc3986)

Exceptions

Name	Thrown on
`The`	input failed to parse correctly.

Parameters

Name	Description
s	The string to parse.

Synopsis

Declared in <include/boost/url/ipv4_address.hpp>


constexpr
ipv4_address&
operator=(ipv4_address const&) = default;

Return the address as bytes, in network byte order.

Synopsis

Declared in <include/boost/url/ipv4_address.hpp>


bytes_type
to_bytes() const noexcept;

Return the address as an unsigned integer.

Synopsis

Declared in <include/boost/url/ipv4_address.hpp>


uint_type
to_uint() const noexcept;

Return the address as a string in dotted decimal format

Synopsis

Declared in <include/boost/url/ipv4_address.hpp>


template<class StringToken = string_token::return_string>
StringToken::result_type
to_string(StringToken&& token) const;

Description

When called with no arguments, the return type is `std::string`. Otherwise, the return type and style of output is determined by which string token is passed.


assert( ipv4_address(0x01020304).to_string() == "1.2.3.4" );

Constant.

Strong guarantee.

Calls to allocate may throw. String tokens may throw exceptions.

2.2. Text Representation of Addresses (rfc4291)

Return Value

The return type of the string token. If the token parameter is omitted, then a new `std::string` is returned. Otherwise, the function return type is the result type of the token.

Parameters

Name	Description
token	An optional string token.

Write a dotted decimal string representing the address to a buffer

Synopsis

Declared in <include/boost/url/ipv4_address.hpp>


core::string_view
to_buffer(
    char* dest,
    std::size_t dest_size) const;

Description

The resulting buffer is not null-terminated.

Exceptions

Name	Thrown on
`dest_size	< ipv4_address::max_str_len`

Return Value

The formatted string

Parameters

Name	Description
dest	The buffer in which to write, which must have at least `dest_size` space.
dest_size	The size of the output buffer.

Return true if the address is a loopback address

Synopsis

Declared in <include/boost/url/ipv4_address.hpp>


bool
is_loopback() const noexcept;

Return true if the address is unspecified

Synopsis

Declared in <include/boost/url/ipv4_address.hpp>


bool
is_unspecified() const noexcept;

Return true if the address is a multicast address

Synopsis

Declared in <include/boost/url/ipv4_address.hpp>


bool
is_multicast() const noexcept;

Return true if two addresses are equal

Synopsis

Declared in <include/boost/url/ipv4_address.hpp>


friend
bool
operator==(
    ipv4_address const& a1,
    ipv4_address const& a2) noexcept;

Return true if two addresses are not equal

Synopsis

Declared in <include/boost/url/ipv4_address.hpp>


friend
bool
operator!=(
    ipv4_address const& a1,
    ipv4_address const& a2) noexcept;

Return an address object that represents any address

Synopsis

Declared in <include/boost/url/ipv4_address.hpp>


static
ipv4_address
any() noexcept;

Return an address object that represents the loopback address

Synopsis

Declared in <include/boost/url/ipv4_address.hpp>


static
ipv4_address
loopback() noexcept;

Return an address object that represents the broadcast address

Synopsis

Declared in <include/boost/url/ipv4_address.hpp>


static
ipv4_address
broadcast() noexcept;

Format the address to an output stream.

Synopsis

Declared in <include/boost/url/ipv4_address.hpp>


friend
std::ostream&
operator<<(
    std::ostream& os,
    ipv4_address const& addr);

Description

IPv4 addresses written to output streams are written in their dotted decimal format.

Parameters

Name	Description
os	The output stream.
addr	The address to format.

Return true if two addresses are equal

Synopsis

Declared in <include/boost/url/ipv4_address.hpp>


bool
operator==(
    ipv4_address const& a1,
    ipv4_address const& a2) noexcept;

» more...


bool
operator==(
    ipv6_address const& a1,
    ipv6_address const& a2) noexcept;

» more...


bool
operator==(
    authority_view const& a0,
    authority_view const& a1) noexcept;

» more...


template<
    class S0,
    class S1>
constexpr
bool
operator==(
    S0 const& s0,
    S1 const& s1) noexcept;

» more...


bool
operator==(
    iterator const& it0,
    iterator const& it1) noexcept;

» more...


bool
operator==(
    url_view_base const& u0,
    url_view_base const& u1) noexcept;

» more...

Return true if two addresses are equal

Synopsis

Declared in <include/boost/url/ipv4_address.hpp>


bool
operator==(
    ipv4_address const& a1,
    ipv4_address const& a2) noexcept;

Return true if two addresses are equal

Synopsis

Declared in <include/boost/url/ipv6_address.hpp>


bool
operator==(
    ipv6_address const& a1,
    ipv6_address const& a2) noexcept;

Return the result of comparing two authorities The authorities are compared component by component as if they were first normalized.

Synopsis

Declared in <include/boost/url/authority_view.hpp>


bool
operator==(
    authority_view const& a0,
    authority_view const& a1) noexcept;

Description

Linear in `min( a0.size(), a1.size() )`

Throws nothing

Compare two decode views for equality

Synopsis

Declared in <include/boost/url/decode_view.hpp>


template<
    class S0,
    class S1>
constexpr
bool
operator==(
    S0 const& s0,
    S1 const& s1) noexcept;

Description

This function is only enabled if both types are decode_view or convertible to `core::string_view`, but not both are convertible to `core::string_view`

Synopsis

Declared in <include/boost/url/impl/params_encoded_base.hpp>


bool
operator==(
    iterator const& it0,
    iterator const& it1) noexcept;

Return the result of comparing two URLs

Synopsis

Declared in <include/boost/url/url_view_base.hpp>


bool
operator==(
    url_view_base const& u0,
    url_view_base const& u1) noexcept;

Description

The URLs are compared component by component as if they were first normalized.


url_view u0( "http://www.a.com/index.htm" );
url_view u1( "http://www.a.com/index.htm" );
assert( u0 == u1 );


url a(u0);
a.normalize();
url b(u1);
b.normalize();
return a.buffer() == b.buffer();

Linear in `min( u0.size(), u1.size() )`

Throws nothing

6.2.2 Syntax-Based Normalization (rfc3986)

Return Value

`true` if `u0 == u1`

Return true if two addresses are not equal

Synopsis

Declared in <include/boost/url/ipv4_address.hpp>


bool
operator!=(
    ipv4_address const& a1,
    ipv4_address const& a2) noexcept;

» more...


bool
operator!=(
    ipv6_address const& a1,
    ipv6_address const& a2) noexcept;

» more...


bool
operator!=(
    authority_view const& a0,
    authority_view const& a1) noexcept;

» more...


template<
    class S0,
    class S1>
constexpr
bool
operator!=(
    S0 const& s0,
    S1 const& s1) noexcept;

» more...


bool
operator!=(
    iterator const& it0,
    iterator const& it1) noexcept;

» more...


bool
operator!=(
    url_view_base const& u0,
    url_view_base const& u1) noexcept;

» more...

Return true if two addresses are not equal

Synopsis

Declared in <include/boost/url/ipv4_address.hpp>


bool
operator!=(
    ipv4_address const& a1,
    ipv4_address const& a2) noexcept;

Return true if two addresses are not equal

Synopsis

Declared in <include/boost/url/ipv6_address.hpp>


bool
operator!=(
    ipv6_address const& a1,
    ipv6_address const& a2) noexcept;

Return the result of comparing two authorities The authorities are compared component by component as if they were first normalized.

Synopsis

Declared in <include/boost/url/authority_view.hpp>


bool
operator!=(
    authority_view const& a0,
    authority_view const& a1) noexcept;

Description

Linear in `min( a0.size(), a1.size() )`

Throws nothing

Compare two decode views for inequality

Synopsis

Declared in <include/boost/url/decode_view.hpp>


template<
    class S0,
    class S1>
constexpr
bool
operator!=(
    S0 const& s0,
    S1 const& s1) noexcept;

Description

This function is only enabled if both types are decode_view or convertible to `core::string_view`, but not both are convertible to `core::string_view`

Synopsis

Declared in <include/boost/url/impl/params_encoded_base.hpp>


bool
operator!=(
    iterator const& it0,
    iterator const& it1) noexcept;

Return the result of comparing two URLs

Synopsis

Declared in <include/boost/url/url_view_base.hpp>


bool
operator!=(
    url_view_base const& u0,
    url_view_base const& u1) noexcept;

Description

The URLs are compared component by component as if they were first normalized.


url_view u0( "http://www.a.com/index.htm" );
url_view u1( "http://www.b.com/index.htm" );
assert( u0 != u1 );


url a(u0);
a.normalize();
url b(u1);
b.normalize();
return a.buffer() != b.buffer();

Linear in `min( u0.size(), u1.size() )`

Throws nothing

6.2.2 Syntax-Based Normalization (rfc3986)

Return Value

`true` if `u0 != u1`

Format the address to an output stream.

Synopsis

Declared in <include/boost/url/ipv4_address.hpp>


std::ostream&
operator<<(
    std::ostream& os,
    ipv4_address const& addr);

» more...


std::ostream&
operator<<(
    std::ostream& os,
    ipv6_address const& addr);

» more...


std::ostream&
operator<<(
    std::ostream& os,
    authority_view const& a);

» more...


std::ostream&
operator<<(
    std::ostream& os,
    decode_view const& s);

» more...


std::ostream&
operator<<(
    std::ostream& os,
    params_encoded_base const& qp);

» more...


std::ostream&
operator<<(
    std::ostream& os,
    params_base const& qp);

» more...


std::ostream&
operator<<(
    std::ostream& os,
    segments_encoded_base const& ps);

» more...


std::ostream&
operator<<(
    std::ostream& os,
    segments_base const& ps);

» more...


std::ostream&
operator<<(
    std::ostream& os,
    url_view_base const& u);

» more...

Description

IPv4 addresses written to output streams are written in their dotted decimal format.

Format the address to an output stream.

IPv4 addresses written to output streams are written in their dotted decimal format.

Parameters

Name	Description
os	The output stream.
addr	The address to format.
a	The URL to write
s	The decoded view to write
u	The url to write.

Format the address to an output stream.

Synopsis

Declared in <include/boost/url/ipv4_address.hpp>


std::ostream&
operator<<(
    std::ostream& os,
    ipv4_address const& addr);

Description

IPv4 addresses written to output streams are written in their dotted decimal format.

Format the address to an output stream.

IPv4 addresses written to output streams are written in their dotted decimal format.

Parameters

Name	Description
os	The output stream.
addr	The address to format.
os	The output stream.
addr	The address to format.

Format the address to an output stream

Synopsis

Declared in <include/boost/url/ipv6_address.hpp>


std::ostream&
operator<<(
    std::ostream& os,
    ipv6_address const& addr);

Description

This hidden friend function writes the address to an output stream using standard notation.

Format the address to an output stream

This function writes the address to an output stream using standard notation.

Return Value

The output stream, for chaining.

Parameters

Name	Description
os	The output stream to write to.
addr	The address to write.
os	The output stream to write to.
addr	The address to write.

Format the encoded authority to the output stream

Synopsis

Declared in <include/boost/url/authority_view.hpp>


std::ostream&
operator<<(
    std::ostream& os,
    authority_view const& a);

Description

This hidden friend function serializes the encoded URL to the output stream.


authority_view a( "www.example.com" );

std::cout << a << std::endl;

Format the encoded authority to the output stream

This function serializes the encoded URL to the output stream.


authority_view a( "www.example.com" );

std::cout << a << std::endl;

Return Value

A reference to the output stream, for chaining

Parameters

Name	Description
os	The output stream to write to
a	The URL to write
os	The output stream to write to
a	The URL to write

Format the string with percent-decoding applied to the output stream

Synopsis

Declared in <include/boost/url/decode_view.hpp>


std::ostream&
operator<<(
    std::ostream& os,
    decode_view const& s);

Description

This hidden friend function serializes the decoded view to the output stream.

Format the string with percent-decoding applied to the output stream

This function serializes the decoded view to the output stream.

Return Value

A reference to the output stream, for chaining

Parameters

Name	Description
os	The output stream to write to
s	The decoded view to write
os	The output stream to write to
s	The decoded view to write

Format to an output stream

Synopsis

Declared in <include/boost/url/params_encoded_base.hpp>


std::ostream&
operator<<(
    std::ostream& os,
    params_encoded_base const& qp);

Description

Any percent-escapes are emitted as-is; no decoding is performed.

Linear in `ps.buffer().size()`.


return os << ps.buffer();

Format to an output stream

Synopsis

Declared in <include/boost/url/params_base.hpp>


std::ostream&
operator<<(
    std::ostream& os,
    params_base const& qp);

Description

Any percent-escapes are emitted as-is; no decoding is performed.

Linear in `ps.buffer().size()`.


return os << ps.buffer();

Format to an output stream

Synopsis

Declared in <include/boost/url/segments_encoded_base.hpp>


std::ostream&
operator<<(
    std::ostream& os,
    segments_encoded_base const& ps);

Description

Any percent-escapes are emitted as-is; no decoding is performed.

Linear in `ps.buffer().size()`.


return os << ps.buffer();

Format to an output stream

Synopsis

Declared in <include/boost/url/segments_base.hpp>


std::ostream&
operator<<(
    std::ostream& os,
    segments_base const& ps);

Description

Any percent-escapes are emitted as-is; no decoding is performed.

Linear in `ps.buffer().size()`.


return os << ps.buffer();

Format the url to the output stream

Synopsis

Declared in <include/boost/url/url_view_base.hpp>


std::ostream&
operator<<(
    std::ostream& os,
    url_view_base const& u);

Description

This function serializes the url to the specified output stream. Any percent-escapes are emitted as-is; no decoding is performed.


url_view u( "http://www.example.com/index.htm" );
std::stringstream ss;
ss << u;
assert( ss.str() == "http://www.example.com/index.htm" );


return os << u.buffer();

Linear in `u.buffer().size()`

Basic guarantee.

Format the url to the output stream

This function serializes the url to the specified output stream. Any percent-escapes are emitted as-is; no decoding is performed.


url_view u( "http://www.example.com/index.htm" );
std::stringstream ss;
ss << u;
assert( ss.str() == "http://www.example.com/index.htm" );


return os << u.buffer();

Linear in `u.buffer().size()`

Basic guarantee.

Return Value

A reference to the output stream, for chaining

Parameters

Name	Description
os	The output stream to write to.
u	The url to write.
os	The output stream to write to.
u	The url to write.

Return an IPv4 address from an IP address string in dotted decimal form

Synopsis

Declared in <include/boost/url/ipv4_address.hpp>


system::result<ipv4_address>
parse_ipv4_address(core::string_view s) noexcept;

An IP version 6 style address.

Synopsis

Declared in <include/boost/url/ipv6_address.hpp>


class ipv6_address;

Types

Name	Description
`bytes_type`	The type used to represent an address as an array of bytes.

Member Functions

Name	Description
`ipv6_address` [constructor]	Construct from a string. Construct from an IPv4 address. Construct from an array of bytes. Constructor.
`is_loopback`	Return true if the address is a loopback address
`is_unspecified`	Return true if the address is unspecified
`is_v4_mapped`	Return true if the address is a mapped IPv4 address
`operator=`	Copy Assignment
`to_buffer`	Write a dotted decimal string representing the address to a buffer
`to_bytes`	Return the address as bytes, in network byte order
`to_string`	Return the address as a string.

Static Member Functions

Name	Description
`loopback`	Return an address object that represents the loopback address

Static Data Members

Name	Description
`max_str_len`	The number of characters in the longest possible IPv6 string.

Friends

Name	Description
`operator!=`	Return true if two addresses are not equal
`operator<<`	Format the address to an output stream
`operator==`	Return true if two addresses are equal

Description

Objects of this type are used to construct, parse, and manipulate IP version 6 addresses.


IPv6address =                            6( h16 ":" ) ls32
            /                       "::" 5( h16 ":" ) ls32
            / [               h16 ] "::" 4( h16 ":" ) ls32
            / [ *1( h16 ":" ) h16 ] "::" 3( h16 ":" ) ls32
            / [ *2( h16 ":" ) h16 ] "::" 2( h16 ":" ) ls32
            / [ *3( h16 ":" ) h16 ] "::"    h16 ":"   ls32
            / [ *4( h16 ":" ) h16 ] "::"              ls32
            / [ *5( h16 ":" ) h16 ] "::"              h16
            / [ *6( h16 ":" ) h16 ] "::"

ls32        = ( h16 ":" h16 ) / IPv4address
            ; least-significant 32 bits of address

h16         = 1*4HEXDIG
            ; 16 bits of address represented in hexadecimal

IP Version 6 Addressing Architecture (rfc4291)

3.2.2. Host (rfc3986)

Synopsis

Declared in <include/boost/url/ipv6_address.hpp>


constexpr
static
std::size_t const max_str_len = 49;

Description

The longest IPv6 address is:


ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff

Synopsis

Declared in <include/boost/url/ipv6_address.hpp>


using bytes_type = std::array<unsigned char, 16>;

Description

Octets are stored in network byte order.

Constructor.

Synopsis

Declared in <include/boost/url/ipv6_address.hpp>


constexpr
ipv6_address() = default;

» more...


constexpr
ipv6_address(ipv6_address const&) = default;

» more...


ipv6_address(bytes_type const& bytes) noexcept;

» more...


ipv6_address(ipv4_address const& addr) noexcept;

» more...


ipv6_address(core::string_view s);

» more...

Description

Default constructed objects represent the unspecified address.

2.5.2. The Unspecified Address

Exceptions

Name	Thrown on
`[object Object]`	input failed to parse correctly.

Parameters

Name	Description
bytes	The value to construct from.
addr	The address to construct from.
s	The string to parse.

Synopsis

Declared in <include/boost/url/ipv6_address.hpp>


constexpr
ipv6_address() = default;

Description

Default constructed objects represent the unspecified address.

2.5.2. The Unspecified Address

Synopsis

Declared in <include/boost/url/ipv6_address.hpp>


constexpr
ipv6_address(ipv6_address const&) = default;

Construct from an array of bytes.

Synopsis

Declared in <include/boost/url/ipv6_address.hpp>


ipv6_address(bytes_type const& bytes) noexcept;

Description

This function constructs an address from the array in `bytes`, which is interpreted in big-endian.

Parameters

Name	Description
bytes	The value to construct from.

Construct from an IPv4 address.

Synopsis

Declared in <include/boost/url/ipv6_address.hpp>


ipv6_address(ipv4_address const& addr) noexcept;

Description

This function constructs an IPv6 address from the IPv4 address `addr`. The resulting address is an IPv4-Mapped IPv6 Address.

2.5.5.2. IPv4-Mapped IPv6 Address (rfc4291)

Parameters

Name	Description
addr	The address to construct from.

Construct from a string.

Synopsis

Declared in <include/boost/url/ipv6_address.hpp>


ipv6_address(core::string_view s);

Description

This function constructs an address from the string `s`, which must contain a valid IPv6 address string or else an exception is thrown.

NOTE

For a non-throwing parse function, use parse_ipv6_address .

Exceptions thrown on invalid input.

3.2.2. Host (rfc3986)

Exceptions

Name	Thrown on
`The`	input failed to parse correctly.

Parameters

Name	Description
s	The string to parse.

Synopsis

Declared in <include/boost/url/ipv6_address.hpp>


constexpr
ipv6_address&
operator=(ipv6_address const&) = default;

Return the address as bytes, in network byte order

Synopsis

Declared in <include/boost/url/ipv6_address.hpp>


bytes_type
to_bytes() const noexcept;

Return the address as a string.

Synopsis

Declared in <include/boost/url/ipv6_address.hpp>


template<class StringToken = string_token::return_string>
StringToken::result_type
to_string(StringToken&& token) const;

Description

The returned string does not contain surrounding square brackets.

When called with no arguments, the return type is `std::string`. Otherwise, the return type and style of output is determined by which string token is passed.


ipv6_address::bytes_type b = {{
        0, 1, 0, 2, 0, 3, 0, 4,
        0, 5, 0, 6, 0, 7, 0, 8 }};
ipv6_address a(b);
assert(a.to_string() == "1:2:3:4:5:6:7:8");
assert( ipv4_address(0x01020304).to_string() == "1.2.3.4" );

Constant.

Strong guarantee.

Calls to allocate may throw. String tokens may throw exceptions.

2.2. Text Representation of Addresses (rfc4291)

Return Value

The return type of the string token. If the token parameter is omitted, then a new `std::string` is returned. Otherwise, the function return type is the result type of the token.

Parameters

Name	Description
token	An optional string token.

Write a dotted decimal string representing the address to a buffer

Synopsis

Declared in <include/boost/url/ipv6_address.hpp>


core::string_view
to_buffer(
    char* dest,
    std::size_t dest_size) const;

Description

The resulting buffer is not null-terminated.

Exceptions

Name	Thrown on
`dest_size	< ipv6_address::max_str_len`

Return Value

The formatted string

Parameters

Name	Description
dest	The buffer in which to write, which must have at least `dest_size` space.
dest_size	The size of the output buffer.

Return true if the address is unspecified

Synopsis

Declared in <include/boost/url/ipv6_address.hpp>


bool
is_unspecified() const noexcept;

Description

The address 0:0:0:0:0:0:0:0 is called the unspecified address. It indicates the absence of an address.

2.5.2. The Unspecified Address (rfc4291)

Return true if the address is a loopback address

Synopsis

Declared in <include/boost/url/ipv6_address.hpp>


bool
is_loopback() const noexcept;

Description

The unicast address 0:0:0:0:0:0:0:1 is called the loopback address. It may be used by a node to send an IPv6 packet to itself.

2.5.3. The Loopback Address (rfc4291)

Return true if the address is a mapped IPv4 address

Synopsis

Declared in <include/boost/url/ipv6_address.hpp>


bool
is_v4_mapped() const noexcept;

Description

This address type is used to represent the addresses of IPv4 nodes as IPv6 addresses.

2.5.5.2. IPv4-Mapped IPv6 Address (rfc4291)

Return true if two addresses are equal

Synopsis

Declared in <include/boost/url/ipv6_address.hpp>


friend
bool
operator==(
    ipv6_address const& a1,
    ipv6_address const& a2) noexcept;

Return true if two addresses are not equal

Synopsis

Declared in <include/boost/url/ipv6_address.hpp>


friend
bool
operator!=(
    ipv6_address const& a1,
    ipv6_address const& a2) noexcept;

Return an address object that represents the loopback address

Synopsis

Declared in <include/boost/url/ipv6_address.hpp>


static
ipv6_address
loopback() noexcept;

Description

The unicast address 0:0:0:0:0:0:0:1 is called the loopback address. It may be used by a node to send an IPv6 packet to itself.

2.5.3. The Loopback Address (rfc4291)

Format the address to an output stream

Synopsis

Declared in <include/boost/url/ipv6_address.hpp>


friend
std::ostream&
operator<<(
    std::ostream& os,
    ipv6_address const& addr);

Description

This hidden friend function writes the address to an output stream using standard notation.

Return Value

The output stream, for chaining.

Parameters

Name	Description
os	The output stream to write to.
addr	The address to write.

Parse a string containing an IPv6 address.

Synopsis

Declared in <include/boost/url/ipv6_address.hpp>


system::result<ipv6_address>
parse_ipv6_address(core::string_view s) noexcept;

Description

This function attempts to parse the string as an IPv6 address and returns a result containing the address upon success, or an error code if the string does not contain a valid IPv6 address.

Throws nothing.

Return Value

A result containing the address.

Parameters

Name	Description
s	The string to parse.

Percent-encoding options

Synopsis

Declared in <include/boost/url/encoding_opts.hpp>


struct encoding_opts;

Member Functions

Name	Description
`encoding_opts` [constructor]

Data Members

Name	Description
`disallow_null`	True if nulls are not allowed
`lower_case`	True if hexadecimal digits are emitted as lower case
`space_as_plus`	True if spaces encode to and from plus signs

Description

These options are used to customize the behavior of algorithms which use percent escapes, such as encoding or decoding.

Synopsis

Declared in <include/boost/url/encoding_opts.hpp>


bool space_as_plus = false;

Description

This option controls whether or not the PLUS character ("+") is used to represent the SP character (" ") when encoding or decoding. Although not prescribed by the RFC, plus signs are commonly treated as spaces upon decoding when used in the query of URLs using well known schemes such as HTTP.

application/x-www-form-urlencoded (w3.org)

True if hexadecimal digits are emitted as lower case

Synopsis

Declared in <include/boost/url/encoding_opts.hpp>


bool lower_case = false;

Description

By default, percent-encoding algorithms emit hexadecimal digits A through F as uppercase letters. When this option is `true`, lowercase letters are used.

True if nulls are not allowed

Synopsis

Declared in <include/boost/url/encoding_opts.hpp>


bool disallow_null = false;

Description

Normally all possible character values (from 0 to 255) are allowed, with reserved characters being replaced with escapes upon encoding. When this option is true, attempting to decode a null will result in an error.

Synopsis

Declared in <include/boost/url/encoding_opts.hpp>


encoding_opts(
    bool space_as_plus_ = false,
    bool lower_case_ = false,
    bool disallow_null_ = false) noexcept;

A reference to a valid, percent-encoded string

Synopsis

Declared in <include/boost/url/decode_view.hpp>


class decode_view;

Types

Name	Description
`const_iterator`	An iterator of constant, decoded characters.
`const_reference`	The reference type
`difference_type`	The signed integer type
`iterator`	An iterator of constant, decoded characters.
`reference`	The reference type
`size_type`	The unsigned integer type
`value_type`	The value type

Member Functions

Name	Description
`back`	Return the last character
`begin`	Return an iterator to the beginning
`compare`	Return the result of comparing to another string
`decode_view` [constructor]	Constructor
`empty`	Return true if the string is empty
`end`	Return an iterator to the end
`ends_with`	Checks if the string ends with the given prefix
`find`	Finds the first occurrence of character in this view
`front`	Return the first character
`options`	Return the decoding options
`remove_prefix`	Remove the first characters
`remove_suffix`	Remove the last characters
`rfind`	Finds the first occurrence of character in this view
`size`	Return the number of decoded characters
`starts_with`	Checks if the string begins with the given prefix

Friends

Name	Description
`operator!=`	Compare two decode views for inequality
`operator<`	Compare two decode views for less than
`operator<<`	Format the string with percent-decoding applied to the output stream
`operator<=`	Compare two decode views for less than or equal
`operator==`	Compare two decode views for equality
`operator>`	Compare two decode views for greater than
`operator>=`	Compare two decode views for greater than or equal

Description

These views reference strings in parts of URLs or other components that are percent-encoded. The special characters (those not in the allowed character set) are stored as three character escapes that consist of a percent sign ('%%') followed by a two-digit hexadecimal number of the corresponding unescaped character code, which may be part of a UTF-8 code point depending on the context.

The view refers to the original character buffer and only decodes escaped sequences when needed. In particular these operations perform percent-decoding automatically without the need to allocate memory:

Iteration of the string

Accessing the encoded character buffer

Comparison to encoded or plain strings

These objects can only be constructed from strings that have a valid percent-encoding, otherwise construction fails. The caller is responsible for ensuring that the lifetime of the character buffer from which the view is constructed extends unmodified until the view is no longer accessed.

The following operators are supported between

decode_view and any object that is convertible to `core::string_view`


bool operator==( decode_view, decode_view ) noexcept;
bool operator!=( decode_view, decode_view ) noexcept;
bool operator<=( decode_view, decode_view ) noexcept;
bool operator< ( decode_view, decode_view ) noexcept;
bool operator> ( decode_view, decode_view ) noexcept;
bool operator>=( decode_view, decode_view ) noexcept;

The value type

Synopsis

Declared in <include/boost/url/decode_view.hpp>


using value_type = char;

The reference type

Synopsis

Declared in <include/boost/url/decode_view.hpp>


using reference = char;

The reference type

Synopsis

Declared in <include/boost/url/decode_view.hpp>


using const_reference = char;

The unsigned integer type

Synopsis

Declared in <include/boost/url/decode_view.hpp>


using size_type = std::size_t;

The signed integer type

Synopsis

Declared in <include/boost/url/decode_view.hpp>


using difference_type = std::ptrdiff_t;

An iterator of constant, decoded characters.

Synopsis

Declared in <include/boost/url/impl/decode_view.hpp>


class iterator;

Types

Name	Description
`const_reference`
`difference_type`
`iterator_category`
`pointer`
`reference`
`size_type`
`value_type`

Member Functions

Name	Description
`base`
`iterator` [constructor]
`operator!=`
`operator*`
`operator++`
`operator--`
`operator=`
`operator==`

Description

This iterator is used to access the encoded string as a bidirectional range of characters with percent-decoding applied. Escape sequences are not decoded until the iterator is dereferenced.

Synopsis

Declared in <include/boost/url/impl/decode_view.hpp>


using value_type = char;

Synopsis

Declared in <include/boost/url/impl/decode_view.hpp>


using reference = char;

Synopsis

Declared in <include/boost/url/impl/decode_view.hpp>


using pointer = void const*;

Synopsis

Declared in <include/boost/url/impl/decode_view.hpp>


using const_reference = char;

Synopsis

Declared in <include/boost/url/impl/decode_view.hpp>


using size_type = std::size_t;

Synopsis

Declared in <include/boost/url/impl/decode_view.hpp>


using difference_type = std::ptrdiff_t;

Synopsis

Declared in <include/boost/url/impl/decode_view.hpp>


using iterator_category = std::bidirectional_iterator_tag;

Synopsis

Declared in <include/boost/url/impl/decode_view.hpp>


constexpr
iterator() = default;

» more...


constexpr
iterator(iterator const&) = default;

» more...

Synopsis

Declared in <include/boost/url/impl/decode_view.hpp>


constexpr
iterator() = default;

Synopsis

Declared in <include/boost/url/impl/decode_view.hpp>


constexpr
iterator(iterator const&) = default;

Synopsis

Declared in <include/boost/url/impl/decode_view.hpp>


constexpr
iterator&
operator=(iterator const&) = default;

Synopsis

Declared in <include/boost/url/impl/decode_view.hpp>


reference
operator*() const noexcept;

Synopsis

Declared in <include/boost/url/impl/decode_view.hpp>


iterator&
operator++() noexcept;

» more...


iterator
operator++(int) noexcept;

» more...

Synopsis

Declared in <include/boost/url/impl/decode_view.hpp>


iterator&
operator++() noexcept;

Synopsis

Declared in <include/boost/url/impl/decode_view.hpp>


iterator
operator++(int) noexcept;

Synopsis

Declared in <include/boost/url/impl/decode_view.hpp>


iterator&
operator--() noexcept;

» more...


iterator
operator--(int) noexcept;

» more...

Synopsis

Declared in <include/boost/url/impl/decode_view.hpp>


iterator&
operator--() noexcept;

Synopsis

Declared in <include/boost/url/impl/decode_view.hpp>


iterator
operator--(int) noexcept;

Synopsis

Declared in <include/boost/url/impl/decode_view.hpp>


char const*
base();

Synopsis

Declared in <include/boost/url/impl/decode_view.hpp>


bool
operator==(iterator const& other) const noexcept;

Synopsis

Declared in <include/boost/url/impl/decode_view.hpp>


bool
operator!=(iterator const& other) const noexcept;

An iterator of constant, decoded characters.

Synopsis

Declared in <include/boost/url/decode_view.hpp>


using const_iterator = iterator;

Description

This iterator is used to access the encoded string as a bidirectional range of characters with percent-decoding applied. Escape sequences are not decoded until the iterator is dereferenced.

Constructor

Synopsis

Declared in <include/boost/url/decode_view.hpp>


constexpr
decode_view() noexcept = default;

» more...


explicit
decode_view(
    pct_string_view s,
    encoding_opts opt = = {}) noexcept;

» more...

Description

Default-constructed views represent empty strings.


decode_view ds;


this->empty() == true

Constant.

Throws nothing.

Exceptions

Name	Thrown on
`[object Object]`	string contains an invalid percent encoding.

Parameters

Name	Description
s	A percent-encoded string that has already been validated.
opt	The options for decoding. If this parameter is omitted, the default options are used.

Constructor

Synopsis

Declared in <include/boost/url/decode_view.hpp>


constexpr
decode_view() noexcept = default;

Description

Default-constructed views represent empty strings.


decode_view ds;


this->empty() == true

Constant.

Throws nothing.

Constructor

Synopsis

Declared in <include/boost/url/decode_view.hpp>


explicit
decode_view(
    pct_string_view s,
    encoding_opts opt = = {}) noexcept;

Description

This constructs a view from the character buffer `s`, which must remain valid and unmodified until the view is no longer accessed.


decode_view ds( "Program%20Files" );


this->encoded() == s

Linear in `s.size()`.

Exceptions thrown on invalid input.

Exceptions

Name	Thrown on
`The`	string contains an invalid percent encoding.

Parameters

Name	Description
s	A percent-encoded string that has already been validated.
opt	The options for decoding. If this parameter is omitted, the default options are used.

Return true if the string is empty

Synopsis

Declared in <include/boost/url/decode_view.hpp>


bool
empty() const noexcept;

Description


assert( decode_view( "" ).empty() );

Constant.

Throws nothing.

Return the number of decoded characters

Synopsis

Declared in <include/boost/url/decode_view.hpp>


size_type
size() const noexcept;

Description


assert( decode_view( "Program%20Files" ).size() == 13 );


return std::distance( this->begin(), this->end() );

Constant.

Throws nothing.

Return an iterator to the beginning

Synopsis

Declared in <include/boost/url/decode_view.hpp>


iterator
begin() const noexcept;

Description


auto it = this->begin();

Constant.

Throws nothing.

Return an iterator to the end

Synopsis

Declared in <include/boost/url/decode_view.hpp>


iterator
end() const noexcept;

Description


auto it = this->end();

Constant.

Throws nothing.

Return the first character

Synopsis

Declared in <include/boost/url/decode_view.hpp>


reference
front() const noexcept;

Description


assert( decode_view( "Program%20Files" ).front() == 'P' );


not this->empty()

Constant.

Throws nothing.

Return the last character

Synopsis

Declared in <include/boost/url/decode_view.hpp>


reference
back() const noexcept;

Description


assert( decode_view( "Program%20Files" ).back() == 's' );


not this->empty()

Constant.

Throws nothing.

Checks if the string begins with the given prefix

Synopsis

Declared in <include/boost/url/decode_view.hpp>


bool
starts_with(core::string_view s) const noexcept;

» more...


bool
starts_with(char ch) const noexcept;

» more...

Description


assert( decode_view( "Program%20Files" ).starts_with("Program") );

Linear.

Throws nothing.

Checks if the string begins with the given prefix

Synopsis

Declared in <include/boost/url/decode_view.hpp>


bool
starts_with(core::string_view s) const noexcept;

Description


assert( decode_view( "Program%20Files" ).starts_with("Program") );

Linear.

Throws nothing.

Checks if the string begins with the given prefix

Synopsis

Declared in <include/boost/url/decode_view.hpp>


bool
starts_with(char ch) const noexcept;

Description


assert( decode_view( "Program%20Files" ).starts_with('P') );

Constant.

Throws nothing.

Checks if the string ends with the given prefix

Synopsis

Declared in <include/boost/url/decode_view.hpp>


bool
ends_with(core::string_view s) const noexcept;

» more...


bool
ends_with(char ch) const noexcept;

» more...

Description


assert( decode_view( "Program%20Files" ).ends_with("Files") );

Linear.

Throws nothing.

Checks if the string ends with the given prefix

Synopsis

Declared in <include/boost/url/decode_view.hpp>


bool
ends_with(core::string_view s) const noexcept;

Description


assert( decode_view( "Program%20Files" ).ends_with("Files") );

Linear.

Throws nothing.

Checks if the string ends with the given prefix

Synopsis

Declared in <include/boost/url/decode_view.hpp>


bool
ends_with(char ch) const noexcept;

Description


assert( decode_view( "Program%20Files" ).ends_with('s') );

Constant.

Throws nothing.

Finds the first occurrence of character in this view

Synopsis

Declared in <include/boost/url/decode_view.hpp>


const_iterator
find(char ch) const noexcept;

Description

Linear.

Throws nothing.

Finds the first occurrence of character in this view

Synopsis

Declared in <include/boost/url/decode_view.hpp>


const_iterator
rfind(char ch) const noexcept;

Description

Linear.

Throws nothing.

Remove the first characters

Synopsis

Declared in <include/boost/url/decode_view.hpp>


void
remove_prefix(size_type n);

Description


decode_view d( "Program%20Files" );
d.remove_prefix( 8 );
assert( d == "Files" );


not this->empty()

Linear.

Remove the last characters

Synopsis

Declared in <include/boost/url/decode_view.hpp>


void
remove_suffix(size_type n);

Description


decode_view d( "Program%20Files" );
d.remove_prefix( 6 );
assert( d == "Program" );


not this->empty()

Linear.

Return the decoding options

Synopsis

Declared in <include/boost/url/decode_view.hpp>


encoding_opts
options() const noexcept;

Return the result of comparing to another string

Synopsis

Declared in <include/boost/url/decode_view.hpp>


int
compare(core::string_view other) const noexcept;

» more...


int
compare(decode_view other) const noexcept;

» more...

Description

The length of the sequences to compare is the smaller of `size()` and `other.size()`.

The function compares the two strings as if by calling `char_traits::compare(to_string().data(), v.data(), rlen)`. This means the comparison is performed with percent-decoding applied to the current string.

Return Value

Negative value if this string is less than the other character sequence, zero if the both character sequences are equal, positive value if this string is greater than the other character sequence

Parameters

Name	Description
other	string to compare

Return the result of comparing to another string

Synopsis

Declared in <include/boost/url/decode_view.hpp>


int
compare(core::string_view other) const noexcept;

Description

The length of the sequences to compare is the smaller of `size()` and `other.size()`.

Return Value

Negative value if this string is less than the other character sequence, zero if the both character sequences are equal, positive value if this string is greater than the other character sequence

Parameters

Name	Description
other	string to compare

Return the result of comparing to another string

Synopsis

Declared in <include/boost/url/decode_view.hpp>


int
compare(decode_view other) const noexcept;

Description

The length of the sequences to compare is the smaller of `size()` and `other.size()`.

The function compares the two strings as if by calling `char_traits::compare(to_string().data(), v.to_string().data(), rlen)`. This means the comparison is performed with percent-decoding applied to the current string.

Return Value

Negative value if this string is less than the other character sequence, zero if the both character sequences are equal, positive value if this string is greater than the other character sequence

Parameters

Name	Description
other	string to compare

Compare two decode views for equality

Synopsis

Declared in <include/boost/url/decode_view.hpp>


template<
    class S0,
    class S1>
friend
constexpr
bool
operator==(
    S0 const& s0,
    S1 const& s1) noexcept;

Description

This function is only enabled if both types are decode_view or convertible to `core::string_view`, but not both are convertible to `core::string_view`

Compare two decode views for inequality

Synopsis

Declared in <include/boost/url/decode_view.hpp>


template<
    class S0,
    class S1>
friend
constexpr
bool
operator!=(
    S0 const& s0,
    S1 const& s1) noexcept;

Description

This function is only enabled if both types are decode_view or convertible to `core::string_view`, but not both are convertible to `core::string_view`

Compare two decode views for less than

Synopsis

Declared in <include/boost/url/decode_view.hpp>


template<
    class S0,
    class S1>
friend
constexpr
bool
operator<(
    S0 const& s0,
    S1 const& s1) noexcept;

Description

This function is only enabled if both types are decode_view or convertible to `core::string_view`, but not both are convertible to `core::string_view`

Compare two decode views for less than or equal

Synopsis

Declared in <include/boost/url/decode_view.hpp>


template<
    class S0,
    class S1>
friend
constexpr
bool
operator<=(
    S0 const& s0,
    S1 const& s1) noexcept;

Description

This function is only enabled if both types are decode_view or convertible to `core::string_view`, but not both are convertible to `core::string_view`

Compare two decode views for greater than

Synopsis

Declared in <include/boost/url/decode_view.hpp>


template<
    class S0,
    class S1>
friend
constexpr
bool
operator>(
    S0 const& s0,
    S1 const& s1) noexcept;

Description

This function is only enabled if both types are decode_view or convertible to `core::string_view`, but not both are convertible to `core::string_view`

Compare two decode views for greater than or equal

Synopsis

Declared in <include/boost/url/decode_view.hpp>


template<
    class S0,
    class S1>
friend
constexpr
bool
operator>=(
    S0 const& s0,
    S1 const& s1) noexcept;

Description

This function is only enabled if both types are decode_view or convertible to `core::string_view`, but not both are convertible to `core::string_view`

Format the string with percent-decoding applied to the output stream

Synopsis

Declared in <include/boost/url/decode_view.hpp>


friend
std::ostream&
operator<<(
    std::ostream& os,
    decode_view const& s);

Description

This hidden friend function serializes the decoded view to the output stream.

Return Value

A reference to the output stream, for chaining

Parameters

Name	Description
os	The output stream to write to
s	The decoded view to write

A reference to a valid percent-encoded string

Synopsis

Declared in <include/boost/url/pct_string_view.hpp>


class pct_string_view
    : public grammar::string_view_base;

Types

Name	Description
`const_iterator`	The const iterator type
`const_pointer`	The const pointer type
`const_reference`	The const reference type
`const_reverse_iterator`	The const reverse iterator type
`difference_type`	The difference type
`iterator`	The iterator type
`pointer`	The pointer type
`reference`	The reference type
`reverse_iterator`	The reverse iterator type
`size_type`	The size type
`traits_type`	The character traits
`value_type`	The value type

Member Functions

Name	Description
`at`	Access a character
`back`	Return the last character
`begin`	Return an iterator to the beginning
`cbegin`	Return an iterator to the beginning
`cend`	Return an iterator to the end
`compare`	Return the result of comparing to another string
`contains`	Return true if matching characters are found
`copy`	Copy the characters to another buffer
`crbegin`	Return a reverse iterator to the end
`crend`	Return a reverse iterator to the beginning
`data`	Return a pointer to the character buffer
`decode`	Return the string with percent-decoding
`decoded_size`	Return the decoded size
`empty`	Return true if the string is empty
`end`	Return an iterator to the end
`ends_with`	Return true if a matching suffix exists
`find`	Return the position of matching characters
`find_first_not_of`	Return the position of the first non-match
`find_first_of`	Return the position of the first match
`find_last_not_of`	Return the position of the last non-match
`find_last_of`	Return the position of the last match
`front`	Return the first character
`length`	Return the size
`max_size`	Return the maximum allowed size
`operator std::string`	Conversion
`operator core::string_view`	Conversion
`operator*`	Return the string as a range of decoded characters
`operator->`	Arrow support
`operator=`	Assignment
`operator[]`	Access a character
`pct_string_view` [constructor]	Constructor (deleted) Constructor
`rbegin`	Return a reverse iterator to the end
`rend`	Return a reverse iterator to the beginning
`rfind`	Return the position of matching characters
`size`	Return the size
`starts_with`	Return true if a matching prefix exists
`substr`	Return a view to part of the string
`swap`	Swap

Static Data Members

Name	Description
`npos`	A constant used to represent "no position"

Friends

Name	Description
`make_pct_string_view`	Return a valid percent-encoded string
`operator!=`	Compare two string views for inequality
`operator<`	Compare two string views for less than
`operator<<`	Format a string to an output stream
`operator<=`	Compare two string views for less than or equal
`operator==`	Compare two string views for equality
`operator>`	Compare two string views for greater than
`operator>=`	Compare two string views for greater than or equal

Description

Objects of this type behave like a `core::string_view` and have the same interface, but offer an additional invariant: they can only be constructed from strings containing valid percent-escapes.

Attempting construction from a string containing invalid or malformed percent escapes results in an exception.

The following operators are supported between

pct_string_view and any object that is convertible to `core::string_view`


bool operator==( pct_string_view, pct_string_view ) noexcept;
bool operator!=( pct_string_view, pct_string_view ) noexcept;
bool operator<=( pct_string_view, pct_string_view ) noexcept;
bool operator< ( pct_string_view, pct_string_view ) noexcept;
bool operator> ( pct_string_view, pct_string_view ) noexcept;
bool operator>=( pct_string_view, pct_string_view ) noexcept;

Constructor

Synopsis

Declared in <include/boost/url/pct_string_view.hpp>


constexpr
pct_string_view() = default;

» more...


constexpr
pct_string_view(pct_string_view const& other) = default;

» more...


template<
    class String,
    class = void>
pct_string_view(String const& s);

» more...


pct_string_view(std::nullptr_t) = delete;

» more...


pct_string_view(
    char const* s,
    std::size_t len);

» more...


pct_string_view(core::string_view s);

» more...

Description

Default constructed string are empty.

Constant.

Throws nothing.

Exceptions

Name	Thrown on
`[object Object]`	string contains an invalid percent encoding.

Parameters

Name	Description
s,	len The string to construct from.
s	The string to construct from.

Constructor

Synopsis

Declared in <include/boost/url/pct_string_view.hpp>


constexpr
pct_string_view() = default;

Description

Default constructed string are empty.

Constant.

Throws nothing.

Constructor

Synopsis

Declared in <include/boost/url/pct_string_view.hpp>


constexpr
pct_string_view(pct_string_view const& other) = default;

Description

The copy references the same underlying character buffer. Ownership is not transferred.


this->data() == other.data()

Constant.

Throws nothing.

Synopsis

Declared in <include/boost/url/pct_string_view.hpp>


template<
    class String,
    class = void>
pct_string_view(String const& s);

Constructor (deleted)

Synopsis

Declared in <include/boost/url/pct_string_view.hpp>


pct_string_view(std::nullptr_t) = delete;

Constructor

Synopsis

Declared in <include/boost/url/pct_string_view.hpp>


pct_string_view(
    char const* s,
    std::size_t len);

Description

The newly constructed string references the specified character buffer. Ownership is not transferred.


this->data() == s && this->size() == len

Linear in `len`.

Exceptions thrown on invalid input.

Exceptions

Name	Thrown on
`The`	string contains an invalid percent encoding.

Parameters

Name	Description
s,	len The string to construct from.

Constructor

Synopsis

Declared in <include/boost/url/pct_string_view.hpp>


pct_string_view(core::string_view s);

Description

The newly constructed string references the specified character buffer. Ownership is not transferred.


this->data() == s.data() && this->size() == s.size()

Linear in `s.size()`.

Exceptions thrown on invalid input.

Exceptions

Name	Thrown on
`The`	string contains an invalid percent encoding.

Parameters

Name	Description
s	The string to construct from.

Assignment

Synopsis

Declared in <include/boost/url/pct_string_view.hpp>


constexpr
pct_string_view&
operator=(pct_string_view const& other) = default;

Description

The copy references the same underlying character buffer. Ownership is not transferred.


this->data() == other.data()

Constant.

Throws nothing.

Return a valid percent-encoded string

Synopsis

Declared in <include/boost/url/pct_string_view.hpp>


friend
system::result<pct_string_view>
make_pct_string_view(core::string_view s) noexcept;

Description

If `s` is a valid percent-encoded string, the function returns the buffer as a valid view which may be used to perform decoding or measurements. Otherwise the result contains an error code. Upon success, the returned view references the original character buffer; Ownership is not transferred.

Linear in `s.size()`.

Throws nothing.

Parameters

Name	Description
s	The string to validate.

Return the decoded size

Synopsis

Declared in <include/boost/url/pct_string_view.hpp>


std::size_t
decoded_size() const noexcept;

Description

This function returns the number of characters in the resulting string if percent escapes were converted into ordinary characters.

Constant.

Throws nothing.

Return the string as a range of decoded characters

Synopsis

Declared in <include/boost/url/pct_string_view.hpp>


decode_view
operator*() const noexcept;

Description

Constant.

Throws nothing.

Synopsis

Declared in <include/boost/url/pct_string_view.hpp>


template<class StringToken = string_token::return_string>
StringToken::result_type
decode(
    encoding_opts opt = = {},
    StringToken&& token) const;

Description

This function converts percent escapes in the string into ordinary characters and returns the result. When called with no arguments, the return type is `std::string`. Otherwise, the return type and style of output is determined by which string token is passed.


assert( pct_string_view( "Program%20Files" ).decode() == "Program Files" );

Linear in `this->size()`.

Calls to allocate may throw.

String tokens may throw exceptions.

Parameters

Name	Description
opt	The options for encoding. If this parameter is omitted, the default options are used.
token	An optional string token. If this parameter is omitted, then a new `std::string` is returned. Otherwise, the function return type is the result type of the token.

Synopsis

Declared in <include/boost/url/pct_string_view.hpp>


pct_string_view const*
operator->() const noexcept;

Swap

Synopsis

Declared in <include/boost/url/pct_string_view.hpp>


void
swap(pct_string_view& s) noexcept;

Return a valid percent-encoded string

Synopsis

Declared in <include/boost/url/pct_string_view.hpp>


system::result<pct_string_view>
make_pct_string_view(core::string_view s) noexcept;

Description

Linear in `s.size()`.

Throws nothing.

Return a valid percent-encoded string

Linear in `s.size()`.

Throws nothing.

Parameters

Name	Description
s	The string to validate.
s	The string to validate.

Identifies a known URL scheme

Synopsis

Declared in <include/boost/url/scheme.hpp>


enum scheme : unsigned short;

Members

Name	Description
none	Indicates that no scheme is present
unknown	Indicates the scheme is not a well-known scheme
ftp	File Transfer Protocol (FTP)
file	File URI Scheme
http	The Hypertext Transfer Protocol URI Scheme
https	The Secure Hypertext Transfer Protocol URI Scheme
ws	The WebSocket URI Scheme
wss	The Secure WebSocket URI Scheme

Description

3.1. Scheme (rfc3986)

Indicates that no scheme is present

Synopsis

Declared in <include/boost/url/scheme.hpp>


none = 0

Indicates the scheme is not a well-known scheme

Synopsis

Declared in <include/boost/url/scheme.hpp>


unknown

File Transfer Protocol (FTP)

Synopsis

Declared in <include/boost/url/scheme.hpp>

ftp

Description

FTP is a standard communication protocol used for the transfer of computer files from a server to a client on a computer network.

The 'ftp' URI Scheme

File URI Scheme

Synopsis

Declared in <include/boost/url/scheme.hpp>


file

Description

The File URI Scheme is typically used to retrieve files from within one's own computer.

The "file" URI Scheme (rfc8089)

The Hypertext Transfer Protocol URI Scheme

Synopsis

Declared in <include/boost/url/scheme.hpp>


http

Description

URLs of this type indicate a resource which is interacted with using the HTTP protocol.

Hypertext Transfer Protocol (HTTP/1.1) (rfc7230)

The Secure Hypertext Transfer Protocol URI Scheme

Synopsis

Declared in <include/boost/url/scheme.hpp>


https

Description

URLs of this type indicate a resource which is interacted with using the Secure HTTP protocol.

Hypertext Transfer Protocol (HTTP/1.1) (rfc7230)

The WebSocket URI Scheme

Synopsis

Declared in <include/boost/url/scheme.hpp>

ws

Description

URLs of this type indicate a resource which is interacted with using the WebSocket protocol.

The WebSocket Protocol (rfc6455)

The Secure WebSocket URI Scheme

Synopsis

Declared in <include/boost/url/scheme.hpp>

wss

Description

URLs of this type indicate a resource which is interacted with using the Secure WebSocket protocol.

The WebSocket Protocol (rfc6455)

Return the known scheme for a non-normalized string, if known

Synopsis

Declared in <include/boost/url/scheme.hpp>


scheme
string_to_scheme(core::string_view s) noexcept;

Description

If the string does not identify a known scheme, the value scheme::unknown is returned.


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

3.1. Scheme (rfc3986)

Return Value

The known scheme

Parameters

Name	Description
s	The string holding the scheme

Return the normalized string for a known scheme

Synopsis

Declared in <include/boost/url/scheme.hpp>


core::string_view
to_string(scheme s) noexcept;

Return Value

A string representing the known scheme

Parameters

Name	Description
s	The known scheme constant

Return the default port for a known scheme

Synopsis

Declared in <include/boost/url/scheme.hpp>


std::uint16_t
default_port(scheme s) noexcept;

Description

This function returns the default port for the known schemes. If the value does not represent a known scheme or the scheme does not represent a protocol, the function returns zero.

The following ports are returned by the function:

scheme::ftp = 21

scheme::http , scheme::ws = 80

scheme::https , scheme::wss = 443

Return Value

An integer with the default port number

Parameters

Name	Description
s	The known scheme constant

A non-owning reference to a valid URL

Synopsis

Declared in <include/boost/url/url_view.hpp>


class url_view
    : public url_view_base;

Member Functions

Name	Description
`authority`	Return the authority
`buffer`	Return the url string
`compare`	Return the result of comparing this with another url
`data`	Return a pointer to the url's character buffer
`empty`	Return true if the url is empty
`encoded_authority`	Return the authority.
`encoded_fragment`	Return the fragment
`encoded_host`	Return the host
`encoded_host_address`	Return the host
`encoded_host_and_port`	Return the host and port
`encoded_host_name`	Return the host name
`encoded_origin`	Return the origin
`encoded_params`	Return the query as a container of parameters
`encoded_password`	Return the password
`encoded_path`	Return the path
`encoded_query`	Return the query
`encoded_resource`	Return the resource
`encoded_segments`	Return the path as a container of segments
`encoded_target`	Return the target
`encoded_user`	Return the user
`encoded_userinfo`	Return the userinfo
`encoded_zone_id`	Return the IPv6 Zone ID
`fragment`	Return the fragment
`has_authority`	Return true if an authority is present
`has_fragment`	Return true if a fragment is present
`has_password`	Return true if a password is present
`has_port`	Return true if a port is present
`has_query`	Return true if a query is present
`has_scheme`	Return true a scheme is present
`has_userinfo`	Return true if a userinfo is present
`host`	Return the host
`host_address`	Return the host
`host_ipv4_address`	Return the host IPv4 address
`host_ipv6_address`	Return the host IPv6 address
`host_ipvfuture`	Return the host IPvFuture address
`host_name`	Return the host name
`host_type`	Return the host type
`is_path_absolute`	Return true if the path is absolute
`operator core::string_view`	Return the URL as a core::string_view
`operator=`	Assignment
`params`	Return the query as a container of parameters
`password`	Return the password
`path`	Return the path
`persist`	Return a shared, persistent copy of the url
`port`	Return the port
`port_number`	Return the port
`query`	Return the query
`scheme`	Return the scheme
`scheme_id`	Return the scheme
`segments`	Return the path as a container of segments
`size`	Return the number of characters in the url
`url_view` [constructor]	Constructor
`user`	Return the user
`userinfo`	Return the userinfo
`zone_id`	Return the IPv6 Zone ID
`~url_view` [destructor]	Destructor

Static Member Functions

Name	Description
`max_size`	Return the maximum number of characters possible

Friends

Name	Description
`operator!=`	Return the result of comparing two URLs
`operator<`	Return the result of comparing two URLs
`operator<<`	Format the url to the output stream
`operator<=`	Return the result of comparing two URLs
`operator==`	Return the result of comparing two URLs
`operator>`	Return the result of comparing two URLs
`operator>=`	Return the result of comparing two URLs

Description

Objects of this type represent valid URL strings constructed from a parsed, external character buffer whose storage is managed by the caller. That is, it acts like a `core::string_view` in terms of ownership. The caller is responsible for ensuring that the lifetime of the underlying character buffer extends until it is no longer referenced.

Construction from a string parses the input

as a URI-reference and throws an exception on error. Upon success, the constructed object points to the passed character buffer; ownership is not transferred.


url_view u( "https://www.example.com/index.htm?text=none#a1" );

Parsing functions like

parse_uri_reference return a result containing either a valid url_view upon succcess, otherwise they contain an error. The error can be converted to an exception by the caller if desired:


system::result< url_view > rv = parse_uri_reference( "https://www.example.com/index.htm?text=none#a1" );


URI-reference = URI / relative-ref

URI           = scheme ":" hier-part [ "?" query ] [ "#" fragment ]

relative-ref  = relative-part [ "?" query ] [ "#" fragment ]

Uniform Resource Identifier (URI): Generic Syntax (rfc3986)

Synopsis

Declared in <include/boost/url/url_view.hpp>


constexpr
~url_view() = default;

Description

Any params, segments, iterators, or other views which reference the same underlying character buffer remain valid.

Constructor

Synopsis

Declared in <include/boost/url/url_view.hpp>


url_view() noexcept;

» more...


url_view(core::string_view s);

» more...


template<
    class String,
    class = void>
url_view(String const& s);

» more...


url_view(url_view const& other) noexcept;

» more...


url_view(url_view_base const& other) noexcept;

» more...

Description

Default constructed views refer to a string with zero length, which always remains valid. This matches the grammar for a relative-ref with an empty path and no query or fragment.


url_view u;


this->empty() == true

Constant.

Throws nothing.


relative-ref  = relative-part [ "?" query ] [ "#" fragment ]

4.2. Relative Reference (rfc3986)

Exceptions

Name	Thrown on
`[object Object]`	input failed to parse correctly.

Parameters

Name	Description
s	The string to parse.

Constructor

Synopsis

Declared in <include/boost/url/url_view.hpp>


url_view() noexcept;

Description

Default constructed views refer to a string with zero length, which always remains valid. This matches the grammar for a relative-ref with an empty path and no query or fragment.


url_view u;


this->empty() == true

Constant.

Throws nothing.


relative-ref  = relative-part [ "?" query ] [ "#" fragment ]

4.2. Relative Reference (rfc3986)

Constructor

Synopsis

Declared in <include/boost/url/url_view.hpp>


url_view(core::string_view s);

Description

This function constructs a URL from the string `s`, which must contain a valid URI or relative-ref or else an exception is thrown. Upon successful construction, the view refers to the characters in the buffer pointed to by `s`. Ownership is not transferred; The caller is responsible for ensuring that the lifetime of the buffer extends until it is no longer referenced.


url_view u( "http://www.example.com/index.htm" );


return parse_uri_reference( s ).value();

Linear in `s.size()`.

Exceptions thrown on invalid input.


URI           = scheme ":" hier-part [ "?" query ] [ "#" fragment ]

relative-ref  = relative-part [ "?" query ] [ "#" fragment ]

4.1. URI Reference

Exceptions

Name	Thrown on
`The`	input failed to parse correctly.

Parameters

Name	Description
s	The string to parse.

Synopsis

Declared in <include/boost/url/url_view.hpp>


template<
    class String,
    class = void>
url_view(String const& s);

Constructor

Synopsis

Declared in <include/boost/url/url_view.hpp>


url_view(url_view const& other) noexcept;

Description

After construction, both views reference the same underlying character buffer. Ownership is not transferred.


this->buffer().data() == other.buffer().data()

Constant.

Throws nothing.

Constructor

Synopsis

Declared in <include/boost/url/url_view.hpp>


url_view(url_view_base const& other) noexcept;

Description

After construction, both views reference the same underlying character buffer. Ownership is not transferred.


this->buffer().data() == other.buffer().data()

Constant.

Throws nothing.

Assignment

Synopsis

Declared in <include/boost/url/url_view.hpp>


url_view&
operator=(url_view const& other) noexcept;

» more...


url_view&
operator=(url_view_base const& other) noexcept;

» more...

Description

After assignment, both views reference the same underlying character buffer. Ownership is not transferred.


this->buffer().data() == other.buffer().data()

Constant.

Throws nothing.

Assignment

Synopsis

Declared in <include/boost/url/url_view.hpp>


url_view&
operator=(url_view const& other) noexcept;

Description

After assignment, both views reference the same underlying character buffer. Ownership is not transferred.


this->buffer().data() == other.buffer().data()

Constant.

Throws nothing.

Assignment

Synopsis

Declared in <include/boost/url/url_view.hpp>


url_view&
operator=(url_view_base const& other) noexcept;

Description

After assignment, both views reference the same underlying character buffer. Ownership is not transferred.


this->buffer().data() == other.buffer().data()

Constant.

Throws nothing.

Return the maximum number of characters possible

Synopsis

Declared in <include/boost/url/url_view.hpp>


constexpr
static
std::size_t
max_size() noexcept;

Description

This represents the largest number of characters that are possible in a url, not including any null terminator.

Constant.

Throws nothing.

A non-owning reference to a valid authority

Synopsis

Declared in <include/boost/url/authority_view.hpp>


class authority_view;

Member Functions

Name	Description
`authority_view` [constructor]	Construct from a string. Constructor
`buffer`	Return the complete authority
`compare`	Return the result of comparing this with another authority
`data`	Return a pointer to the first character
`empty`	Return true if the authority is empty
`encoded_host`	Return the host
`encoded_host_address`	Return the host
`encoded_host_and_port`	Return the host and port
`encoded_host_name`	Return the host name
`encoded_password`	Return the password
`encoded_user`	Return the user
`encoded_userinfo`	Return the userinfo
`has_password`	Return true if a password is present
`has_port`	Return true if a port is present
`has_userinfo`	Return true if a userinfo is present
`host`	Return the host
`host_address`	Return the host
`host_ipv4_address`	Return the host IPv4 address
`host_ipv6_address`	Return the host IPv6 address
`host_ipvfuture`	Return the host IPvFuture address
`host_name`	Return the host name
`host_type`	Return the host type
`operator=`	Assignment
`password`	Return the password
`port`	Return the port
`port_number`	Return the port
`size`	Return the number of characters in the authority
`user`	Return the user
`userinfo`	Return the userinfo
`~authority_view` [destructor]	Destructor

Friends

Name	Description
`operator!=`	Return the result of comparing two authorities The authorities are compared component by component as if they were first normalized.
`operator<`	Return the result of comparing two authorities The authorities are compared component by component as if they were first normalized.
`operator<<`	Format the encoded authority to the output stream
`operator<=`	Return the result of comparing two authorities The authorities are compared component by component as if they were first normalized.
`operator==`	Return the result of comparing two authorities The authorities are compared component by component as if they were first normalized.
`operator>`	Return the result of comparing two authorities The authorities are compared component by component as if they were first normalized.
`operator>=`	Return the result of comparing two authorities The authorities are compared component by component as if they were first normalized.

Description

Objects of this type represent valid authority strings constructed from a parsed, external character buffer whose storage is managed by the caller. That is, it acts like a `core::string_view` in terms of ownership. The caller is responsible for ensuring that the lifetime of the underlying character buffer extends until it is no longer referenced.

Construction from a string parses the input

as an authority and throws an exception on error. Upon success, the constructed object points to the passed character buffer; ownership is not transferred.


authority_view a( "user:pass@www.example.com:8080" );

The parsing function

parse_authority returns a result containing either a valid authority_view upon succcess, otherwise it contain an error. The error can be converted to an exception by the caller if desired:


system::result< authority_view > rv = parse_authority( "user:pass@www.example.com:8080" );


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

userinfo      = user [ ":" [ password ] ]

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

host          = IP-literal / IPv4address / reg-name

port          = *DIGIT

3.2. Authority (rfc3986)

Synopsis

Declared in <include/boost/url/authority_view.hpp>


virtual
~authority_view();

Constructor

Synopsis

Declared in <include/boost/url/authority_view.hpp>


authority_view() noexcept;

» more...


explicit
authority_view(core::string_view s);

» more...


authority_view(authority_view const&) noexcept;

» more...

Description

Default constructed authorities refer to a string with zero length, which is always valid. This matches the grammar for a zero-length host.

Throws nothing.

Constructor

Synopsis

Declared in <include/boost/url/authority_view.hpp>


authority_view() noexcept;

Description

Default constructed authorities refer to a string with zero length, which is always valid. This matches the grammar for a zero-length host.

Throws nothing.

Construct from a string.

Synopsis

Declared in <include/boost/url/authority_view.hpp>


explicit
authority_view(core::string_view s);

Description

This function attempts to construct an authority from the string `s`, which must be a valid ['authority] or else an exception is thrown. Upon successful construction, the view refers to the characters in the buffer pointed to by `s`. Ownership is not transferred; The caller is responsible for ensuring that the lifetime of the buffer extends until the view is destroyed.


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

userinfo      = user [ ":" [ password ] ]

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

host          = IP-literal / IPv4address / reg-name

port          = *DIGIT

3.2. Authority (rfc3986)

Synopsis

Declared in <include/boost/url/authority_view.hpp>


authority_view(authority_view const&) noexcept;

Assignment

Synopsis

Declared in <include/boost/url/authority_view.hpp>


authority_view&
operator=(authority_view const&) noexcept;

Return the number of characters in the authority

Synopsis

Declared in <include/boost/url/authority_view.hpp>


std::size_t
size() const noexcept;

Description

This function returns the number of characters in the authority.


assert( authority_view( "user:pass@www.example.com:8080" ).size() == 30 );

Throws nothing.

Return true if the authority is empty

Synopsis

Declared in <include/boost/url/authority_view.hpp>


bool
empty() const noexcept;

Description

An empty authority has an empty host, no userinfo, and no port.


assert( authority_view( "" ).empty() );

Throws nothing.

Return a pointer to the first character

Synopsis

Declared in <include/boost/url/authority_view.hpp>


char const*
data() const noexcept;

Description

This function returns a pointer to the beginning of the view, which is not guaranteed to be null-terminated.

Throws nothing.

Return the complete authority

Synopsis

Declared in <include/boost/url/authority_view.hpp>


core::string_view
buffer() const noexcept;

Description

This function returns the authority as a percent-encoded string.


assert( parse_authority( "www.example.com" ).value().buffer() == "www.example.com" );


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

Throws nothing.

3.2. Authority (rfc3986)

Return true if a userinfo is present

Synopsis

Declared in <include/boost/url/authority_view.hpp>


bool
has_userinfo() const noexcept;

Description

This function returns true if this contains a userinfo.


assert( url_view( "http://jane%2Ddoe:pass@example.com" ).has_userinfo() );

Constant.

Throws nothing.


userinfo    = user [ ":" [ password ] ]

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

3.2.1. User Information (rfc3986)

Synopsis

Declared in <include/boost/url/authority_view.hpp>


template<class StringToken = string_token::return_string>
StringToken::result_type
userinfo(StringToken&& token) const;

Description

If present, this function returns a string representing the userinfo (which may be empty). Otherwise it returns an empty string. Any percent-escapes in the string are decoded first.


assert( url_view( "http://jane%2Ddoe:pass@example.com" ).userinfo() == "jane-doe:pass" );

Linear in `this->userinfo().size()`.

Calls to allocate may throw.


userinfo    = user [ ":" [ password ] ]

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

3.2.1. User Information (rfc3986)

Synopsis

Declared in <include/boost/url/authority_view.hpp>


pct_string_view
encoded_userinfo() const noexcept;

Description

If present, this function returns a string representing the userinfo (which may be empty). Otherwise it returns an empty string. The returned string may contain percent escapes.


assert( url_view( "http://jane%2Ddoe:pass@example.com" ).encoded_userinfo() == "jane%2Ddoe:pass" );

Constant.

Throws nothing


userinfo    = user [ ":" [ password ] ]

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

3.2.1. User Information (rfc3986)

Synopsis

Declared in <include/boost/url/authority_view.hpp>


template<class StringToken = string_token::return_string>
StringToken::result_type
user(StringToken&& token) const;

Description

If present, this function returns a string representing the user (which may be empty). Otherwise it returns an empty string. Any percent-escapes in the string are decoded first.


assert( url_view( "http://jane%2Ddoe:pass@example.com" ).user() == "jane-doe" );

Linear in `this->user().size()`.

Calls to allocate may throw.


userinfo    = user [ ":" [ password ] ]

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

3.2.1. User Information (rfc3986)

Synopsis

Declared in <include/boost/url/authority_view.hpp>


pct_string_view
encoded_user() const noexcept;

Description

If present, this function returns a string representing the user (which may be empty). Otherwise it returns an empty string. The returned string may contain percent escapes.


assert( url_view( "http://jane%2Ddoe:pass@example.com" ).encoded_user() == "jane%2Ddoe" );

Constant.

Throws nothing.


userinfo    = user [ ":" [ password ] ]

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

3.2.1. User Information (rfc3986)

Synopsis

Declared in <include/boost/url/authority_view.hpp>


bool
has_password() const noexcept;

Description

This function returns true if the userinfo is present and contains a password.


assert( url_view( "http://jane%2Ddoe:pass@example.com" ).has_password() );

Constant.

Throws nothing.


userinfo    = user [ ":" [ password ] ]

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

3.2.1. User Information (rfc3986)

Synopsis

Declared in <include/boost/url/authority_view.hpp>


template<class StringToken = string_token::return_string>
StringToken::result_type
password(StringToken&& token) const;

Description

If present, this function returns a string representing the password (which may be an empty string). Otherwise it returns an empty string. Any percent-escapes in the string are decoded first.


assert( url_view( "http://jane%2Ddoe:pass@example.com" ).password() == "pass" );

Linear in `this->password().size()`.

Calls to allocate may throw.


userinfo    = user [ ":" [ password ] ]

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

3.2.1. User Information (rfc3986)

Synopsis

Declared in <include/boost/url/authority_view.hpp>


pct_string_view
encoded_password() const noexcept;

Description

This function returns the password portion of the userinfo as a percent-encoded string.


assert( url_view( "http://jane%2Ddoe:pass@example.com" ).encoded_password() == "pass" );

Constant.

Throws nothing.


userinfo    = user [ ":" [ password ] ]

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

3.2.1. User Information (rfc3986)

Synopsis

Declared in <include/boost/url/authority_view.hpp>


urls::host_type
host_type() const noexcept;

Description

This function returns one of the following constants representing the type of host present.


assert( url_view( "https://192.168.0.1/local.htm" ).host_type() == host_type::ipv4 );

Constant.

Throws nothing.

3.2.2. Host (rfc3986)

Return the host

Synopsis

Declared in <include/boost/url/authority_view.hpp>


template<class StringToken = string_token::return_string>
StringToken::result_type
host(StringToken&& token) const;

Description

This function returns the host portion of the authority as a string, or the empty string if there is no authority. Any percent-escapes in the string are decoded first.


assert( url_view( "https://www%2droot.example.com/" ).host() == "www-root.example.com" );

Linear in `this->host().size()`.

Calls to allocate may throw.


host        = IP-literal / IPv4address / reg-name

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

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

3.2.2. Host (rfc3986)

Return the host

Synopsis

Declared in <include/boost/url/authority_view.hpp>


pct_string_view
encoded_host() const noexcept;

Description

This function returns the host portion of the authority as a string, or the empty string if there is no authority. The returned string may contain percent escapes.


assert( url_view( "https://www%2droot.example.com/" ).encoded_host() == "www%2droot.example.com" );

Constant.

Throws nothing.


host        = IP-literal / IPv4address / reg-name

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

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

3.2.2. Host (rfc3986)

Return the host

Synopsis

Declared in <include/boost/url/authority_view.hpp>


template<class StringToken = string_token::return_string>
StringToken::result_type
host_address(StringToken&& token) const;

Description

The value returned by this function depends on the type of host returned from the function host_type .

If the type is host_type::ipv4 , then the IPv4 address string is returned.

If the type is host_type::ipv6 , then the IPv6 address string is returned, without any enclosing brackets.

If the type is host_type::ipvfuture , then the IPvFuture address string is returned, without any enclosing brackets.

If the type is host_type::name , then the host name string is returned. Any percent-escapes in the string are decoded first.

If the type is host_type::none , then an empty string is returned.


assert( url_view( "https://[1::6:c0a8:1]/" ).host_address() == "1::6:c0a8:1" );

Linear in `this->host_address().size()`.

Calls to allocate may throw.


host        = IP-literal / IPv4address / reg-name

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

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

3.2.2. Host (rfc3986)

Return the host

Synopsis

Declared in <include/boost/url/authority_view.hpp>


pct_string_view
encoded_host_address() const noexcept;

Description

The value returned by this function depends on the type of host returned from the function host_type .

If the type is host_type::ipv4 , then the IPv4 address string is returned.

If the type is host_type::ipv6 , then the IPv6 address string is returned, without any enclosing brackets.

If the type is host_type::ipvfuture , then the IPvFuture address string is returned, without any enclosing brackets.

If the type is host_type::name , then the host name string is returned. Any percent-escapes in the string are decoded first.

If the type is host_type::none , then an empty string is returned. The returned string may contain percent escapes.


assert( url_view( "https://www%2droot.example.com/" ).encoded_host_address() == "www%2droot.example.com" );

Constant.

Throws nothing.


host        = IP-literal / IPv4address / reg-name

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

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

3.2.2. Host (rfc3986)

Return the host IPv4 address

Synopsis

Declared in <include/boost/url/authority_view.hpp>


ipv4_address
host_ipv4_address() const noexcept;

Description

If the host type is host_type::ipv4 , this function returns the address as a value of type ipv4_address . Otherwise, if the host type is not an IPv4 address, it returns a default-constructed value which is equal to the unspecified address "0.0.0.0".


assert( url_view( "http://127.0.0.1/index.htm?user=win95" ).host_ipv4_address() == ipv4_address( "127.0.0.1" ) );

Constant.

Throws nothing.


IPv4address = dec-octet "." dec-octet "." dec-octet "." dec-octet

dec-octet   = DIGIT                 ; 0-9
            / %x31-39 DIGIT         ; 10-99
            / "1" 2DIGIT            ; 100-199
            / "2" %x30-34 DIGIT     ; 200-249
            / "25" %x30-35          ; 250-255

3.2.2. Host (rfc3986)

Return the host IPv6 address

Synopsis

Declared in <include/boost/url/authority_view.hpp>


ipv6_address
host_ipv6_address() const noexcept;

Description

If the host type is host_type::ipv6 , this function returns the address as a value of type ipv6_address . Otherwise, if the host type is not an IPv6 address, it returns a default-constructed value which is equal to the unspecified address "0:0:0:0:0:0:0:0".


assert( url_view( "ftp://[::1]/" ).host_ipv6_address() == ipv6_address( "::1" ) );

Constant.

Throws nothing.


IPv6address =                            6( h16 ":" ) ls32
            /                       "::" 5( h16 ":" ) ls32
            / [               h16 ] "::" 4( h16 ":" ) ls32
            / [ *1( h16 ":" ) h16 ] "::" 3( h16 ":" ) ls32
            / [ *2( h16 ":" ) h16 ] "::" 2( h16 ":" ) ls32
            / [ *3( h16 ":" ) h16 ] "::"    h16 ":"   ls32
            / [ *4( h16 ":" ) h16 ] "::"              ls32
            / [ *5( h16 ":" ) h16 ] "::"              h16
            / [ *6( h16 ":" ) h16 ] "::"

ls32        = ( h16 ":" h16 ) / IPv4address
            ; least-significant 32 bits of address

h16         = 1*4HEXDIG
            ; 16 bits of address represented in hexadecimal

3.2.2. Host (rfc3986)

Return the host IPvFuture address

Synopsis

Declared in <include/boost/url/authority_view.hpp>


core::string_view
host_ipvfuture() const noexcept;

Description

If the host type is host_type::ipvfuture , this function returns the address as a string. Otherwise, if the host type is not an IPvFuture address, it returns an empty string.


assert( url_view( "http://[v1fe.d:9]/index.htm" ).host_ipvfuture() == "v1fe.d:9" );

Constant.

Throws nothing.


IPvFuture  = "v" 1*HEXDIG "." 1*( unreserved / sub-delims / ":" )

3.2.2. Host (rfc3986)

Return the host name

Synopsis

Declared in <include/boost/url/authority_view.hpp>


template<class StringToken = string_token::return_string>
StringToken::result_type
host_name(StringToken&& token) const;

Description

If the host type is host_type::name , this function returns the name as a string. Otherwise, if the host type is not an name, it returns an empty string. Any percent-escapes in the string are decoded first.


assert( url_view( "https://www%2droot.example.com/" ).host_name() == "www-root.example.com" );

Linear in `this->host_name().size()`.

Calls to allocate may throw.


host        = IP-literal / IPv4address / reg-name

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

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

3.2.2. Host (rfc3986)

Return the host name

Synopsis

Declared in <include/boost/url/authority_view.hpp>


pct_string_view
encoded_host_name() const noexcept;

Description

If the host type is host_type::name , this function returns the name as a string. Otherwise, if the host type is not an name, it returns an empty string. The returned string may contain percent escapes.


assert( url_view( "https://www%2droot.example.com/" ).encoded_host_name() == "www%2droot.example.com" );

Constant.

Throws nothing.


host        = IP-literal / IPv4address / reg-name

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

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

3.2.2. Host (rfc3986)

Return true if a port is present

Synopsis

Declared in <include/boost/url/authority_view.hpp>


bool
has_port() const noexcept;

Description

This function returns true if an authority is present and contains a port.


assert( url_view( "wss://www.example.com:443" ).has_port() );

Constant.

Throws nothing.


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

port        = *DIGIT

3.2.3. Port (rfc3986)

Synopsis

Declared in <include/boost/url/authority_view.hpp>


core::string_view
port() const noexcept;

Description

If present, this function returns a string representing the port (which may be empty). Otherwise it returns an empty string.


assert( url_view( "http://localhost.com:8080" ).port() == "8080" );

Constant.

Throws nothing.


port        = *DIGIT

3.2.3. Port (rfc3986)

Synopsis

Declared in <include/boost/url/authority_view.hpp>


std::uint16_t
port_number() const noexcept;

Description

If a port is present and the numerical value is representable, it is returned as an unsigned integer. Otherwise, the number zero is returned.


assert( url_view( "http://localhost.com:8080" ).port_number() == 8080 );

Constant.

Throws nothing.


port        = *DIGIT

3.2.3. Port (rfc3986)

Synopsis

Declared in <include/boost/url/authority_view.hpp>


pct_string_view
encoded_host_and_port() const noexcept;

Description

If an authority is present, this function returns the host and optional port as a string, which may be empty. Otherwise it returns an empty string. The returned string may contain percent escapes.


assert( url_view( "http://www.example.com:8080/index.htm" ).encoded_host_and_port() == "www.example.com:8080" );

Constant.

Throws nothing.


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

3.2.2. Host (rfc3986)

3.2.3. Port (rfc3986)

Synopsis

Declared in <include/boost/url/authority_view.hpp>


int
compare(authority_view const& other) const noexcept;

Description

This function compares two authorities according to Syntax-Based comparison algorithm.

Throws nothing.

6.2.2 Syntax-Based Normalization (rfc3986)

Return Value

-1 if `*this < other`, 0 if `this == other`, and 1 if `this > other`.

Return the result of comparing two authorities The authorities are compared component by component as if they were first normalized.

Synopsis

Declared in <include/boost/url/authority_view.hpp>


friend
bool
operator==(
    authority_view const& a0,
    authority_view const& a1) noexcept;

Description

Linear in `min( a0.size(), a1.size() )`

Throws nothing

Return the result of comparing two authorities The authorities are compared component by component as if they were first normalized.

Synopsis

Declared in <include/boost/url/authority_view.hpp>


friend
bool
operator!=(
    authority_view const& a0,
    authority_view const& a1) noexcept;

Description

Linear in `min( a0.size(), a1.size() )`

Throws nothing

Return the result of comparing two authorities The authorities are compared component by component as if they were first normalized.

Synopsis

Declared in <include/boost/url/authority_view.hpp>


friend
bool
operator<(
    authority_view const& a0,
    authority_view const& a1) noexcept;

Description

Linear in `min( a0.size(), a1.size() )`

Throws nothing

Return the result of comparing two authorities The authorities are compared component by component as if they were first normalized.

Synopsis

Declared in <include/boost/url/authority_view.hpp>


friend
bool
operator<=(
    authority_view const& a0,
    authority_view const& a1) noexcept;

Description

Linear in `min( a0.size(), a1.size() )`

Throws nothing

Return the result of comparing two authorities The authorities are compared component by component as if they were first normalized.

Synopsis

Declared in <include/boost/url/authority_view.hpp>


friend
bool
operator>(
    authority_view const& a0,
    authority_view const& a1) noexcept;

Description

Linear in `min( a0.size(), a1.size() )`

Throws nothing

Return the result of comparing two authorities The authorities are compared component by component as if they were first normalized.

Synopsis

Declared in <include/boost/url/authority_view.hpp>


friend
bool
operator>=(
    authority_view const& a0,
    authority_view const& a1) noexcept;

Description

Linear in `min( a0.size(), a1.size() )`

Throws nothing

Format the encoded authority to the output stream

Synopsis

Declared in <include/boost/url/authority_view.hpp>


friend
std::ostream&
operator<<(
    std::ostream& os,
    authority_view const& a);

Description

This hidden friend function serializes the encoded URL to the output stream.


authority_view a( "www.example.com" );

std::cout << a << std::endl;

Return Value

A reference to the output stream, for chaining

Parameters

Name	Description
os	The output stream to write to
a	The URL to write

Return the result of comparing two authorities The authorities are compared component by component as if they were first normalized.

Synopsis

Declared in <include/boost/url/authority_view.hpp>


bool
operator<(
    authority_view const& a0,
    authority_view const& a1) noexcept;

» more...


template<
    class S0,
    class S1>
constexpr
bool
operator<(
    S0 const& s0,
    S1 const& s1) noexcept;

» more...


bool
operator<(
    url_view_base const& u0,
    url_view_base const& u1) noexcept;

» more...

Description

Linear in `min( a0.size(), a1.size() )`

Throws nothing

Return the result of comparing two authorities The authorities are compared component by component as if they were first normalized.

Synopsis

Declared in <include/boost/url/authority_view.hpp>


bool
operator<(
    authority_view const& a0,
    authority_view const& a1) noexcept;

Description

Linear in `min( a0.size(), a1.size() )`

Throws nothing

Compare two decode views for less than

Synopsis

Declared in <include/boost/url/decode_view.hpp>


template<
    class S0,
    class S1>
constexpr
bool
operator<(
    S0 const& s0,
    S1 const& s1) noexcept;

Description

This function is only enabled if both types are decode_view or convertible to `core::string_view`, but not both are convertible to `core::string_view`

Return the result of comparing two URLs

Synopsis

Declared in <include/boost/url/url_view_base.hpp>


bool
operator<(
    url_view_base const& u0,
    url_view_base const& u1) noexcept;

Description

The URLs are compared component by component as if they were first normalized.


url_view u0( "http://www.a.com/index.htm" );
url_view u1( "http://www.b.com/index.htm" );
assert( u0 < u1 );


url a(u0);
a.normalize();
url b(u1);
b.normalize();
return a.buffer() < b.buffer();

Linear in `min( u0.size(), u1.size() )`

Throws nothing

6.2.2 Syntax-Based Normalization (rfc3986)

Return Value

`true` if `u0 < u1`

Return the result of comparing two authorities The authorities are compared component by component as if they were first normalized.

Synopsis

Declared in <include/boost/url/authority_view.hpp>


bool
operator<=(
    authority_view const& a0,
    authority_view const& a1) noexcept;

» more...


template<
    class S0,
    class S1>
constexpr
bool
operator<=(
    S0 const& s0,
    S1 const& s1) noexcept;

» more...


bool
operator<=(
    url_view_base const& u0,
    url_view_base const& u1) noexcept;

» more...

Description

Linear in `min( a0.size(), a1.size() )`

Throws nothing

Return the result of comparing two authorities The authorities are compared component by component as if they were first normalized.

Synopsis

Declared in <include/boost/url/authority_view.hpp>


bool
operator<=(
    authority_view const& a0,
    authority_view const& a1) noexcept;

Description

Linear in `min( a0.size(), a1.size() )`

Throws nothing

Compare two decode views for less than or equal

Synopsis

Declared in <include/boost/url/decode_view.hpp>


template<
    class S0,
    class S1>
constexpr
bool
operator<=(
    S0 const& s0,
    S1 const& s1) noexcept;

Description

This function is only enabled if both types are decode_view or convertible to `core::string_view`, but not both are convertible to `core::string_view`

Return the result of comparing two URLs

Synopsis

Declared in <include/boost/url/url_view_base.hpp>


bool
operator<=(
    url_view_base const& u0,
    url_view_base const& u1) noexcept;

Description

The URLs are compared component by component as if they were first normalized.


url_view u0( "http://www.b.com/index.htm" );
url_view u1( "http://www.b.com/index.htm" );
assert( u0 <= u1 );


url a(u0);
a.normalize();
url b(u1);
b.normalize();
return a.buffer() <= b.buffer();

Linear in `min( u0.size(), u1.size() )`

Throws nothing

6.2.2 Syntax-Based Normalization (rfc3986)

Return Value

`true` if `u0 <= u1`

Return the result of comparing two authorities The authorities are compared component by component as if they were first normalized.

Synopsis

Declared in <include/boost/url/authority_view.hpp>


bool
operator>(
    authority_view const& a0,
    authority_view const& a1) noexcept;

» more...


template<
    class S0,
    class S1>
constexpr
bool
operator>(
    S0 const& s0,
    S1 const& s1) noexcept;

» more...


bool
operator>(
    url_view_base const& u0,
    url_view_base const& u1) noexcept;

» more...

Description

Linear in `min( a0.size(), a1.size() )`

Throws nothing

Return the result of comparing two authorities The authorities are compared component by component as if they were first normalized.

Synopsis

Declared in <include/boost/url/authority_view.hpp>


bool
operator>(
    authority_view const& a0,
    authority_view const& a1) noexcept;

Description

Linear in `min( a0.size(), a1.size() )`

Throws nothing

Compare two decode views for greater than

Synopsis

Declared in <include/boost/url/decode_view.hpp>


template<
    class S0,
    class S1>
constexpr
bool
operator>(
    S0 const& s0,
    S1 const& s1) noexcept;

Description

This function is only enabled if both types are decode_view or convertible to `core::string_view`, but not both are convertible to `core::string_view`

Return the result of comparing two URLs

Synopsis

Declared in <include/boost/url/url_view_base.hpp>


bool
operator>(
    url_view_base const& u0,
    url_view_base const& u1) noexcept;

Description

The URLs are compared component by component as if they were first normalized.


url_view u0( "http://www.b.com/index.htm" );
url_view u1( "http://www.a.com/index.htm" );
assert( u0 > u1 );


url a(u0);
a.normalize();
url b(u1);
b.normalize();
return a.buffer() > b.buffer();

Linear in `min( u0.size(), u1.size() )`

Throws nothing

6.2.2 Syntax-Based Normalization (rfc3986)

Return Value

`true` if `u0 > u1`

Return the result of comparing two authorities The authorities are compared component by component as if they were first normalized.

Synopsis

Declared in <include/boost/url/authority_view.hpp>


bool
operator>=(
    authority_view const& a0,
    authority_view const& a1) noexcept;

» more...


template<
    class S0,
    class S1>
constexpr
bool
operator>=(
    S0 const& s0,
    S1 const& s1) noexcept;

» more...


bool
operator>=(
    url_view_base const& u0,
    url_view_base const& u1) noexcept;

» more...

Description

Linear in `min( a0.size(), a1.size() )`

Throws nothing

Return the result of comparing two authorities The authorities are compared component by component as if they were first normalized.

Synopsis

Declared in <include/boost/url/authority_view.hpp>


bool
operator>=(
    authority_view const& a0,
    authority_view const& a1) noexcept;

Description

Linear in `min( a0.size(), a1.size() )`

Throws nothing

Compare two decode views for greater than or equal

Synopsis

Declared in <include/boost/url/decode_view.hpp>


template<
    class S0,
    class S1>
constexpr
bool
operator>=(
    S0 const& s0,
    S1 const& s1) noexcept;

Description

This function is only enabled if both types are decode_view or convertible to `core::string_view`, but not both are convertible to `core::string_view`

Return the result of comparing two URLs

Synopsis

Declared in <include/boost/url/url_view_base.hpp>


bool
operator>=(
    url_view_base const& u0,
    url_view_base const& u1) noexcept;

Description

The URLs are compared component by component as if they were first normalized.


url_view u0( "http://www.a.com/index.htm" );
url_view u1( "http://www.a.com/index.htm" );
assert( u0 >= u1 );


url a(u0);
a.normalize();
url b(u1);
b.normalize();
return a.buffer() >= b.buffer();

Linear in `min( u0.size(), u1.size() )`

Throws nothing

6.2.2 Syntax-Based Normalization (rfc3986)

Return Value

`true` if `u0 >= u1`

Parse an authority

Synopsis

Declared in <include/boost/url/authority_view.hpp>


system::result<authority_view>
parse_authority(core::string_view s) noexcept;

Description

This function parses a string according to the authority grammar below, and returns an authority_view referencing the string. Ownership of the string is not transferred; the caller is responsible for ensuring that the lifetime of the string extends until the view is no longer being accessed.


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

userinfo      = user [ ":" [ password ] ]

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

host          = IP-literal / IPv4address / reg-name

port          = *DIGIT

Throws nothing.

3.2. Authority (rfc3986)

Return Value

A view to the parsed authority

Parameters

Name	Description
s	The string to parse

Synopsis

Declared in <include/boost/url/encode.hpp>


template<class CharSet>
std::size_t
encoded_size(
    core::string_view s,
    CharSet const& unreserved,
    encoding_opts opt = = {}) noexcept;

Description

This function returns the exact number of bytes necessary to store the result of applying percent-encoding to the string using the given options and character set. No encoding is actually performed.


assert( encoded_size( "My Stuff", pchars ) == 10 );

Throws nothing.

2.1. Percent-Encoding (rfc3986)

Return Value

The number of bytes needed, excluding any null terminator.

Parameters

Name	Description
s	The string to measure.
unreserved	The set of characters that is not percent-encoded.
opt	The options for encoding. If this parameter is omitted, the default options are be used.

Synopsis

Declared in <include/boost/url/encode.hpp>


template<class CharSet>
std::size_t
encode(
    char* dest,
    std::size_t size,
    core::string_view s,
    CharSet const& unreserved,
    encoding_opts opt = = {});

» more...


template<
    class StringToken = string_token::return_string,
    class CharSet>
StringToken::result_type
encode(
    core::string_view s,
    CharSet const& unreserved,
    encoding_opts opt = = {},
    StringToken&& token) noexcept;

» more...

Description

This function applies percent-encoding to the string using the given options and character set. The destination buffer provided by the caller is used to store the result, which may be truncated if there is insufficient space.


char buf[100];
assert( encode( buf, sizeof(buf), "Program Files", pchars ) == 15 );

Throws nothing.

2.1. Percent-Encoding (rfc3986)

Return Value

The number of characters written to the destination buffer.

Parameters

Name	Description
dest	The destination buffer to write to.
size	The number of writable characters pointed to by `dest`. If this is less than `encoded_size(s)`, the result is truncated.
s	The string to encode.
unreserved	The set of characters that is not percent-encoded.
opt	The options for encoding. If this parameter is omitted, the default options are used.
token	A string token.

Synopsis

Declared in <include/boost/url/encode.hpp>


template<class CharSet>
std::size_t
encode(
    char* dest,
    std::size_t size,
    core::string_view s,
    CharSet const& unreserved,
    encoding_opts opt = = {});

Description


char buf[100];
assert( encode( buf, sizeof(buf), "Program Files", pchars ) == 15 );

Throws nothing.

2.1. Percent-Encoding (rfc3986)

Return Value

The number of characters written to the destination buffer.

Parameters

Name	Description
dest	The destination buffer to write to.
size	The number of writable characters pointed to by `dest`. If this is less than `encoded_size(s)`, the result is truncated.
s	The string to encode.
unreserved	The set of characters that is not percent-encoded.
opt	The options for encoding. If this parameter is omitted, the default options are used.

Synopsis

Declared in <include/boost/url/encode.hpp>


template<
    class StringToken = string_token::return_string,
    class CharSet>
StringToken::result_type
encode(
    core::string_view s,
    CharSet const& unreserved,
    encoding_opts opt = = {},
    StringToken&& token) noexcept;

Description

This function applies percent-encoding to the string using the given options and character set, and returns the result as a string when called with default arguments.


encoding_opts opt;
opt.space_as_plus = true;
std::string s = encode( "My Stuff", opt, pchars );

assert( s == "My+Stuff" );

Calls to allocate may throw.

2.1. Percent-Encoding (rfc3986)

Return Value

The string

Parameters

Name	Description
s	The string to encode.
unreserved	The set of characters that is not percent-encoded.
opt	The options for encoding. If this parameter is omitted, the default options are used.
token	A string token.

Synopsis

Declared in <include/boost/url/ignore_case.hpp>


constexpr
ignore_case_t const ignore_case = {};

Description

This value may be optionally passed to functions accepting a parameter of type ignore_case_param to indicate that comparisons should be case-insensitive.

An optional parameter to determine case-sensitivity

Synopsis

Declared in <include/boost/url/ignore_case.hpp>


class ignore_case_param;

Member Functions

Name	Description
`ignore_case_param` [constructor]	Constructor
`operator bool`	True if an algorithm should ignore case

Description

Functions may use parameters of this type to allow the user to optionally indicate that comparisons should be case-insensitive when the value ignore_case is passed.

Constructor

Synopsis

Declared in <include/boost/url/ignore_case.hpp>


constexpr
ignore_case_param() noexcept = default;

» more...


constexpr
ignore_case_param(ignore_case_t) noexcept;

» more...

Description

By default, comparisons are case-sensitive.

This function performs case-sensitive

comparisons when called with no arguments:


void f( ignore_case_param = {} );

Constructor

Synopsis

Declared in <include/boost/url/ignore_case.hpp>


constexpr
ignore_case_param() noexcept = default;

Description

By default, comparisons are case-sensitive.

This function performs case-sensitive

comparisons when called with no arguments:


void f( ignore_case_param = {} );

Constructor

Synopsis

Declared in <include/boost/url/ignore_case.hpp>


constexpr
ignore_case_param(ignore_case_t) noexcept;

Description

Construction from ignore_case indicates that comparisons should be case-insensitive.

When

ignore_case is passed as an argument, this function ignores case when performing comparisons:


void f( ignore_case_param = {} );

True if an algorithm should ignore case

Synopsis

Declared in <include/boost/url/ignore_case.hpp>


operator bool() const noexcept;

Description

Values of type `ignore_case_param` evaluate to true when constructed with the constant ignore_case . Otherwise, they are default-constructed and evaluate to `false`.

The type of no_value

Synopsis

Declared in <include/boost/url/param.hpp>


struct no_value_t;

A query parameter

Synopsis

Declared in <include/boost/url/param.hpp>


struct param_pct_view;

Member Functions

Name	Description
`operator param`	Conversion
`operator param_view`	Conversion to param_view
`operator->`	Arrow support
`param_pct_view` [constructor]	Construction Constructor aggregate construction

Data Members

Name	Description
`has_value`	True if a value is present
`key`	The key
`value`	The value

Description

Objects of this type represent a single key and value pair in a query string where a key is always present and may be empty, while the presence of a value is indicated by has_value equal to true. An empty value is distinct from no value.

The strings may have percent escapes, and offer an additional invariant: they never contain an invalid percent-encoding.

For most usages, key comparisons are case-sensitive and duplicate keys in a query are possible. However, it is the authority that has final control over how the query is interpreted.

Keys and values in this object reference external character buffers. Ownership of the buffers is not transferred; the caller is responsible for ensuring that the assigned buffers remain valid until they are no longer referenced.


query-params    = query-param *( "&" query-param )
query-param     = key [ "=" value ]
key             = *qpchar
value           = *( qpchar / "=" )

Query string (Wikipedia)

Synopsis

Declared in <include/boost/url/param.hpp>


pct_string_view key;

Description

For most usages, key comparisons are case-sensitive and duplicate keys in a query are possible. However, it is the authority that has final control over how the query is interpreted.

The value

Synopsis

Declared in <include/boost/url/param.hpp>


pct_string_view value;

Description

The presence of a value is indicated by has_value equal to true. An empty value is distinct from no value.

True if a value is present

Synopsis

Declared in <include/boost/url/param.hpp>


bool has_value = false;

Description

The presence of a value is indicated by `has_value == true`. An empty value is distinct from no value.

Constructor

Synopsis

Declared in <include/boost/url/param.hpp>


constexpr
param_pct_view() = default;

» more...


param_pct_view(
    pct_string_view key,
    pct_string_view value) noexcept;

» more...


template<class OptionalString>
param_pct_view(
    pct_string_view key,
    OptionalString const& value);

» more...


explicit
param_pct_view(param_view const& p);

» more...


param_pct_view(
    pct_string_view key,
    pct_string_view value,
    bool has_value) noexcept;

» more...

Description

Default constructed query parameters have an empty key and no value.


param_pct_view qp;


this->key == "" && this->value == "" && this->has_value == false

Constant.

Throws nothing.

Exceptions

Name	Thrown on
`[object Object]`	or `value` contains an invalid percent-encoding.

Template Parameters

Name	Description
OptionalString	An optional `core::string_view` type, such as `boost::optional` or `std::optional`.

Parameters

Name	Description
key,	value The key and value to set.
p	The param to construct from.

Constructor

Synopsis

Declared in <include/boost/url/param.hpp>


constexpr
param_pct_view() = default;

Description

Default constructed query parameters have an empty key and no value.


param_pct_view qp;


this->key == "" && this->value == "" && this->has_value == false

Constant.

Throws nothing.

Constructor

Synopsis

Declared in <include/boost/url/param.hpp>


param_pct_view(
    pct_string_view key,
    pct_string_view value) noexcept;

Description

This constructs a parameter with a key and value, which may both contain percent escapes. The new key and value reference the same corresponding underlying character buffers. Ownership of the buffers is not transferred; the caller is responsible for ensuring that the assigned buffers remain valid until they are no longer referenced.


param_pct_view qp( "key", "value" );


this->key.data() == key.data() && this->value.data() == value.data() && this->has_value == true

Linear in `key.size() + value.size()`.

Exceptions thrown on invalid input.

Exceptions

Name	Thrown on
`key`	or `value` contains an invalid percent-encoding.

Parameters

Name	Description
key,	value The key and value to set.

Constructor

Synopsis

Declared in <include/boost/url/param.hpp>


template<class OptionalString>
param_pct_view(
    pct_string_view key,
    OptionalString const& value);

Description

This constructs a parameter with a key and optional value, which may both contain percent escapes.

The new key and value reference the same corresponding underlying character buffers.

Ownership of the buffers is not transferred; the caller is responsible for ensuring that the assigned buffers remain valid until they are no longer referenced.


param_pct_view qp( "key", optional("value") );


this->key.data() == key.data() && this->value->data() == value->data() && this->has_value == true

Linear in `key.size() + value->size()`.

Exceptions thrown on invalid input.

Exceptions

Name	Thrown on
`key`	or `value` contains an invalid percent-encoding.

Template Parameters

Name	Description
OptionalString	An optional `core::string_view` type, such as `boost::optional` or `std::optional`.

Parameters

Name	Description
key,	value The key and value to set.

Construction

Synopsis

Declared in <include/boost/url/param.hpp>


explicit
param_pct_view(param_view const& p);

Description

This converts a param which may contain unvalidated percent-escapes into a param whose key and value are guaranteed to contain strings with no invalid percent-escapes, otherwise an exception is thrown.

The new key and value reference the same corresponding underlying character buffers. Ownership of the buffers is not transferred; the caller is responsible for ensuring that the assigned buffers remain valid until they are no longer referenced.


param_pct_view qp( param_view( "key", "value" ) );

Linear in `key.size() + value.size()`.

Exceptions thrown on invalid input.

Exceptions

Name	Thrown on
`key`	or `value` contains an invalid percent escape.

Parameters

Name	Description
p	The param to construct from.

aggregate construction

Synopsis

Declared in <include/boost/url/param.hpp>


param_pct_view(
    pct_string_view key,
    pct_string_view value,
    bool has_value) noexcept;

Conversion

Synopsis

Declared in <include/boost/url/param.hpp>


explicit
operator param() const;

Description

This function performs a conversion from a reference-like query parameter to one retaining ownership of the strings by making a copy.

Linear in `this->key.size() + this->value.size()`.

Calls to allocate may throw.

Conversion to param_view

Synopsis

Declared in <include/boost/url/param.hpp>


operator param_view() const noexcept;

Description

This function performs a conversion from a pct_string_view query parameter to one using a simple string_view.

Calls to allocate may throw.

Arrow support

Synopsis

Declared in <include/boost/url/param.hpp>


param_pct_view const*
operator->() const noexcept;

A query parameter

Synopsis

Declared in <include/boost/url/param.hpp>


struct param_view;

Member Functions

Name	Description
`operator param`	Conversion
`operator->`
`param_view` [constructor]	Constructor

Data Members

Name	Description
`has_value`	True if a value is present
`key`	The key
`value`	The value

Description

Depending on where the object was obtained, the strings may or may not contain percent escapes.

For most usages, key comparisons are case-sensitive and duplicate keys in a query are possible. However, it is the authority that has final control over how the query is interpreted.


query-params    = query-param *( "&" query-param )
query-param     = key [ "=" value ]
key             = *qpchar
value           = *( qpchar / "=" )

Query string (Wikipedia)

Synopsis

Declared in <include/boost/url/param.hpp>


core::string_view key;

Description

For most usages, key comparisons are case-sensitive and duplicate keys in a query are possible. However, it is the authority that has final control over how the query is interpreted.

The value

Synopsis

Declared in <include/boost/url/param.hpp>


core::string_view value;

Description

The presence of a value is indicated by has_value equal to true. An empty value is distinct from no value.

True if a value is present

Synopsis

Declared in <include/boost/url/param.hpp>


bool has_value = false;

Description

The presence of a value is indicated by `has_value == true`. An empty value is distinct from no value.

Constructor

Synopsis

Declared in <include/boost/url/param.hpp>


constexpr
param_view() = default;

» more...


template<class OptionalString>
param_view(
    core::string_view key,
    OptionalString const& value) noexcept;

» more...


param_view(param const& other) noexcept;

» more...


param_view(
    core::string_view key_,
    core::string_view value_,
    bool has_value_) noexcept;

» more...

Description

Default constructed query parameters have an empty key and no value.


param_view qp;


this->key == "" && this->value == "" && this->has_value == false

Constant.

Throws nothing.

Template Parameters

Name	Description
OptionalString	An optional string type, such as `core::string_view`, `std::nullptr`, no_value_t , or `optional`.

Parameters

Name	Description
key,	value The key and value to set.
other	The param to reference

Constructor

Synopsis

Declared in <include/boost/url/param.hpp>


constexpr
param_view() = default;

Description

Default constructed query parameters have an empty key and no value.


param_view qp;


this->key == "" && this->value == "" && this->has_value == false

Constant.

Throws nothing.

Constructor

Synopsis

Declared in <include/boost/url/param.hpp>


template<class OptionalString>
param_view(
    core::string_view key,
    OptionalString const& value) noexcept;

Description

This constructs a parameter with a key and value. No validation is performed on the strings. The new key and value reference the same corresponding underlying character buffers. Ownership of the buffers is not transferred; the caller is responsible for ensuring that the assigned buffers remain valid until they are no longer referenced.


param_view qp( "key", "value" );


this->key.data() == key.data() && this->value.data() == value.data() && this->has_value == true

Constant.

Throws nothing.

Template Parameters

Name	Description
OptionalString	An optional string type, such as `core::string_view`, `std::nullptr`, no_value_t , or `optional`.

Parameters

Name	Description
key,	value The key and value to set.

Constructor

Synopsis

Declared in <include/boost/url/param.hpp>


param_view(param const& other) noexcept;

Description

This function constructs a param which references the character buffers representing the key and value in another container. Ownership of the buffers is not transferred; the caller is responsible for ensuring that the assigned buffers remain valid until they are no longer referenced.


param qp( "key", "value" );
param_view qpv( qp );


this->key == key && this->value == value && this->has_value == other.has_value

Constant.

Throws nothing.

Parameters

Name	Description
other	The param to reference

Synopsis

Declared in <include/boost/url/param.hpp>


param_view(
    core::string_view key_,
    core::string_view value_,
    bool has_value_) noexcept;

Conversion

Synopsis

Declared in <include/boost/url/param.hpp>


explicit
operator param();

Description

This function performs a conversion from a reference-like query parameter to one retaining ownership of the strings by making a copy. No validation is performed on the strings.

Linear in `this->key.size() + this->value.size()`.

Calls to allocate may throw.

Synopsis

Declared in <include/boost/url/param.hpp>


param_view const*
operator->() const noexcept;

Constant indicating no value in a param

Synopsis

Declared in <include/boost/url/param.hpp>


constexpr
no_value_t const no_value = {};

A query parameter

Synopsis

Declared in <include/boost/url/param.hpp>


struct param;

Member Functions

Name	Description
`operator->`
`operator=`	Assignment
`param` [constructor]	Constructor

Data Members

Name	Description
`has_value`	True if a value is present
`key`	The key
`value`	The value

Description

Depending on where the object was obtained, the strings may or may not contain percent escapes.

For most usages, key comparisons are case-sensitive and duplicate keys in a query are possible. However, it is the authority that has final control over how the query is interpreted.


query-params    = query-param *( "&" query-param )
query-param     = key [ "=" value ]
key             = *qpchar
value           = *( qpchar / "=" )

Query string (Wikipedia)

Synopsis

Declared in <include/boost/url/param.hpp>


std::string key;

Description

For most usages, key comparisons are case-sensitive and duplicate keys in a query are possible. However, it is the authority that has final control over how the query is interpreted.

The value

Synopsis

Declared in <include/boost/url/param.hpp>


std::string value;

Description

The presence of a value is indicated by has_value equal to true. An empty value is distinct from no value.

True if a value is present

Synopsis

Declared in <include/boost/url/param.hpp>


bool has_value = false;

Description

The presence of a value is indicated by `has_value == true`. An empty value is distinct from no value.

Constructor

Synopsis

Declared in <include/boost/url/param.hpp>


constexpr
param() = default;

» more...


param(param&& other) noexcept;

» more...


constexpr
param(param const& other) = default;

» more...


template<class OptionalString>
param(
    core::string_view key,
    OptionalString const& value);

» more...


param(
    core::string_view key,
    core::string_view value,
    bool has_value) noexcept;

» more...

Description

Default constructed query parameters have an empty key and no value.


param qp;


this->key == "" && this->value == "" && this->has_value == false

Constant.

Throws nothing.

Template Parameters

Name	Description
OptionalString	An optional string type, such as `core::string_view`, `std::nullptr`, no_value_t , or `optional`.

Parameters

Name	Description
key,	value The key and value to set.

Constructor

Synopsis

Declared in <include/boost/url/param.hpp>


constexpr
param() = default;

Description

Default constructed query parameters have an empty key and no value.


param qp;


this->key == "" && this->value == "" && this->has_value == false

Constant.

Throws nothing.

Constructor

Synopsis

Declared in <include/boost/url/param.hpp>


param(param&& other) noexcept;

Description

Upon construction, this acquires ownership of the members of other via move construction. The moved from object is as if default constructed.

Constant.

Throws nothing.

Constructor

Synopsis

Declared in <include/boost/url/param.hpp>


constexpr
param(param const& other) = default;

Description

Upon construction, this becomes a copy of `other`.


this->key == other.key && this->value == other.value && this->has_value == other.has_value

Linear in `other.key.size() + other.value.size()`.

Calls to allocate may throw.

Constructor

Synopsis

Declared in <include/boost/url/param.hpp>


template<class OptionalString>
param(
    core::string_view key,
    OptionalString const& value);

Description

This constructs a parameter with a key and value.

No validation is performed on the strings. Ownership of the key and value is acquired by making copies.


param qp( "key", "value" );


param qp( "key", optional("value") );


param qp( "key", boost::none );


param qp( "key", nullptr );


param qp( "key", no_value );


this->key == key && this->value == value && this->has_value == true

Linear in `key.size() + value.size()`.

Calls to allocate may throw.

Template Parameters

Name	Description
OptionalString	An optional string type, such as `core::string_view`, `std::nullptr`, no_value_t , or `optional`.

Parameters

Name	Description
key,	value The key and value to set.

Synopsis

Declared in <include/boost/url/param.hpp>


param(
    core::string_view key,
    core::string_view value,
    bool has_value) noexcept;

Assignment

Synopsis

Declared in <include/boost/url/param.hpp>


param&
operator=(param&& other) noexcept;

» more...


constexpr
param&
operator=(param const&) = default;

» more...


param&
operator=(param_view const& other);

» more...


param&
operator=(param_pct_view const& other);

» more...

Description

Upon assignment, this acquires ownership of the members of other via move assignment. The moved from object is as if default constructed.

Constant.

Throws nothing.

Parameters

Name	Description
other	The parameter to copy.

Assignment

Synopsis

Declared in <include/boost/url/param.hpp>


param&
operator=(param&& other) noexcept;

Description

Upon assignment, this acquires ownership of the members of other via move assignment. The moved from object is as if default constructed.

Constant.

Throws nothing.

Assignment

Synopsis

Declared in <include/boost/url/param.hpp>


constexpr
param&
operator=(param const&) = default;

Description

Upon assignment, this becomes a copy of `other`.


this->key == other.key && this->value == other.value && this->has_value == other.has_value

Linear in `other.key.size() + other.value.size()`.

Calls to allocate may throw.

Assignment

Synopsis

Declared in <include/boost/url/param.hpp>


param&
operator=(param_view const& other);

Description

The members of `other` are copied, re-using already existing string capacity.


this->key == other.key && this->value == other.value && this->has_value == other.has_value

Linear in `other.key.size() + other.value.size()`.

Calls to allocate may throw.

Parameters

Name	Description
other	The parameter to copy.

Assignment

Synopsis

Declared in <include/boost/url/param.hpp>


param&
operator=(param_pct_view const& other);

Description

The members of `other` are copied, re-using already existing string capacity.


this->key == other.key && this->value == other.value && this->has_value == other.has_value

Linear in `other.key.size() + other.value.size()`.

Calls to allocate may throw.

Parameters

Name	Description
other	The parameter to copy.

Synopsis

Declared in <include/boost/url/param.hpp>


param const*
operator->() const noexcept;

Common functionality for containers

Synopsis

Declared in <include/boost/url/params_encoded_base.hpp>


class params_encoded_base;

Types

Name	Description
`const_iterator`	A Bidirectional iterator to a query parameter
`const_reference`	The reference type
`difference_type`	A signed integer type used to represent differences.
`iterator`	A Bidirectional iterator to a query parameter
`reference`	The reference type
`size_type`	An unsigned integer type to represent sizes.
`value_type`	The value type

Member Functions

Name	Description
`begin`	Return an iterator to the beginning
`buffer`	Return the query corresponding to these params
`contains`	Return true if a matching key exists
`count`	Return the number of matching keys
`empty`	Return true if there are no params
`end`	Return an iterator to the end
`find`	Find a matching key
`find_last`	Find a matching key
`size`	Return the number of params

Static Member Functions

Name	Description
`max_size`	Return the maximum number of characters possible

Description

This base class is used by the library to provide common member functions for containers. This cannot be instantiated directly; Instead, use one of the containers or functions:

A Bidirectional iterator to a query parameter

Synopsis

Declared in <include/boost/url/impl/params_encoded_base.hpp>


class iterator;

Types

Name	Description
`difference_type`
`iterator_category`
`pointer`
`reference`
`value_type`

Member Functions

Name	Description
`iterator` [constructor]
`operator*`
`operator++`
`operator--`
`operator->`
`operator=`

Friends

Name	Description
`operator!=`
`operator==`

Description

Objects of this type allow iteration through the parameters in the query. Strings returned by iterators may contain percent escapes. The values returned are read-only; changes to parameters must be made through the container instead, if the container supports modification.

The strings produced when iterators are dereferenced refer to the underlying character buffer. Ownership is not transferred; the caller is responsible for ensuring that the lifetime of the buffer extends until it is no longer referenced by any container or iterator.

Synopsis

Declared in <include/boost/url/impl/params_encoded_base.hpp>


using value_type = params_encoded_base::value_type;

Synopsis

Declared in <include/boost/url/impl/params_encoded_base.hpp>


using reference = params_encoded_base::reference;

Synopsis

Declared in <include/boost/url/impl/params_encoded_base.hpp>


using pointer = reference;

Synopsis

Declared in <include/boost/url/impl/params_encoded_base.hpp>


using difference_type = std::ptrdiff_t;

Synopsis

Declared in <include/boost/url/impl/params_encoded_base.hpp>


using iterator_category = std::bidirectional_iterator_tag;

Synopsis

Declared in <include/boost/url/impl/params_encoded_base.hpp>


constexpr
iterator() = default;

» more...


constexpr
iterator(iterator const&) = default;

» more...

Synopsis

Declared in <include/boost/url/impl/params_encoded_base.hpp>


constexpr
iterator() = default;

Synopsis

Declared in <include/boost/url/impl/params_encoded_base.hpp>


constexpr
iterator(iterator const&) = default;

Synopsis

Declared in <include/boost/url/impl/params_encoded_base.hpp>


constexpr
iterator&
operator=(iterator const&) = default;

Synopsis

Declared in <include/boost/url/impl/params_encoded_base.hpp>


iterator&
operator++() noexcept;

» more...


iterator
operator++(int) noexcept;

» more...

Synopsis

Declared in <include/boost/url/impl/params_encoded_base.hpp>


iterator&
operator++() noexcept;

Synopsis

Declared in <include/boost/url/impl/params_encoded_base.hpp>


iterator
operator++(int) noexcept;

Synopsis

Declared in <include/boost/url/impl/params_encoded_base.hpp>


iterator&
operator--() noexcept;

» more...


iterator
operator--(int) noexcept;

» more...

Synopsis

Declared in <include/boost/url/impl/params_encoded_base.hpp>


iterator&
operator--() noexcept;

Synopsis

Declared in <include/boost/url/impl/params_encoded_base.hpp>


iterator
operator--(int) noexcept;

Synopsis

Declared in <include/boost/url/impl/params_encoded_base.hpp>


reference
operator*() const;

Synopsis

Declared in <include/boost/url/impl/params_encoded_base.hpp>


pointer
operator->() const;

Synopsis

Declared in <include/boost/url/impl/params_encoded_base.hpp>


friend
bool
operator==(
    iterator const& it0,
    iterator const& it1) noexcept;

Synopsis

Declared in <include/boost/url/impl/params_encoded_base.hpp>


friend
bool
operator!=(
    iterator const& it0,
    iterator const& it1) noexcept;

A Bidirectional iterator to a query parameter

Synopsis

Declared in <include/boost/url/params_encoded_base.hpp>


using const_iterator = iterator;

Description

The value type

Synopsis

Declared in <include/boost/url/params_encoded_base.hpp>


using value_type = param;

Description

Values of this type represent parameters whose strings retain unique ownership by making a copy.


params_encoded_view::value_type qp( *url_view( "?first=John&last=Doe" ).params().find( "first" ) );

Synopsis

Declared in <include/boost/url/params_encoded_base.hpp>


using reference = param_pct_view;

Description

This is the type of value returned when iterators of the view are dereferenced.

Synopsis

Declared in <include/boost/url/params_encoded_base.hpp>


using const_reference = param_pct_view;


constexpr
static
std::size_t
max_size() noexcept;

Description

This represents the largest number of characters that are possible in a path, not including any null terminator.

Throws nothing.

Return the query corresponding to these params

Synopsis

Declared in <include/boost/url/params_encoded_base.hpp>


pct_string_view
buffer() const noexcept;

Description

This function returns the query string referenced by the container. The returned string may contain percent escapes.


assert( url_view( "?first=John&last=Doe" ).encoded_params().buffer() == "first=John&last=Doe" );

Constant.

Throws nothing.


query-params    = query-param *( "&" query-param )
query-param     = key [ "=" value ]
key             = *qpchar
value           = *( qpchar / "=" )

Query string (Wikipedia)

Return true if there are no params

Synopsis

Declared in <include/boost/url/params_encoded_base.hpp>


bool
empty() const noexcept;

Description


assert( ! url_view( "?key=value" ).encoded_params().empty() );

Constant.

Throws nothing.

Return the number of params

Synopsis

Declared in <include/boost/url/params_encoded_base.hpp>


std::size_t
size() const noexcept;

Description


assert( url_view( "?key=value").encoded_params().size() == 1 );

Constant.

Throws nothing.

Return an iterator to the beginning

Synopsis

Declared in <include/boost/url/params_encoded_base.hpp>


iterator
begin() const noexcept;

Description

Linear in the size of the first param.

Throws nothing.

Return an iterator to the end

Synopsis

Declared in <include/boost/url/params_encoded_base.hpp>


iterator
end() const noexcept;

Description

Constant.

Throws nothing.

Return true if a matching key exists

Synopsis

Declared in <include/boost/url/params_encoded_base.hpp>


bool
contains(
    pct_string_view key,
    ignore_case_param ic = = {}) const noexcept;

Description

This function examines the parameters in the container to find a match for the specified key, which may contain percent escapes. The comparison is performed as if all escaped characters were decoded first.


assert( url_view( "?first=John&last=Doe" ).encoded_params().contains( "first" ) );

Linear in `this->buffer().size()`.

Exceptions thrown on invalid input.

Exceptions

Name	Thrown on
`key`	contains an invalid percent-encoding.

Parameters

Name	Description
key	The key to match. By default, a case-sensitive comparison is used.
ic	An optional parameter. If the value ignore_case is passed here, the comparison is case-insensitive.

Return the number of matching keys

Synopsis

Declared in <include/boost/url/params_encoded_base.hpp>


std::size_t
count(
    pct_string_view key,
    ignore_case_param ic = = {}) const noexcept;

Description

This function examines the parameters in the container to find the number of matches for the specified key, which may contain percent escapes. The comparison is performed as if all escaped characters were decoded first.


assert( url_view( "?first=John&last=Doe" ).encoded_params().count( "first" ) == 1 );

Linear in `this->buffer().size()`.

Exceptions thrown on invalid input.

Exceptions

Name	Thrown on
`key`	contains an invalid percent-encoding.

Parameters

Name	Description
key	The key to match. By default, a case-sensitive comparison is used.
ic	An optional parameter. If the value ignore_case is passed here, the comparison is case-insensitive.

Find a matching key

Synopsis

Declared in <include/boost/url/params_encoded_base.hpp>


iterator
find(
    pct_string_view key,
    ignore_case_param ic = = {}) const noexcept;

» more...


iterator
find(
    iterator from,
    pct_string_view key,
    ignore_case_param ic = = {}) const noexcept;

» more...

Description

The search starts from the first param and proceeds forward until either the key is found or the end of the range is reached, in which case `end()` is returned.


assert( url_view( "?first=John&last=Doe" ).encoded_params().find( "First", ignore_case )->value == "John" );


return this->find( this->begin(), key, ic );

Linear in `this->buffer().size()`.

Exceptions thrown on invalid input.

Exceptions

Name	Thrown on
`[object Object]`	contains an invalid percent-encoding.

Return Value

an iterator to the param

Parameters

Name	Description
key	The key to match. By default, a case-sensitive comparison is used.
ic	An optional parameter. If the value ignore_case is passed here, the comparison is case-insensitive.
from	The position to begin the search from. This can be `end()`.

Find a matching key

Synopsis

Declared in <include/boost/url/params_encoded_base.hpp>


iterator
find(
    pct_string_view key,
    ignore_case_param ic = = {}) const noexcept;

Description

The search starts from the first param and proceeds forward until either the key is found or the end of the range is reached, in which case `end()` is returned.


assert( url_view( "?first=John&last=Doe" ).encoded_params().find( "First", ignore_case )->value == "John" );


return this->find( this->begin(), key, ic );

Linear in `this->buffer().size()`.

Exceptions thrown on invalid input.

Exceptions

Name	Thrown on
`key`	contains an invalid percent-encoding.

Return Value

an iterator to the param

Parameters

Name	Description
key	The key to match. By default, a case-sensitive comparison is used.
ic	An optional parameter. If the value ignore_case is passed here, the comparison is case-insensitive.

Find a matching key

Synopsis

Declared in <include/boost/url/params_encoded_base.hpp>


iterator
find(
    iterator from,
    pct_string_view key,
    ignore_case_param ic = = {}) const noexcept;

Description

The search starts at `from` and proceeds forward until either the key is found or the end of the range is reached, in which case `end()` is returned.


url_view u( "?First=John&Last=Doe" );

assert( u.encoded_params().find( "first" ) != u.encoded_params().find( "first", ignore_case ) );

Linear in `this->buffer().size()`.

Exceptions thrown on invalid input.

Exceptions

Name	Thrown on
`key`	contains an invalid percent-encoding.

Return Value

an iterator to the param

Parameters

Name	Description
from	The position to begin the search from. This can be `end()`.
key	The key to match. By default, a case-sensitive comparison is used.
ic	An optional parameter. If the value ignore_case is passed here, the comparison is case-insensitive.

Find a matching key

Synopsis

Declared in <include/boost/url/params_encoded_base.hpp>


iterator
find_last(
    pct_string_view key,
    ignore_case_param ic = = {}) const noexcept;

» more...


iterator
find_last(
    iterator before,
    pct_string_view key,
    ignore_case_param ic = = {}) const noexcept;

» more...

Description

The search starts from the last param and proceeds backwards until either the key is found or the beginning of the range is reached, in which case `end()` is returned.


assert( url_view( "?first=John&last=Doe" ).encoded_params().find_last( "last" )->value == "Doe" );

Linear in `this->buffer().size()`.

Exceptions thrown on invalid input.

Exceptions

Name	Thrown on
`[object Object]`	contains an invalid percent-encoding.

Return Value

an iterator to the param

Parameters

Name	Description
key	The key to match. By default, a case-sensitive comparison is used.
ic	An optional parameter. If the value ignore_case is passed here, the comparison is case-insensitive.
before	One past the position to begin the search from. This can be `end()`.

Find a matching key

Synopsis

Declared in <include/boost/url/params_encoded_base.hpp>


iterator
find_last(
    pct_string_view key,
    ignore_case_param ic = = {}) const noexcept;

Description

The search starts from the last param and proceeds backwards until either the key is found or the beginning of the range is reached, in which case `end()` is returned.


assert( url_view( "?first=John&last=Doe" ).encoded_params().find_last( "last" )->value == "Doe" );

Linear in `this->buffer().size()`.

Exceptions thrown on invalid input.

Exceptions

Name	Thrown on
`key`	contains an invalid percent-encoding.

Return Value

an iterator to the param

Parameters

Name	Description
key	The key to match. By default, a case-sensitive comparison is used.
ic	An optional parameter. If the value ignore_case is passed here, the comparison is case-insensitive.

Find a matching key

Synopsis

Declared in <include/boost/url/params_encoded_base.hpp>


iterator
find_last(
    iterator before,
    pct_string_view key,
    ignore_case_param ic = = {}) const noexcept;

Description

The search starts prior to `before` and proceeds backwards until either the key is found or the beginning of the range is reached, in which case `end()` is returned.


url_view u( "?First=John&Last=Doe" );

assert( u.encoded_params().find_last( "last" ) != u.encoded_params().find_last( "last", ignore_case ) );

Linear in `this->buffer().size()`.

Return Value

an iterator to the param

Parameters

Name	Description
before	One past the position to begin the search from. This can be `end()`.
key	The key to match. By default, a case-sensitive comparison is used.
ic	An optional parameter. If the value ignore_case is passed here, the comparison is case-insensitive.

A view representing query parameters in a URL

Synopsis

Declared in <include/boost/url/params_ref.hpp>


class params_ref
    : public params_base;

Types

Name	Description
`const_iterator`	A Bidirectional iterator to a query parameter
`const_reference`	The reference type
`difference_type`	A signed integer type used to represent differences.
`iterator`	A Bidirectional iterator to a query parameter
`reference`	The reference type
`size_type`	An unsigned integer type to represent sizes.
`value_type`	The value type

Member Functions

Name	Description
`append`	Append elements
`assign`	Assign elements
`begin`	Return an iterator to the beginning
`buffer`	Return the referenced character buffer.
`clear`	Clear the contents of the container
`contains`	Return true if a matching key exists
`count`	Return the number of matching keys
`empty`	Return true if there are no params
`end`	Return an iterator to the end
`erase`	Erase elements
`find`	Find a matching key
`find_last`	Find a matching key
`insert`	Insert elements
`operator params_view`	Conversion
`operator=`	Assignment
`params_ref` [constructor]	Constructor
`replace`	Replace elements
`set`	Set a value
`size`	Return the number of params
`unset`	Remove the value on an element
`url`	Return the referenced url

Static Member Functions

Name	Description
`max_size`	Return the maximum number of characters possible

Description

Objects of this type are used to interpret the query parameters as a bidirectional view of key/value pairs. The view does not retain ownership of the elements and instead references the original url. The caller is responsible for ensuring that the lifetime of the referenced url extends until it is no longer referenced. The view is modifiable; calling non-const members causes changes to the referenced url.

Percent escapes in strings returned when dereferencing iterators are automatically decoded. Reserved characters in strings supplied to modifier functions are automatically percent-escaped.


url u( "?first=John&last=Doe" );

params_ref p = u.params();

Changes to the underlying character buffer

can invalidate iterators which reference it. Modifications made through the container invalidate some or all iterators:

append : Only `end()`.

assign , clear , `operator=` : All elements.

erase : Erased elements and all elements after (including `end()`).

insert : All elements at or after the insertion point (including `end()`).

replace , set : Modified elements and all elements after (including `end()`).

Constructor

Synopsis

Declared in <include/boost/url/params_ref.hpp>


constexpr
params_ref(params_ref const& other) = default;

» more...


params_ref(
    params_ref const& other,
    encoding_opts opt) noexcept;

» more...

Description

After construction, both views reference the same url. Ownership is not transferred; the caller is responsible for ensuring the lifetime of the url extends until it is no longer referenced.


&this->url() == &other.url()

Constant.

Throws nothing.

Parameters

Name	Description
other	The other view.
opt	The options for decoding. If this parameter is omitted, `space_as_plus` is used.

Constructor

Synopsis

Declared in <include/boost/url/params_ref.hpp>


constexpr
params_ref(params_ref const& other) = default;

Description

After construction, both views reference the same url. Ownership is not transferred; the caller is responsible for ensuring the lifetime of the url extends until it is no longer referenced.


&this->url() == &other.url()

Constant.

Throws nothing.

Parameters

Name	Description
other	The other view.

Constructor

Synopsis

Declared in <include/boost/url/params_ref.hpp>


params_ref(
    params_ref const& other,
    encoding_opts opt) noexcept;

Description

After construction, both views will reference the same url but this instance will use the specified encoding_opts when the values are decoded.

Ownership is not transferred; the caller is responsible for ensuring the lifetime of the url extends until it is no longer referenced.


&this->url() == &other.url()

Constant.

Throws nothing.

Parameters

Name	Description
other	The other view.
opt	The options for decoding. If this parameter is omitted, `space_as_plus` is used.

Assignment

Synopsis

Declared in <include/boost/url/params_ref.hpp>


params_ref&
operator=(params_ref const& other);

» more...


params_ref&
operator=(std::initializer_list<param_view> init);

» more...

Description

The previous contents of this are replaced by the contents of `other.

All iterators are invalidated.

NOTE

The strings referenced by `other` must not come from the underlying url, or else the behavior is undefined.


this->assign( other.begin(), other.end() );

Linear in `other.buffer().size()`.

Strong guarantee.

Calls to allocate may throw.

Parameters

Name	Description
other	The params to assign.
init	The list of params to assign.

Assignment

Synopsis

Declared in <include/boost/url/params_ref.hpp>


params_ref&
operator=(params_ref const& other);

Description

The previous contents of this are replaced by the contents of `other.

All iterators are invalidated.

NOTE

The strings referenced by `other` must not come from the underlying url, or else the behavior is undefined.


this->assign( other.begin(), other.end() );

Linear in `other.buffer().size()`.

Strong guarantee.

Calls to allocate may throw.

Parameters

Name	Description
other	The params to assign.

Assignment

Synopsis

Declared in <include/boost/url/params_ref.hpp>


params_ref&
operator=(std::initializer_list<param_view> init);

Description

After assignment, the previous contents of the query parameters are replaced by the contents of the initializer-list.

None of character buffers referenced by

`init` may overlap the character buffer of the underlying url, or else the behavior is undefined.


this->assign( init );

Linear in `init.size()`.

Strong guarantee.

Calls to allocate may throw.

Parameters

Name	Description
init	The list of params to assign.

Conversion

Synopsis

Declared in <include/boost/url/params_ref.hpp>


operator params_view() const noexcept;

Return the referenced url

Synopsis

Declared in <include/boost/url/params_ref.hpp>


url_base&
url() const noexcept;

Description

This function returns the url referenced by the view.


url u( "?key=value" );

assert( &u.segments().url() == &u );


Throws nothing.

Clear the contents of the container

Synopsis

Declared in <include/boost/url/params_ref.hpp>


void
clear() noexcept;

Description

All iterators are invalidated.


this->url().remove_query();


this->empty() == true && this->url().has_query() == false

Constant.

Throws nothing.

Assign elements

Synopsis

Declared in <include/boost/url/params_ref.hpp>


void
assign(std::initializer_list<param_view> init);

» more...


template<class FwdIt>
void
assign(
    FwdIt first,
    FwdIt last);

» more...

Description

This function replaces the entire contents of the view with the params in the initializer-list .

All iterators are invalidated.

NOTE

The strings referenced by the inputs must not come from the underlying url, or else the behavior is undefined.


url u;

u.params().assign( {{ "first", "John" }, { "last", "Doe" }} );

Linear in `init.size()`.

Strong guarantee.

Calls to allocate may throw.

Parameters

Name	Description
init	The list of params to assign.
first,	last The range of params to assign.

Assign elements

Synopsis

Declared in <include/boost/url/params_ref.hpp>


void
assign(std::initializer_list<param_view> init);

Description

This function replaces the entire contents of the view with the params in the initializer-list .

All iterators are invalidated.

NOTE

The strings referenced by the inputs must not come from the underlying url, or else the behavior is undefined.


url u;

u.params().assign( {{ "first", "John" }, { "last", "Doe" }} );

Linear in `init.size()`.

Strong guarantee.

Calls to allocate may throw.

Parameters

Name	Description
init	The list of params to assign.

Assign elements

Synopsis

Declared in <include/boost/url/params_ref.hpp>


template<class FwdIt>
void
assign(
    FwdIt first,
    FwdIt last);

Description

This function replaces the entire contents of the view with the params in the range.

All iterators are invalidated.

NOTE

The strings referenced by the inputs must not come from the underlying url, or else the behavior is undefined.


std::is_convertible< std::iterator_traits< FwdIt >::reference_type, param_view >::value == true

Linear in the size of the range.

Strong guarantee.

Calls to allocate may throw.

Parameters

Name	Description
first,	last The range of params to assign.

Append elements

Synopsis

Declared in <include/boost/url/params_ref.hpp>


iterator
append(param_view const& p);

» more...


iterator
append(std::initializer_list<param_view> init);

» more...


template<class FwdIt>
iterator
append(
    FwdIt first,
    FwdIt last);

» more...

Description

This function appends a param to the view.

The `end()` iterator is invalidated.


url u;

u.params().append( { "first", "John" } );

Linear in `this->url().encoded_query().size()`.

Strong guarantee.

Calls to allocate may throw.

Return Value

An iterator to the new element.

Parameters

Name	Description
p	The param to append.
init	The list of params to append.
first,	last The range of params to append.

Append elements

Synopsis

Declared in <include/boost/url/params_ref.hpp>


iterator
append(param_view const& p);

Description

This function appends a param to the view.

The `end()` iterator is invalidated.


url u;

u.params().append( { "first", "John" } );

Linear in `this->url().encoded_query().size()`.

Strong guarantee.

Calls to allocate may throw.

Return Value

An iterator to the new element.

Parameters

Name	Description
p	The param to append.

Append elements

Synopsis

Declared in <include/boost/url/params_ref.hpp>


iterator
append(std::initializer_list<param_view> init);

Description

This function appends the params in an initializer-list to the view.

The `end()` iterator is invalidated.


url u;

u.params().append({ { "first", "John" }, { "last", "Doe" } });

Linear in `this->url().encoded_query().size()`.

Strong guarantee.

Calls to allocate may throw.

Return Value

An iterator to the first new element.

Parameters

Name	Description
init	The list of params to append.

Append elements

Synopsis

Declared in <include/boost/url/params_ref.hpp>


template<class FwdIt>
iterator
append(
    FwdIt first,
    FwdIt last);

Description

This function appends a range of params to the view.

The `end()` iterator is invalidated.

NOTE

The strings referenced by the inputs must not come from the underlying url, or else the behavior is undefined.


std::is_convertible< std::iterator_traits< FwdIt >::reference_type, param_view >::value == true

Linear in `this->url().encoded_query().size()`.

Strong guarantee.

Calls to allocate may throw.

Return Value

An iterator to the first new element.

Parameters

Name	Description
first,	last The range of params to append.

Insert elements

Synopsis

Declared in <include/boost/url/params_ref.hpp>


iterator
insert(
    iterator before,
    param_view const& p);

» more...


iterator
insert(
    iterator before,
    std::initializer_list<param_view> init);

» more...


template<class FwdIt>
iterator
insert(
    iterator before,
    FwdIt first,
    FwdIt last);

» more...

Description

This function inserts a param before the specified position.

All iterators that are equal to `before` or come after are invalidated.

Linear in `this->url().encoded_query().size()`.

Strong guarantee.

Calls to allocate may throw.

Return Value

An iterator to the inserted element.

Parameters

Name	Description
before	An iterator before which the param is inserted. This may be equal to `end()`.
p	The param to insert.
init	The list of params to insert.
first,	last The range of params to insert.

Insert elements

Synopsis

Declared in <include/boost/url/params_ref.hpp>


iterator
insert(
    iterator before,
    param_view const& p);

Description

This function inserts a param before the specified position.

All iterators that are equal to `before` or come after are invalidated.

Linear in `this->url().encoded_query().size()`.

Strong guarantee.

Calls to allocate may throw.

Return Value

An iterator to the inserted element.

Parameters

Name	Description
before	An iterator before which the param is inserted. This may be equal to `end()`.
p	The param to insert.

Insert elements

Synopsis

Declared in <include/boost/url/params_ref.hpp>


iterator
insert(
    iterator before,
    std::initializer_list<param_view> init);

Description

This function inserts the params in an initializer-list before the specified position.

All iterators that are equal to `before` or come after are invalidated.

NOTE

The strings referenced by the inputs must not come from the underlying url, or else the behavior is undefined.

Linear in `this->url().encoded_query().size()`.

Strong guarantee.

Calls to allocate may throw.

Return Value

An iterator to the first element inserted, or `before` if `init.size() == 0`.

Parameters

Name	Description
before	An iterator before which the element is inserted. This may be equal to `end()`.
init	The list of params to insert.

Insert elements

Synopsis

Declared in <include/boost/url/params_ref.hpp>


template<class FwdIt>
iterator
insert(
    iterator before,
    FwdIt first,
    FwdIt last);

Description

This function inserts a range of params before the specified position.

All iterators that are equal to `before` or come after are invalidated.

NOTE

The strings referenced by the inputs must not come from the underlying url, or else the behavior is undefined.


std::is_convertible< std::iterator_traits< FwdIt >::reference_type, param_view >::value == true

Linear in `this->url().encoded_query().size()`.

Strong guarantee.

Calls to allocate may throw.

Return Value

An iterator to the first element inserted, or `before` if `first == last`.

Parameters

Name	Description
before	An iterator before which the element is inserted. This may be equal to `end()`.
first,	last The range of params to insert.

Erase elements

Synopsis

Declared in <include/boost/url/params_ref.hpp>


iterator
erase(iterator pos) noexcept;

» more...


iterator
erase(
    iterator first,
    iterator last) noexcept;

» more...


std::size_t
erase(
    core::string_view key,
    ignore_case_param ic = = {}) noexcept;

» more...

Description

This function removes an element from the container.

All iterators that are equal to `pos` or come after are invalidated.


url u( "?first=John&last=Doe" );

params_ref::iterator it = u.params().erase( u.params().begin() );

assert( u.encoded_query() == "last=Doe" );

Linear in `this->url().encoded_query().size()`.

Throws nothing.

Return Value

An iterator to one past the removed element.

Parameters

Name	Description
pos	An iterator to the element.
first,	last The range of elements to erase.
key	The key to match. By default, a case-sensitive comparison is used.
ic	An optional parameter. If the value ignore_case is passed here, the comparison is case-insensitive.

Erase elements

Synopsis

Declared in <include/boost/url/params_ref.hpp>


iterator
erase(iterator pos) noexcept;

Description

This function removes an element from the container.

All iterators that are equal to `pos` or come after are invalidated.


url u( "?first=John&last=Doe" );

params_ref::iterator it = u.params().erase( u.params().begin() );

assert( u.encoded_query() == "last=Doe" );

Linear in `this->url().encoded_query().size()`.

Throws nothing.

Return Value

An iterator to one past the removed element.

Parameters

Name	Description
pos	An iterator to the element.

Erase elements

Synopsis

Declared in <include/boost/url/params_ref.hpp>


iterator
erase(
    iterator first,
    iterator last) noexcept;

Description

This function removes a range of elements from the container.

All iterators that are equal to `first` or come after are invalidated.

Linear in `this->url().encoded_query().size()`.

Throws nothing.

Return Value

An iterator to one past the removed range.

Parameters

Name	Description
first,	last The range of elements to erase.

Erase elements

Synopsis

Declared in <include/boost/url/params_ref.hpp>


std::size_t
erase(
    core::string_view key,
    ignore_case_param ic = = {}) noexcept;

Description

All iterators are invalidated.


this->count( key, ic ) == 0

Linear in `this->url().encoded_query().size()`.

Throws nothing.

Return Value

The number of elements removed from the container.

Parameters

Name	Description
key	The key to match. By default, a case-sensitive comparison is used.
ic	An optional parameter. If the value ignore_case is passed here, the comparison is case-insensitive.

Replace elements

Synopsis

Declared in <include/boost/url/params_ref.hpp>


iterator
replace(
    iterator pos,
    param_view const& p);

» more...


iterator
replace(
    iterator from,
    iterator to,
    std::initializer_list<param_view> init);

» more...


template<class FwdIt>
iterator
replace(
    iterator from,
    iterator to,
    FwdIt first,
    FwdIt last);

» more...

Description

This function replaces the contents of the element at `pos` with the specified param.

All iterators that are equal to `pos` or come after are invalidated.


url u( "?first=John&last=Doe" );

u.params().replace( u.params().begin(), { "title", "Mr" });

assert( u.encoded_query() == "title=Mr&last=Doe" );

Linear in `this->url().encoded_query().size()`.

Strong guarantee.

Calls to allocate may throw.

Return Value

An iterator to the element.

Parameters

Name	Description
pos	An iterator to the element.
p	The param to assign.
from,to	The range of elements to replace.
init	The list of params to assign.
first,	last The range of params to assign.

Replace elements

Synopsis

Declared in <include/boost/url/params_ref.hpp>


iterator
replace(
    iterator pos,
    param_view const& p);

Description

This function replaces the contents of the element at `pos` with the specified param.

All iterators that are equal to `pos` or come after are invalidated.


url u( "?first=John&last=Doe" );

u.params().replace( u.params().begin(), { "title", "Mr" });

assert( u.encoded_query() == "title=Mr&last=Doe" );

Linear in `this->url().encoded_query().size()`.

Strong guarantee.

Calls to allocate may throw.

Return Value

An iterator to the element.

Parameters

Name	Description
pos	An iterator to the element.
p	The param to assign.

Replace elements

Synopsis

Declared in <include/boost/url/params_ref.hpp>


iterator
replace(
    iterator from,
    iterator to,
    std::initializer_list<param_view> init);

Description

This function replaces a range of elements with the params in an initializer-list .

All iterators that are equal to `from` or come after are invalidated.

NOTE

The strings referenced by the inputs must not come from the underlying url, or else the behavior is undefined.

Linear in `this->url().encoded_query().size()`.

Strong guarantee.

Calls to allocate may throw.

Return Value

An iterator to the first element inserted, or one past `to` if `init.size() == 0`.

Parameters

Name	Description
from,to	The range of elements to replace.
init	The list of params to assign.

Replace elements

Synopsis

Declared in <include/boost/url/params_ref.hpp>


template<class FwdIt>
iterator
replace(
    iterator from,
    iterator to,
    FwdIt first,
    FwdIt last);

Description

This function replaces a range of elements with a range of params.

All iterators that are equal to `from` or come after are invalidated.

NOTE

The strings referenced by the inputs must not come from the underlying url, or else the behavior is undefined.


std::is_convertible< std::iterator_traits< FwdIt >::reference_type, param_view >::value == true

Linear in `this->url().encoded_query().size()`.

Strong guarantee.

Calls to allocate may throw.

Return Value

An iterator to the first element inserted, or one past `to` if `first == last`.

Parameters

Name	Description
from,to	The range of elements to replace.
first,	last The range of params to assign.

Remove the value on an element

Synopsis

Declared in <include/boost/url/params_ref.hpp>


iterator
unset(iterator pos) noexcept;

Description

This function removes the value of an element at the specified position. After the call returns, `has_value` for the element is false.

All iterators that are equal to `pos` or come after are invalidated.


url u( "?first=John&last=Doe" );

u.params().unset( u.params().begin() );

assert( u.encoded_query() == "first&last=Doe" );

Linear in `this->url().encoded_query().size()`.

Throws nothing.

Return Value

An iterator to the element.

Parameters

Name	Description
pos	An iterator to the element.

Set a value

Synopsis

Declared in <include/boost/url/params_ref.hpp>


iterator
set(
    iterator pos,
    core::string_view value);

» more...


iterator
set(
    core::string_view key,
    core::string_view value,
    ignore_case_param ic = = {});

» more...

Description

This function replaces the value of an element at the specified position.

All iterators that are equal to `pos` or come after are invalidated.


url u( "?id=42&id=69" );

u.params().set( u.params().begin(), "none" );

assert( u.encoded_query() == "id=none&id=69" );

Linear in `this->url().encoded_query().size()`.

Strong guarantee.

Calls to allocate may throw.

Return Value

An iterator to the element.

Parameters

Name	Description
pos	An iterator to the element.
value	The value to assign. The empty string still counts as a value. That is, `has_value` for the element is true.
key	The key to match. By default, a case-sensitive comparison is used.
ic	An optional parameter. If the value ignore_case is passed here, the comparison is case-insensitive.

Set a value

Synopsis

Declared in <include/boost/url/params_ref.hpp>


iterator
set(
    iterator pos,
    core::string_view value);

Description

This function replaces the value of an element at the specified position.

All iterators that are equal to `pos` or come after are invalidated.


url u( "?id=42&id=69" );

u.params().set( u.params().begin(), "none" );

assert( u.encoded_query() == "id=none&id=69" );

Linear in `this->url().encoded_query().size()`.

Strong guarantee.

Calls to allocate may throw.

Return Value

An iterator to the element.

Parameters

Name	Description
pos	An iterator to the element.
value	The value to assign. The empty string still counts as a value. That is, `has_value` for the element is true.

Set a value

Synopsis

Declared in <include/boost/url/params_ref.hpp>


iterator
set(
    core::string_view key,
    core::string_view value,
    ignore_case_param ic = = {});

Description

This function performs one of two actions depending on the value of `this->contains( key, ic )`.

If key is contained in the view then one of the matching elements has its value changed to the specified value. The remaining elements with a matching key are erased. Otherwise,

If `key` is not contained in the view, then the function apppends the param `{ key, value }`.

All iterators are invalidated.


url u( "?id=42&id=69" );

u.params().set( "id", "none" );

assert( u.params().count( "id" ) == 1 );


this->count( key, ic ) == 1 && this->find( key, ic )->value == value

Linear in `this->url().encoded_query().size()`.

Strong guarantee.

Calls to allocate may throw.

Return Value

An iterator to the appended or modified element.

Parameters

Name	Description
key	The key to match. By default, a case-sensitive comparison is used.
value	The value to assign. The empty string still counts as a value. That is, `has_value` for the element is true.
ic	An optional parameter. If the value ignore_case is passed here, the comparison is case-insensitive.

Common functionality for containers

Synopsis

Declared in <include/boost/url/params_base.hpp>


class params_base;

Types

Name	Description
`const_iterator`	A Bidirectional iterator to a query parameter
`const_reference`	The reference type
`difference_type`	A signed integer type used to represent differences.
`iterator`	A Bidirectional iterator to a query parameter
`reference`	The reference type
`size_type`	An unsigned integer type to represent sizes.
`value_type`	The value type

Member Functions

Name	Description
`begin`	Return an iterator to the beginning
`buffer`	Return the referenced character buffer.
`contains`	Return true if a matching key exists
`count`	Return the number of matching keys
`empty`	Return true if there are no params
`end`	Return an iterator to the end
`find`	Find a matching key
`find_last`	Find a matching key
`size`	Return the number of params

Static Member Functions

Name	Description
`max_size`	Return the maximum number of characters possible

Description

This base class is used by the library to provide common member functions for containers. This cannot be instantiated directly; Instead, use one of the containers or functions:

A Bidirectional iterator to a query parameter

Synopsis

Declared in <include/boost/url/impl/params_base.hpp>


class iterator;

Types

Name	Description
`difference_type`
`iterator_category`
`pointer`
`reference`
`value_type`

Member Functions

Name	Description
`iterator` [constructor]
`operator!=`
`operator*`
`operator++`
`operator--`
`operator->`
`operator=`
`operator==`

Description

Objects of this type allow iteration through the parameters in the query. Any percent-escapes in returned strings are decoded first. The values returned are read-only; changes to parameters must be made through the container instead, if the container supports modification.

The strings produced when iterators are dereferenced belong to the iterator and become invalidated when that particular iterator is incremented, decremented, or destroyed.

NOTE

The implementation may use temporary, recycled storage to store decoded strings. These iterators are meant to be used ephemerally. That is, for short durations such as within a function scope. Do not store iterators with static storage duration or as long-lived objects.

Synopsis

Declared in <include/boost/url/impl/params_base.hpp>


using value_type = params_base::value_type;

Synopsis

Declared in <include/boost/url/impl/params_base.hpp>


using reference = params_base::reference;

Synopsis

Declared in <include/boost/url/impl/params_base.hpp>


using pointer = reference;

Synopsis

Declared in <include/boost/url/impl/params_base.hpp>


using difference_type = params_base::difference_type;

Synopsis

Declared in <include/boost/url/impl/params_base.hpp>


using iterator_category = std::bidirectional_iterator_tag;

Synopsis

Declared in <include/boost/url/impl/params_base.hpp>


constexpr
iterator() = default;

» more...


constexpr
iterator(iterator const&) = default;

» more...

Synopsis

Declared in <include/boost/url/impl/params_base.hpp>


constexpr
iterator() = default;

Synopsis

Declared in <include/boost/url/impl/params_base.hpp>


constexpr
iterator(iterator const&) = default;

Synopsis

Declared in <include/boost/url/impl/params_base.hpp>


constexpr
iterator&
operator=(iterator const&) noexcept = default;

Synopsis

Declared in <include/boost/url/impl/params_base.hpp>


iterator&
operator++() noexcept;

» more...


iterator
operator++(int) noexcept;

» more...

Synopsis

Declared in <include/boost/url/impl/params_base.hpp>


iterator&
operator++() noexcept;

Synopsis

Declared in <include/boost/url/impl/params_base.hpp>


iterator
operator++(int) noexcept;

Synopsis

Declared in <include/boost/url/impl/params_base.hpp>


iterator&
operator--() noexcept;

» more...


iterator
operator--(int) noexcept;

» more...

Synopsis

Declared in <include/boost/url/impl/params_base.hpp>


iterator&
operator--() noexcept;

Synopsis

Declared in <include/boost/url/impl/params_base.hpp>


iterator
operator--(int) noexcept;

Synopsis

Declared in <include/boost/url/impl/params_base.hpp>


reference
operator*() const;

Synopsis

Declared in <include/boost/url/impl/params_base.hpp>


pointer
operator->() const = delete;

Synopsis

Declared in <include/boost/url/impl/params_base.hpp>


bool
operator==(iterator const& other) const noexcept;

Synopsis

Declared in <include/boost/url/impl/params_base.hpp>


bool
operator!=(iterator const& other) const noexcept;

A Bidirectional iterator to a query parameter

Synopsis

Declared in <include/boost/url/params_base.hpp>


using const_iterator = iterator;

Description

The strings produced when iterators are dereferenced belong to the iterator and become invalidated when that particular iterator is incremented, decremented, or destroyed.

NOTE

The value type

Synopsis

Declared in <include/boost/url/params_base.hpp>


using value_type = param;

Description

Values of this type represent parameters whose strings retain unique ownership by making a copy.


params_view::value_type qp( *url_view( "?first=John&last=Doe" ).params().find( "first" ) );

Synopsis

Declared in <include/boost/url/params_base.hpp>


using reference = param;

Description

This is the type of value returned when iterators of the view are dereferenced.

Synopsis

Declared in <include/boost/url/params_base.hpp>


using const_reference = param;


constexpr
static
std::size_t
max_size() noexcept;

Description

This represents the largest number of characters that are possible in a path, not including any null terminator.

Throws nothing.

Return the referenced character buffer.

Synopsis

Declared in <include/boost/url/params_base.hpp>


pct_string_view
buffer() const noexcept;

Description

This function returns the character buffer referenced by the view. The returned string may contain percent escapes.


assert( url_view( "?first=John&last=Doe" ).params().buffer() == "?first=John&last=Doe" );

Constant.

Throws nothing.

Return true if there are no params

Synopsis

Declared in <include/boost/url/params_base.hpp>


bool
empty() const noexcept;

Description


assert( ! url_view( "?key=value" ).params().empty() );

Constant.

Throws nothing.

Return the number of params

Synopsis

Declared in <include/boost/url/params_base.hpp>


std::size_t
size() const noexcept;

Description


assert( url_view( "?key=value").params().size() == 1 );

Constant.

Throws nothing.

Return an iterator to the beginning

Synopsis

Declared in <include/boost/url/params_base.hpp>


iterator
begin() const noexcept;

Description

Linear in the size of the first param.

Throws nothing.

Return an iterator to the end

Synopsis

Declared in <include/boost/url/params_base.hpp>


iterator
end() const noexcept;

Description

Constant.

Throws nothing.

Return true if a matching key exists

Synopsis

Declared in <include/boost/url/params_base.hpp>


bool
contains(
    core::string_view key,
    ignore_case_param ic = = {}) const noexcept;

Description

This function examines the parameters in the container to find a match for the specified key. The comparison is performed as if all escaped characters were decoded first.


assert( url_view( "?first=John&last=Doe" ).params().contains( "first" ) );

Linear in `this->buffer().size()`.

Throws nothing.

Parameters

Name	Description
key	The key to match. By default, a case-sensitive comparison is used.
ic	An optional parameter. If the value ignore_case is passed here, the comparison is case-insensitive.

Return the number of matching keys

Synopsis

Declared in <include/boost/url/params_base.hpp>


std::size_t
count(
    core::string_view key,
    ignore_case_param ic = = {}) const noexcept;

Description

This function examines the parameters in the container to find the number of matches for the specified key. The comparison is performed as if all escaped characters were decoded first.


assert( url_view( "?first=John&last=Doe" ).params().count( "first" ) == 1 );

Linear in `this->buffer().size()`.

Throws nothing.

Parameters

Name	Description
key	The key to match. By default, a case-sensitive comparison is used.
ic	An optional parameter. If the value ignore_case is passed here, the comparison is case-insensitive.

Find a matching key

Synopsis

Declared in <include/boost/url/params_base.hpp>


iterator
find(
    core::string_view key,
    ignore_case_param ic = = {}) const noexcept;

» more...


iterator
find(
    iterator from,
    core::string_view key,
    ignore_case_param ic = = {}) const noexcept;

» more...

Description

This function examines the parameters in the container to find a match for the specified key. The comparison is performed as if all escaped characters were decoded first.

The search starts from the first param and proceeds forward until either the key is found or the end of the range is reached, in which case `end()` is returned.


assert( (*url_view( "?first=John&last=Doe" ).params().find( "First", ignore_case )).value == "John" );


return this->find( this->begin(), key, ic );

Linear in `this->buffer().size()`.

Return Value

an iterator to the param

Parameters

Name	Description
key	The key to match. By default, a case-sensitive comparison is used.
ic	An optional parameter. If the value ignore_case is passed here, the comparison is case-insensitive.
from	The position to begin the search from. This can be `end()`.

Find a matching key

Synopsis

Declared in <include/boost/url/params_base.hpp>


iterator
find(
    core::string_view key,
    ignore_case_param ic = = {}) const noexcept;

Description

This function examines the parameters in the container to find a match for the specified key. The comparison is performed as if all escaped characters were decoded first.

The search starts from the first param and proceeds forward until either the key is found or the end of the range is reached, in which case `end()` is returned.


assert( (*url_view( "?first=John&last=Doe" ).params().find( "First", ignore_case )).value == "John" );


return this->find( this->begin(), key, ic );

Linear in `this->buffer().size()`.

Return Value

an iterator to the param

Parameters

Name	Description
key	The key to match. By default, a case-sensitive comparison is used.
ic	An optional parameter. If the value ignore_case is passed here, the comparison is case-insensitive.

Find a matching key

Synopsis

Declared in <include/boost/url/params_base.hpp>


iterator
find(
    iterator from,
    core::string_view key,
    ignore_case_param ic = = {}) const noexcept;

Description

This function examines the parameters in the container to find a match for the specified key. The comparison is performed as if all escaped characters were decoded first.

The search starts at `from` and proceeds forward until either the key is found or the end of the range is reached, in which case `end()` is returned.


url_view u( "?First=John&Last=Doe" );

assert( u.params().find( "first" ) != u.params().find( "first", ignore_case ) );

Linear in `this->buffer().size()`.

Return Value

an iterator to the param

Parameters

Name	Description
from	The position to begin the search from. This can be `end()`.
key	The key to match. By default, a case-sensitive comparison is used.
ic	An optional parameter. If the value ignore_case is passed here, the comparison is case-insensitive.

Find a matching key

Synopsis

Declared in <include/boost/url/params_base.hpp>


iterator
find_last(
    core::string_view key,
    ignore_case_param ic = = {}) const noexcept;

» more...


iterator
find_last(
    iterator before,
    core::string_view key,
    ignore_case_param ic = = {}) const noexcept;

» more...

Description

This function examines the parameters in the container to find a match for the specified key. The comparison is performed as if all escaped characters were decoded first.

The search starts from the last param and proceeds backwards until either the key is found or the beginning of the range is reached, in which case `end()` is returned.


assert( (*url_view( "?first=John&last=Doe" ).params().find_last( "last" )).value == "Doe" );

Linear in `this->buffer().size()`.

Return Value

an iterator to the param

Parameters

Name	Description
key	The key to match. By default, a case-sensitive comparison is used.
ic	An optional parameter. If the value ignore_case is passed here, the comparison is case-insensitive.
before	One past the position to begin the search from. This can be `end()`.

Find a matching key

Synopsis

Declared in <include/boost/url/params_base.hpp>


iterator
find_last(
    core::string_view key,
    ignore_case_param ic = = {}) const noexcept;

Description

This function examines the parameters in the container to find a match for the specified key. The comparison is performed as if all escaped characters were decoded first.

The search starts from the last param and proceeds backwards until either the key is found or the beginning of the range is reached, in which case `end()` is returned.


assert( (*url_view( "?first=John&last=Doe" ).params().find_last( "last" )).value == "Doe" );

Linear in `this->buffer().size()`.

Return Value

an iterator to the param

Parameters

Name	Description
key	The key to match. By default, a case-sensitive comparison is used.
ic	An optional parameter. If the value ignore_case is passed here, the comparison is case-insensitive.

Find a matching key

Synopsis

Declared in <include/boost/url/params_base.hpp>


iterator
find_last(
    iterator before,
    core::string_view key,
    ignore_case_param ic = = {}) const noexcept;

Description

This function examines the parameters in the container to find a match for the specified key. The comparison is performed as if all escaped characters were decoded first.

The search starts prior to `before` and proceeds backwards until either the key is found or the beginning of the range is reached, in which case `end()` is returned.


url_view u( "?First=John&Last=Doe" );

assert( u.params().find_last( "last" ) != u.params().find_last( "last", ignore_case ) );

Linear in `this->buffer().size()`.

Return Value

an iterator to the param

Parameters

Name	Description
before	One past the position to begin the search from. This can be `end()`.
key	The key to match. By default, a case-sensitive comparison is used.
ic	An optional parameter. If the value ignore_case is passed here, the comparison is case-insensitive.

A view representing query parameters in a URL

Synopsis

Declared in <include/boost/url/params_view.hpp>


class params_view
    : public params_base;

Types

Name	Description
`const_iterator`	A Bidirectional iterator to a query parameter
`const_reference`	The reference type
`difference_type`	A signed integer type used to represent differences.
`iterator`	A Bidirectional iterator to a query parameter
`reference`	The reference type
`size_type`	An unsigned integer type to represent sizes.
`value_type`	The value type

Member Functions

Name	Description
`begin`	Return an iterator to the beginning
`buffer`	Return the referenced character buffer.
`contains`	Return true if a matching key exists
`count`	Return the number of matching keys
`empty`	Return true if there are no params
`end`	Return an iterator to the end
`find`	Find a matching key
`find_last`	Find a matching key
`operator=`	Assignment
`params_view` [constructor]	Constructor
`size`	Return the number of params

Static Member Functions

Name	Description
`max_size`	Return the maximum number of characters possible

Description

Objects of this type are used to interpret the query parameters as a bidirectional view of key/value pairs.

The view does not retain ownership of the elements and instead references the original character buffer. The caller is responsible for ensuring that the lifetime of the buffer extends until it is no longer referenced.


url_view u( "?first=John&last=Doe" );

params_view p = u.params();

Percent escapes in strings returned when dereferencing iterators are automatically decoded.

Changes to the underlying character buffer

can invalidate iterators which reference it.

Constructor

Synopsis

Declared in <include/boost/url/params_view.hpp>


params_view() = default;

» more...


constexpr
params_view(params_view const& other) = default;

» more...


params_view(
    params_view const& other,
    encoding_opts opt) noexcept;

» more...


params_view(core::string_view s);

» more...


params_view(
    core::string_view s,
    encoding_opts opt);

» more...

Description

Default-constructed params have zero elements.


params_view qp;


return params_view( "" );

Constant.

Throws nothing.

Exceptions

Name	Thrown on
`[object Object]`	contains an invalid query parameter string.

Parameters

Name	Description
s	The string to parse.
opt	The options for decoding. If this parameter is omitted, `space_as_plus` is used.

Constructor

Synopsis

Declared in <include/boost/url/params_view.hpp>


params_view() = default;

Description

Default-constructed params have zero elements.


params_view qp;


return params_view( "" );

Constant.

Throws nothing.

Constructor

Synopsis

Declared in <include/boost/url/params_view.hpp>


constexpr
params_view(params_view const& other) = default;

Description

After construction both views reference the same character buffer.

Ownership is not transferred; the caller is responsible for ensuring the lifetime of the buffer extends until it is no longer referenced.


this->buffer().data() == other.buffer().data()

Constant.

Throws nothing

Constructor

Synopsis

Declared in <include/boost/url/params_view.hpp>


params_view(
    params_view const& other,
    encoding_opts opt) noexcept;

Description

After construction both views will reference the same character buffer but this instance will use the specified encoding_opts when the values are decoded.

Ownership is not transferred; the caller is responsible for ensuring the lifetime of the buffer extends until it is no longer referenced.


this->buffer().data() == other.buffer().data()

Constant.

Throws nothing

Constructor

Synopsis

Declared in <include/boost/url/params_view.hpp>


params_view(core::string_view s);

Description

This function constructs params from a valid query parameter string, which can contain percent escapes. Unlike the parameters in URLs, the string passed here should not start with "?". Upon construction, the view references the character buffer pointed to by `s`. The caller is responsible for ensuring that the lifetime of the buffer extends until it is no longer referenced.


params_view qp( "first=John&last=Doe" );


return parse_query( s ).value();


this->buffer().data() == s.data()

Linear in `s`.

Exceptions thrown on invalid input.


query-params    = [ query-param ] *( "&" query-param )

query-param     = key [ "=" value ]

3.4. Query

Exceptions

Name	Thrown on
`s`	contains an invalid query parameter string.

Parameters

Name	Description
s	The string to parse.

Constructor

Synopsis

Declared in <include/boost/url/params_view.hpp>


params_view(
    core::string_view s,
    encoding_opts opt);

Description

This function constructs params from a valid query parameter string, which can contain percent escapes.

This instance will use the specified encoding_opts when the values are decoded.

Unlike the parameters in URLs, the string passed here should not start with "?". Upon construction, the view will reference the character buffer pointed to by `s`. The caller is responsible for ensuring that the lifetime of the buffer extends until it is no longer referenced.


encoding_opts opt;
opt.space_as_plus = true;
params_view qp( "name=John+Doe", opt );


return params_view(parse_query( s ).value(), opt);


this->buffer().data() == s.data()

Linear in `s`.

Exceptions thrown on invalid input.


query-params    = [ query-param ] *( "&" query-param )

query-param     = key [ "=" value ]

3.4. Query

Exceptions

Name	Thrown on
`s`	contains an invalid query parameter string.

Parameters

Name	Description
s	The string to parse.
opt	The options for decoding. If this parameter is omitted, `space_as_plus` is used.

Assignment

Synopsis

Declared in <include/boost/url/params_view.hpp>


params_view&
operator=(params_view const&) = default;

Description

After assignment, both views reference the same underlying character buffer.

Ownership is not transferred; the caller is responsible for ensuring the lifetime of the buffer extends until it is no longer referenced.


this->buffer().data() == other.buffer().data()

Constant

Throws nothing

Types

Name	Description
`absolute_uri_rule_t`
`authority_rule_t`
`ipv4_address_rule_t`
`ipv6_address_rule_t`
`named_arg`
`pct_encoded_rule_t`
`query_rule_t`
`relative_ref_rule_t`
`uri_reference_rule_t`
`uri_rule_t`

Synopsis

Declared in <include/boost/url/rfc/query_rule.hpp>


struct query_rule_t;

Types

Name	Description
`value_type`

Member Functions

Name	Description
`parse`

Synopsis

Declared in <include/boost/url/rfc/query_rule.hpp>


using value_type = params_encoded_view;

Synopsis

Declared in <include/boost/url/rfc/query_rule.hpp>


system::result<    _implementation-defined_>
parse(
    char const*& it,
    char const* end) const noexcept;

Synopsis

Declared in <include/boost/url/detail/format_args.hpp>


template<class T>
using named_arg = detail::named_arg<T>;

Synopsis

Declared in <include/boost/url/rfc/absolute_uri_rule.hpp>


struct absolute_uri_rule_t;

Types

Name	Description
`value_type`

Member Functions

Name	Description
`parse`

Synopsis

Declared in <include/boost/url/rfc/absolute_uri_rule.hpp>


using value_type = url_view;

Synopsis

Declared in <include/boost/url/rfc/absolute_uri_rule.hpp>


system::result<    _implementation-defined_>
parse(
    char const*& it,
    char const* end) const noexcept;

Synopsis

Declared in <include/boost/url/rfc/authority_rule.hpp>


struct authority_rule_t;

Types

Name	Description
`value_type`

Member Functions

Name	Description
`parse`

Synopsis

Declared in <include/boost/url/rfc/authority_rule.hpp>


using value_type = authority_view;

Synopsis

Declared in <include/boost/url/rfc/authority_rule.hpp>


system::result<    _implementation-defined_>
parse(
    char const*& it,
    char const* end) const noexcept;

Synopsis

Declared in <include/boost/url/rfc/ipv4_address_rule.hpp>


struct ipv4_address_rule_t;

Types

Name	Description
`value_type`

Member Functions

Name	Description
`parse`

Synopsis

Declared in <include/boost/url/rfc/ipv4_address_rule.hpp>


using value_type = ipv4_address;

Synopsis

Declared in <include/boost/url/rfc/ipv4_address_rule.hpp>


system::result<ipv4_address>
parse(
    char const*& it,
    char const* end) const noexcept;

Synopsis

Declared in <include/boost/url/rfc/ipv6_address_rule.hpp>


struct ipv6_address_rule_t;

Types

Name	Description
`value_type`

Member Functions

Name	Description
`parse`

Synopsis

Declared in <include/boost/url/rfc/ipv6_address_rule.hpp>


using value_type = ipv6_address;

Synopsis

Declared in <include/boost/url/rfc/ipv6_address_rule.hpp>


system::result<ipv6_address>
parse(
    char const*& it,
    char const* end) const noexcept;

Synopsis

Declared in <include/boost/url/rfc/pct_encoded_rule.hpp>


template<class CharSet>
struct pct_encoded_rule_t;

Types

Name	Description
`value_type`

Member Functions

Name	Description
`parse`
`pct_encoded_rule_t` [constructor]

Synopsis

Declared in <include/boost/url/rfc/pct_encoded_rule.hpp>


using value_type = pct_string_view;

Synopsis

Declared in <include/boost/url/rfc/pct_encoded_rule.hpp>


system::result<    _implementation-defined_>
parse(
    char const*& it,
    char const* end) const noexcept;

Synopsis

Declared in <include/boost/url/rfc/pct_encoded_rule.hpp>


constexpr
pct_encoded_rule_t(CharSet const& cs) noexcept;

Synopsis

Declared in <include/boost/url/rfc/relative_ref_rule.hpp>


struct relative_ref_rule_t;

Types

Name	Description
`value_type`

Member Functions

Name	Description
`parse`

Synopsis

Declared in <include/boost/url/rfc/relative_ref_rule.hpp>


using value_type = url_view;

Synopsis

Declared in <include/boost/url/rfc/relative_ref_rule.hpp>


system::result<    _implementation-defined_>
parse(
    char const*& it,
    char const* end) const noexcept;

Synopsis

Declared in <include/boost/url/rfc/uri_rule.hpp>


struct uri_rule_t;

Types

Name	Description
`value_type`

Member Functions

Name	Description
`parse`

Synopsis

Declared in <include/boost/url/rfc/uri_rule.hpp>


using value_type = url_view;

Synopsis

Declared in <include/boost/url/rfc/uri_rule.hpp>


system::result<    _implementation-defined_>
parse(
    char const*& it,
    char const const* end) const noexcept;

Synopsis

Declared in <include/boost/url/rfc/uri_reference_rule.hpp>


struct uri_reference_rule_t;

Types

Name	Description
`value_type`

Member Functions

Name	Description
`parse`

Synopsis

Declared in <include/boost/url/rfc/uri_reference_rule.hpp>


using value_type = url_view;

Synopsis

Declared in <include/boost/url/rfc/uri_reference_rule.hpp>


system::result<    _implementation-defined_>
parse(
    char const*& it,
    char const* end) const noexcept;

A view representing query parameters in a URL

Synopsis

Declared in <include/boost/url/params_encoded_view.hpp>


class params_encoded_view
    : public params_encoded_base;

Types

Name	Description
`const_iterator`	A Bidirectional iterator to a query parameter
`const_reference`	The reference type
`difference_type`	A signed integer type used to represent differences.
`iterator`	A Bidirectional iterator to a query parameter
`reference`	The reference type
`size_type`	An unsigned integer type to represent sizes.
`value_type`	The value type

Member Functions

Name	Description
`begin`	Return an iterator to the beginning
`buffer`	Return the query corresponding to these params
`contains`	Return true if a matching key exists
`count`	Return the number of matching keys
`empty`	Return true if there are no params
`end`	Return an iterator to the end
`find`	Find a matching key
`find_last`	Find a matching key
`operator params_view`	Conversion
`operator=`	Assignment
`params_encoded_view` [constructor]	Constructor
`size`	Return the number of params

Static Member Functions

Name	Description
`max_size`	Return the maximum number of characters possible

Friends

Name	Description
`parse_query`	Parse a string and return an encoded params view

Description

Objects of this type are used to interpret the query parameters as a bidirectional view of key/value pairs.


url_view u( "?first=John&last=Doe" );

params_encoded_view p = u.encoded_params();

Strings produced when elements are returned have type param_pct_view and represent encoded strings. Strings passed to member functions may contain percent escapes, and throw exceptions on invalid inputs.

Changes to the underlying character buffer

can invalidate iterators which reference it.

Constructor

Synopsis

Declared in <include/boost/url/params_encoded_view.hpp>


constexpr
params_encoded_view() = default;

» more...


constexpr
params_encoded_view(params_encoded_view const& other) = default;

» more...


params_encoded_view(core::string_view s);

» more...

Description

Default-constructed params have zero elements.


params_encoded_view qp;


return params_encoded_view( "" );

Constant.

Throws nothing.

Exceptions

Name	Thrown on
`[object Object]`	contains an invalid query parameter string.

Parameters

Name	Description
s	The string to parse.

Constructor

Synopsis

Declared in <include/boost/url/params_encoded_view.hpp>


constexpr
params_encoded_view() = default;

Description

Default-constructed params have zero elements.


params_encoded_view qp;


return params_encoded_view( "" );

Constant.

Throws nothing.

Constructor

Synopsis

Declared in <include/boost/url/params_encoded_view.hpp>


constexpr
params_encoded_view(params_encoded_view const& other) = default;

Description

After construction both views reference the same character buffer.

Ownership is not transferred; the caller is responsible for ensuring the lifetime of the buffer extends until it is no longer referenced.


this->buffer().data() == other.buffer().data()

Constant.

Throws nothing

Constructor

Synopsis

Declared in <include/boost/url/params_encoded_view.hpp>


params_encoded_view(core::string_view s);

Description


params_encoded_view qp( "first=John&last=Doe" );


return parse_query( s ).value();


this->buffer().data() == s.data()

Linear in `s`.

Exceptions thrown on invalid input.


query-params    = [ query-param ] *( "&" query-param )

query-param     = key [ "=" value ]

3.4. Query

Exceptions

Name	Thrown on
`s`	contains an invalid query parameter string.

Parameters

Name	Description
s	The string to parse.

Assignment

Synopsis

Declared in <include/boost/url/params_encoded_view.hpp>


constexpr
params_encoded_view&
operator=(params_encoded_view const&) = default;

Description

After assignment, both views reference the same underlying character buffer.

Ownership is not transferred; the caller is responsible for ensuring the lifetime of the buffer extends until it is no longer referenced.


this->buffer().data() == other.buffer().data()

Constant

Throws nothing

Conversion

Synopsis

Declared in <include/boost/url/params_encoded_view.hpp>


operator params_view() const noexcept;

Description

This conversion returns a new view which references the same underlying character buffer, and whose iterators and members return ordinary strings with decoding applied to any percent escapes.

Ownership is not transferred; the caller is responsible for ensuring the lifetime of the buffer extends until it is no longer referenced.


params_view qp = parse_path( "/path/to/file.txt" ).value();


params_view( *this ).buffer().data() == this->buffer().data()

Constant

Throws nothing

Parse a string and return an encoded params view

Synopsis

Declared in <include/boost/url/params_encoded_view.hpp>


friend
system::result<params_encoded_view>
parse_query(core::string_view s) noexcept;

Description

This function parses the string and returns the corresponding params object if the string is valid, otherwise returns an error.


query         = *( pchar / "/" / "?" )

No-throw guarantee.

Return Value

A valid view on success, otherwise an error code.

Parameters

Name	Description
s	The string to parse

Synopsis

Declared in <include/boost/url/params_encoded_view.hpp>


system::result<params_encoded_view>
parse_query(core::string_view s) noexcept;

Description

This function parses the string and returns the corresponding params object if the string is valid, otherwise returns an error.


query         = *( pchar / "/" / "?" )

No-throw guarantee.

Parse a string and return an encoded params view

This function parses the string and returns the corresponding params object if the string is valid, otherwise returns an error.


query         = *( pchar / "/" / "?" )

No-throw guarantee.

Return Value

A valid view on success, otherwise an error code.

Parameters

Name	Description
s	The string to parse
s	The string to parse

Synopsis

Declared in <include/boost/url/url_base.hpp>


class url_base
    : public url_view_base;

Member Functions

Name	Description
`authority`	Return the authority
`buffer`	Return the url string
`c_str`	Return the url as a null-terminated string
`capacity`	Return the number of characters that can be stored without reallocating
`clear`	Clear the contents while preserving the capacity
`compare`	Return the result of comparing this with another url
`data`	Return a pointer to the url's character buffer
`empty`	Return true if the url is empty
`encoded_authority`	Return the authority.
`encoded_fragment`	Return the fragment
`encoded_host`	Return the host
`encoded_host_address`	Return the host
`encoded_host_and_port`	Return the host and port
`encoded_host_name`	Return the host name
`encoded_origin`	Return the origin
`encoded_params`	Return the query as a container of parameters
`encoded_password`	Return the password
`encoded_path`	Return the path
`encoded_query`	Return the query
`encoded_resource`	Return the resource
`encoded_segments`	Return the path as a container of segments
`encoded_target`	Return the target
`encoded_user`	Return the user
`encoded_userinfo`	Return the userinfo
`encoded_zone_id`	Return the IPv6 Zone ID
`fragment`	Return the fragment
`has_authority`	Return true if an authority is present
`has_fragment`	Return true if a fragment is present
`has_password`	Return true if a password is present
`has_port`	Return true if a port is present
`has_query`	Return true if a query is present
`has_scheme`	Return true a scheme is present
`has_userinfo`	Return true if a userinfo is present
`host`	Return the host
`host_address`	Return the host
`host_ipv4_address`	Return the host IPv4 address
`host_ipv6_address`	Return the host IPv6 address
`host_ipvfuture`	Return the host IPvFuture address
`host_name`	Return the host name
`host_type`	Return the host type
`is_path_absolute`	Return true if the path is absolute
`normalize`	Normalize the URL components
`normalize_authority`	Normalize the URL authority
`normalize_fragment`	Normalize the URL fragment
`normalize_path`	Normalize the URL path
`normalize_query`	Normalize the URL query
`normalize_scheme`	Normalize the URL scheme
`operator core::string_view`	Return the URL as a core::string_view
`params`	url_view_base::params Return the query as a container of parameters
`password`	Return the password
`path`	Return the path
`persist`	Return a shared, persistent copy of the url
`port`	Return the port
`port_number`	Return the port
`query`	Return the query
`remove_authority`	Remove the authority
`remove_fragment`	Remove the fragment
`remove_origin`	Remove the origin component
`remove_password`	Remove the password
`remove_port`	Remove the port
`remove_query`	Remove the query
`remove_scheme`	Remove the scheme
`remove_userinfo`	Remove the userinfo
`reserve`	Adjust the capacity without changing the size
`resolve`	Resolve a URL reference against this base URL
`scheme`	Return the scheme
`scheme_id`	Return the scheme
`segments`	Return the path as a container of segments
`set_encoded_authority`	Set the authority
`set_encoded_fragment`	Set the fragment.
`set_encoded_host`	Set the host
`set_encoded_host_address`	Set the host to an address
`set_encoded_host_name`	Set the host to a name
`set_encoded_params`	Set the query params
`set_encoded_password`	Set the password.
`set_encoded_path`	Set the path.
`set_encoded_query`	Set the query
`set_encoded_user`	Set the user
`set_encoded_userinfo`	Set the userinfo.
`set_fragment`	Set the fragment.
`set_host`	Set the host
`set_host_address`	Set the host to an address
`set_host_ipv4`	Set the host to an address
`set_host_ipv6`	Set the host to an address
`set_host_ipvfuture`	Set the host to an address
`set_host_name`	Set the host to a name
`set_params`	Set the query params
`set_password`	Set the password.
`set_path`	Set the path.
`set_path_absolute`	Set if the path is absolute
`set_port`	Set the port
`set_port_number`	Set the port
`set_query`	Set the query
`set_scheme`	Set the scheme
`set_scheme_id`	Set the scheme
`set_user`	Set the user
`set_userinfo`	Set the userinfo
`size`	Return the number of characters in the url
`user`	Return the user
`userinfo`	Return the userinfo
`zone_id`	Return the IPv6 Zone ID

Static Member Functions

Name	Description
`max_size`	Return the maximum number of characters possible

Friends

Name	Description
`operator!=`	Return the result of comparing two URLs
`operator<`	Return the result of comparing two URLs
`operator<<`	Format the url to the output stream
`operator<=`	Return the result of comparing two URLs
`operator==`	Return the result of comparing two URLs
`operator>`	Return the result of comparing two URLs
`operator>=`	Return the result of comparing two URLs
`resolve`	Resolve a URL reference against a base URL

Description

This base class is used by the library to provide common member functions for containers. This cannot be instantiated directly; Instead, use one of the containers or functions:

Return the url as a null-terminated string

Synopsis

Declared in <include/boost/url/url_base.hpp>


char const*
c_str() const noexcept;

Description

This function returns a pointer to a null terminated string representing the url, which may contain percent escapes.


assert( std::strlen( url( "http://www.example.com" ).c_str() ) == 22 );

Constant.

Throws nothing.

Return the number of characters that can be stored without reallocating

Synopsis

Declared in <include/boost/url/url_base.hpp>


std::size_t
capacity() const noexcept;

Description

This does not include the null terminator, which is always present.

Constant.

Throws nothing.

Clear the contents while preserving the capacity

Synopsis

Declared in <include/boost/url/url_base.hpp>


void
clear() noexcept;

Description


this->empty() == true

Constant.

No-throw guarantee.

Adjust the capacity without changing the size

Synopsis

Declared in <include/boost/url/url_base.hpp>


void
reserve(std::size_t n);

Description

This function adjusts the capacity of the container in characters, without affecting the current contents. Has no effect if `n<= this->capacity()`.

Strong guarantee.

Calls to allocate may throw.

Exceptions

Name	Thrown on
`Allocation`	failure

Parameters

Name	Description
n	The capacity in characters, excluding any null terminator.

Set the scheme

Synopsis

Declared in <include/boost/url/url_base.hpp>


url_base&
set_scheme(core::string_view s);

Description

The scheme is set to the specified string, which must contain a valid scheme without any trailing colon (':'). Note that schemes are case-insensitive, and the canonical form is lowercased.


assert( url( "http://www.example.com" ).set_scheme( "https" ).scheme_id() == scheme::https );

Linear in `this->size() + s.size()`.

Strong guarantee.

Calls to allocate may throw. Exceptions thrown on invalid input.


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

3.1. Scheme (rfc3986)

Exceptions

Name	Thrown on
`s`	contains an invalid scheme.

Parameters

Name	Description
s	The scheme to set.

Synopsis

Declared in <include/boost/url/url_base.hpp>


url_base&
set_scheme_id(urls::scheme id);

Description

This function sets the scheme to the specified known urls::scheme id, which may not be scheme::unknown or else an exception is thrown. If the id is scheme::none , this function behaves as if remove_scheme were called.


assert( url( "http://example.com/echo.cgi" ).set_scheme_id( scheme::wss ).buffer() == "wss://example.com/echo.cgi" );

Linear in `this->size()`.

Strong guarantee.

Calls to allocate may throw. Exceptions thrown on invalid input.

3.1. Scheme (rfc3986)

Exceptions

Name	Thrown on
`The`	scheme is invalid.

Parameters

Name	Description
id	The scheme to set.

Remove the scheme

Synopsis

Declared in <include/boost/url/url_base.hpp>


url_base&
remove_scheme();

Description

This function removes the scheme if it is present.


assert( url("http://www.example.com/index.htm" ).remove_scheme().buffer() == "//www.example.com/index.htm" );


this->has_scheme() == false && this->scheme_id() == scheme::none

Linear in `this->size()`.

Throws nothing.


URI           = scheme ":" hier-part [ "?" query ] [ "#" fragment ]

3.1. Scheme (rfc3986)

Synopsis

Declared in <include/boost/url/url_base.hpp>


url_base&
set_encoded_authority(pct_string_view s);

Description

This function sets the authority to the specified string. The string may contain percent-escapes.


assert( url().set_encoded_authority( "My%20Computer" ).has_authority() );

Strong guarantee.

Calls to allocate may throw. Exceptions thrown on invalid input.


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

userinfo      = *( unreserved / pct-encoded / sub-delims / ":" )
host          = IP-literal / IPv4address / reg-name
port          = *DIGIT

3.2. Authority (rfc3986)

Exceptions

Name	Thrown on
`The`	string contains an invalid percent-encoding.

Parameters

Name	Description
s	The authority string to set.

Synopsis

Declared in <include/boost/url/url_base.hpp>


url_base&
remove_authority();

Description

This function removes the authority, which includes the userinfo, host, and a port if present.


assert( url( "http://example.com/echo.cgi" ).remove_authority().buffer() == "http:/echo.cgi" );


this->has_authority() == false && this->has_userinfo() == false && this->has_port() == false

Linear in `this->size()`.

Throws nothing.


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

userinfo      = *( unreserved / pct-encoded / sub-delims / ":" )
host          = IP-literal / IPv4address / reg-name
port          = *DIGIT

3.2. Authority (rfc3986)

Synopsis

Declared in <include/boost/url/url_base.hpp>


url_base&
set_userinfo(core::string_view s);

Description

The userinfo is set to the given string, which may contain percent-escapes. Any special or reserved characters in the string are automatically percent-encoded. The effects on the user and password depend on the presence of a colon (':') in the string:

If an unescaped colon exists, the characters up to the colon become the user and the rest of the characters after the colon become the password. In this case has_password returns true. Otherwise,

If there is no colon, the user is set to the string. The function has_password returns false.

NOTE

The interpretation of the userinfo as individual user and password components is scheme-dependent. Transmitting passwords in URLs is deprecated.


assert( url( "http://example.com" ).set_userinfo( "user:pass" ).encoded_user() == "user" );

Linear in `this->size() + s.size()`.

Strong guarantee.

Calls to allocate may throw.


userinfo      = [ [ user ] [ ':' password ] ]

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

3.2.1. User Information (rfc3986)

Parameters

Name	Description
s	The string to set.

Synopsis

Declared in <include/boost/url/url_base.hpp>


url_base&
set_encoded_userinfo(pct_string_view s);

Description

The userinfo is set to the given string, which may contain percent-escapes. Escapes in the string are preserved, and reserved characters in the string are percent-escaped in the result. The effects on the user and password depend on the presence of a colon (':') in the string:

If an unescaped colon exists, the characters up to the colon become the user and the rest of the characters after the colon become the password. In this case has_password returns true. Otherwise,

If there is no colon, the user is set to the string. The function has_password returns false.

NOTE

The interpretation of the userinfo as individual user and password components is scheme-dependent. Transmitting passwords in URLs is deprecated.


assert( url( "http://example.com" ).set_encoded_userinfo( "john%20doe" ).user() == "john doe" );

Linear in `this->size() + s.size()`.

Strong guarantee.

Calls to allocate may throw. Exceptions thrown on invalid input.


userinfo      = [ [ user ] [ ':' password ] ]

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

3.2.1. User Information (rfc3986)

Exceptions

Name	Thrown on
`s`	contains an invalid percent-encoding.

Parameters

Name	Description
s	The string to set.

Synopsis

Declared in <include/boost/url/url_base.hpp>


url_base&
remove_userinfo() noexcept;

Description

This function removes the userinfo if present, without removing any authority.


assert( url( "http://user@example.com" ).remove_userinfo().has_userinfo() == false );


this->has_userinfo() == false && this->encoded_userinfo().empty == true

Linear in `this->size()`.

Throws nothing.


userinfo      = [ [ user ] [ ':' password ] ]

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

3.2.1. User Information (rfc3986)

Synopsis

Declared in <include/boost/url/url_base.hpp>


url_base&
set_user(core::string_view s);

Description

This function sets the user part of the userinfo to the string. Any special or reserved characters in the string are automatically percent-encoded.


assert( url().set_user("john doe").encoded_userinfo() == "john%20doe" );


this->has_authority() == true && this->has_userinfo() == true

Linear in `this->size() + s.size()`.

Strong guarantee.

Calls to allocate may throw.


userinfo      = [ [ user ] [ ':' password ] ]

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

3.2.1. User Information (rfc3986)

Parameters

Name	Description
s	The string to set.

Synopsis

Declared in <include/boost/url/url_base.hpp>


url_base&
set_encoded_user(pct_string_view s);

Description

This function sets the user part of the userinfo the the string, which may contain percent-escapes. Escapes in the string are preserved, and reserved characters in the string are percent-escaped in the result.


assert( url().set_encoded_user("john%20doe").userinfo() == "john doe" );


this->has_authority() == true && this->has_userinfo() == true

Linear in `this->size() + s.size()`.

Strong guarantee.

Calls to allocate may throw.


userinfo      = [ [ user ] [ ':' password ] ]

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

3.2.1. User Information (rfc3986)

Exceptions

Name	Thrown on
`s`	contains an invalid percent-encoding.

Parameters

Name	Description
s	The string to set.

Synopsis

Declared in <include/boost/url/url_base.hpp>


url_base&
set_password(core::string_view s);

Description

This function sets the password in the userinfo to the string. Reserved characters in the string are percent-escaped in the result.

NOTE

The interpretation of the userinfo as individual user and password components is scheme-dependent. Transmitting passwords in URLs is deprecated.


assert( url("http://user@example.com").set_password( "pass" ).encoded_userinfo() == "user:pass" );


this->has_password() == true && this->password() == s

Strong guarantee.

Calls to allocate may throw.


userinfo      = [ [ user ] [ ':' password ] ]

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

3.2.1. User Information (rfc3986)

Parameters

Name	Description
s	The string to set. This string may contain any characters, including nulls.

Synopsis

Declared in <include/boost/url/url_base.hpp>


url_base&
set_encoded_password(pct_string_view s);

Description

This function sets the password in the userinfo to the string, which may contain percent-escapes. Escapes in the string are preserved, and reserved characters in the string are percent-escaped in the result.

NOTE

The interpretation of the userinfo as individual user and password components is scheme-dependent. Transmitting passwords in URLs is deprecated.


assert( url("http://user@example.com").set_encoded_password( "pass" ).encoded_userinfo() == "user:pass" );


this->has_password() == true

Strong guarantee.

Calls to allocate may throw.


userinfo      = [ [ user ] [ ':' password ] ]

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

3.2.1. User Information (rfc3986)

Exceptions

Name	Thrown on
`s`	contains an invalid percent-encoding.

Parameters

Name	Description
s	The string to set. This string may contain any characters, including nulls.

Synopsis

Declared in <include/boost/url/url_base.hpp>


url_base&
remove_password() noexcept;

Description

This function removes the password from the userinfo if a password exists. If there is no userinfo or no authority, the call has no effect.

NOTE

The interpretation of the userinfo as individual user and password components is scheme-dependent. Transmitting passwords in URLs is deprecated.


assert( url( "http://user:pass@example.com" ).remove_password().authority().buffer() == "user@example.com" );


this->has_password() == false && this->encoded_password().empty() == true

Linear in `this->size()`.

Throws nothing.


userinfo      = [ [ user ] [ ':' password ] ]

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

3.2.1. User Information (rfc3986)

Synopsis

Declared in <include/boost/url/url_base.hpp>


url_base&
set_host(core::string_view s);

Description

Depending on the contents of the passed string, this function sets the host:

If the string is a valid IPv4 address, then the host is set to the address. The host type is host_type::ipv4 .

If the string is a valid IPv6 address enclosed in square brackets, then the host is set to that address. The host type is host_type::ipv6 .

If the string is a valid IPvFuture address enclosed in square brackets, then the host is set to that address. The host type is host_type::ipvfuture .

Otherwise, the host name is set to the string, which may be empty. Reserved characters in the string are percent-escaped in the result. The host type is host_type::name .

In all cases, when this function returns, the URL contains an authority.


assert( url( "http://www.example.com" ).set_host( "127.0.0.1" ).buffer() == "http://127.0.0.1" );


this->has_authority() == true

Linear in `this->size() + s.size()`.

Strong guarantee.

Calls to allocate may throw.


host        = IP-literal / IPv4address / reg-name

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

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

IPv4 (Wikipedia)

IP Version 6 Addressing Architecture (rfc4291)

3.2.2. Host (rfc3986)

Parameters

Name	Description
s	The string to set.

Synopsis

Declared in <include/boost/url/url_base.hpp>


url_base&
set_encoded_host(pct_string_view s);

Description

Depending on the contents of the passed string, this function sets the host:

If the string is a valid IPv4 address, then the host is set to the address. The host type is host_type::ipv4 .

If the string is a valid IPv6 address enclosed in square brackets, then the host is set to that address. The host type is host_type::ipv6 .

If the string is a valid IPvFuture address enclosed in square brackets, then the host is set to that address. The host type is host_type::ipvfuture .

Otherwise, the host name is set to the string. This string can contain percent escapes, or can be empty. Escapes in the string are preserved, and reserved characters in the string are percent-escaped in the result. The host type is host_type::name .

In all cases, when this function returns, the URL contains an authority.


assert( url( "http://www.example.com" ).set_host( "127.0.0.1" ).buffer() == "http://127.0.0.1" );


this->has_authority() == true

Linear in `this->size() + s.size()`.

Strong guarantee.

Calls to allocate may throw. Exceptions thrown on invalid input.


host        = IP-literal / IPv4address / reg-name

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

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

IPv4 (Wikipedia)

IP Version 6 Addressing Architecture (rfc4291)

3.2.2. Host (rfc3986)

Exceptions

Name	Thrown on
`s`	contains an invalid percent-encoding.

Parameters

Name	Description
s	The string to set.

Synopsis

Declared in <include/boost/url/url_base.hpp>


url_base&
set_host_address(core::string_view s);

Description

Depending on the contents of the passed string, this function sets the host:

If the string is a valid IPv4 address, then the host is set to the address. The host type is host_type::ipv4 .

If the string is a valid IPv6 address, then the host is set to that address. The host type is host_type::ipv6 .

If the string is a valid IPvFuture, then the host is set to that address. The host type is host_type::ipvfuture .

Otherwise, the host name is set to the string, which may be empty. Reserved characters in the string are percent-escaped in the result. The host type is host_type::name .

In all cases, when this function returns, the URL contains an authority.


assert( url( "http://www.example.com" ).set_host_address( "127.0.0.1" ).buffer() == "http://127.0.0.1" );


this->has_authority() == true

Linear in `s.size()`.

Strong guarantee.

Calls to allocate may throw.


IPv4address = dec-octet "." dec-octet "." dec-octet "." dec-octet

dec-octet   = DIGIT                 ; 0-9
            / %x31-39 DIGIT         ; 10-99
            / "1" 2DIGIT            ; 100-199
            / "2" %x30-34 DIGIT     ; 200-249
            / "25" %x30-35          ; 250-255

IPv6address =                            6( h16 ":" ) ls32
            /                       "::" 5( h16 ":" ) ls32
            / [               h16 ] "::" 4( h16 ":" ) ls32
            / [ *1( h16 ":" ) h16 ] "::" 3( h16 ":" ) ls32
            / [ *2( h16 ":" ) h16 ] "::" 2( h16 ":" ) ls32
            / [ *3( h16 ":" ) h16 ] "::"    h16 ":"   ls32
            / [ *4( h16 ":" ) h16 ] "::"              ls32
            / [ *5( h16 ":" ) h16 ] "::"              h16
            / [ *6( h16 ":" ) h16 ] "::"

ls32        = ( h16 ":" h16 ) / IPv4address
            ; least-significant 32 bits of address

h16         = 1*4HEXDIG
            ; 16 bits of address represented in hexadecimal

IPvFuture     = "v" 1*HEXDIG "." 1*( unreserved / sub-delims / ":" )

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

IPv4 (Wikipedia)

IP Version 6 Addressing Architecture (rfc4291)

3.2.2. Host (rfc3986)

Parameters

Name	Description
s	The string to set.

Synopsis

Declared in <include/boost/url/url_base.hpp>


url_base&
set_encoded_host_address(pct_string_view s);

Description

Depending on the contents of the passed string, this function sets the host:

If the string is a valid IPv4 address, then the host is set to the address. The host type is host_type::ipv4 .

If the string is a valid IPv6 address, then the host is set to that address. The host type is host_type::ipv6 .

If the string is a valid IPvFuture, then the host is set to that address. The host type is host_type::ipvfuture .

In all cases, when this function returns, the URL contains an authority.


assert( url( "http://www.example.com" ).set_host( "127.0.0.1" ).buffer() == "http://127.0.0.1" );


this->has_authority() == true

Linear in `this->size() + s.size()`.

Strong guarantee.

Calls to allocate may throw. Exceptions thrown on invalid input.


IPv4address = dec-octet "." dec-octet "." dec-octet "." dec-octet

dec-octet   = DIGIT                 ; 0-9
            / %x31-39 DIGIT         ; 10-99
            / "1" 2DIGIT            ; 100-199
            / "2" %x30-34 DIGIT     ; 200-249
            / "25" %x30-35          ; 250-255

IPv6address =                            6( h16 ":" ) ls32
            /                       "::" 5( h16 ":" ) ls32
            / [               h16 ] "::" 4( h16 ":" ) ls32
            / [ *1( h16 ":" ) h16 ] "::" 3( h16 ":" ) ls32
            / [ *2( h16 ":" ) h16 ] "::" 2( h16 ":" ) ls32
            / [ *3( h16 ":" ) h16 ] "::"    h16 ":"   ls32
            / [ *4( h16 ":" ) h16 ] "::"              ls32
            / [ *5( h16 ":" ) h16 ] "::"              h16
            / [ *6( h16 ":" ) h16 ] "::"

ls32        = ( h16 ":" h16 ) / IPv4address
            ; least-significant 32 bits of address

h16         = 1*4HEXDIG
            ; 16 bits of address represented in hexadecimal

IPvFuture     = "v" 1*HEXDIG "." 1*( unreserved / sub-delims / ":" )

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

IPv4 (Wikipedia)

IP Version 6 Addressing Architecture (rfc4291)

3.2.2. Host (rfc3986)

Exceptions

Name	Thrown on
`s`	contains an invalid percent-encoding.

Parameters

Name	Description
s	The string to set.

Synopsis

Declared in <include/boost/url/url_base.hpp>


url_base&
set_host_ipv4(ipv4_address const& addr);

Description

The host is set to the specified IPv4 address. The host type is host_type::ipv4 .


assert( url("http://www.example.com").set_host_ipv4( ipv4_address( "127.0.0.1" ) ).buffer() == "http://127.0.0.1" );

Linear in `this->size()`.


this->has_authority() == true && this->host_ipv4_address() == addr && this->host_type() == host_type::ipv4

Strong guarantee.

Calls to allocate may throw.


IPv4address = dec-octet "." dec-octet "." dec-octet "." dec-octet

dec-octet   = DIGIT                 ; 0-9
            / %x31-39 DIGIT         ; 10-99
            / "1" 2DIGIT            ; 100-199
            / "2" %x30-34 DIGIT     ; 200-249
            / "25" %x30-35          ; 250-255

IPv4 (Wikipedia)

3.2.2. Host (rfc3986)

Parameters

Name	Description
addr	The address to set.

Synopsis

Declared in <include/boost/url/url_base.hpp>


url_base&
set_host_ipv6(ipv6_address const& addr);

Description

The host is set to the specified IPv6 address. The host type is host_type::ipv6 .


assert( url().set_host_ipv6( ipv6_address( "1::6:c0a8:1" ) ).authority().buffer() == "[1::6:c0a8:1]" );


this->has_authority() == true && this->host_ipv6_address() == addr && this->host_type() == host_type::ipv6

Linear in `this->size()`.

Strong guarantee.

Calls to allocate may throw.


IPv6address =                            6( h16 ":" ) ls32
            /                       "::" 5( h16 ":" ) ls32
            / [               h16 ] "::" 4( h16 ":" ) ls32
            / [ *1( h16 ":" ) h16 ] "::" 3( h16 ":" ) ls32
            / [ *2( h16 ":" ) h16 ] "::" 2( h16 ":" ) ls32
            / [ *3( h16 ":" ) h16 ] "::"    h16 ":"   ls32
            / [ *4( h16 ":" ) h16 ] "::"              ls32
            / [ *5( h16 ":" ) h16 ] "::"              h16
            / [ *6( h16 ":" ) h16 ] "::"

ls32        = ( h16 ":" h16 ) / IPv4address
            ; least-significant 32 bits of address

h16         = 1*4HEXDIG
            ; 16 bits of address represented in hexadecimal

IP Version 6 Addressing Architecture (rfc4291)

3.2.2. Host (rfc3986)

Parameters

Name	Description
addr	The address to set.

Synopsis

Declared in <include/boost/url/url_base.hpp>


url_base&
set_host_ipvfuture(core::string_view s);

Description

The host is set to the specified IPvFuture string. The host type is host_type::ipvfuture .


assert( url().set_host_ipvfuture( "v42.bis" ).buffer() == "//[v42.bis]" );

Linear in `this->size() + s.size()`.


this->has_authority() == true && this->host_ipvfuture) == s && this->host_type() == host_type::ipvfuture

Strong guarantee.

Calls to allocate may throw. Exceptions thrown on invalid input.


IPvFuture     = "v" 1*HEXDIG "." 1*( unreserved / sub-delims / ":" )

3.2.2. Host (rfc3986)

Exceptions

Name	Thrown on
`s`	contains an invalid percent-encoding.

Parameters

Name	Description
s	The string to set.

Synopsis

Declared in <include/boost/url/url_base.hpp>


url_base&
set_host_name(core::string_view s);

Description

The host is set to the specified string, which may be empty. Reserved characters in the string are percent-escaped in the result. The host type is host_type::name .


assert( url( "http://www.example.com/index.htm").set_host_name( "localhost" ).host_address() == "localhost" );


this->has_authority() == true && this->host_ipv6_address() == addr && this->host_type() == host_type::name

Strong guarantee.

Calls to allocate may throw.


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

3.2.2. Host (rfc3986)

Parameters

Name	Description
s	The string to set.

Synopsis

Declared in <include/boost/url/url_base.hpp>


url_base&
set_encoded_host_name(pct_string_view s);

Description

The host is set to the specified string, which may contain percent-escapes and can be empty. Escapes in the string are preserved, and reserved characters in the string are percent-escaped in the result. The host type is host_type::name .


assert( url( "http://www.example.com/index.htm").set_encoded_host_name( "localhost" ).host_address() == "localhost" );


this->has_authority() == true && this->host_ipv6_address() == addr && this->host_type() == host_type::name

Strong guarantee.

Calls to allocate may throw. Exceptions thrown on invalid input.


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

3.2.2. Host (rfc3986)

Exceptions

Name	Thrown on
`s`	contains an invalid percent-encoding.

Parameters

Name	Description
s	The string to set.

Synopsis

Declared in <include/boost/url/url_base.hpp>


url_base&
set_port_number(std::uint16_t n);

Description

The port is set to the specified integer.


assert( url( "http://www.example.com" ).set_port_number( 8080 ).authority().buffer() == "www.example.com:8080" );


this->has_authority() == true && this->has_port() == true && this->port_number() == n

Linear in `this->size()`.

Strong guarantee.

Calls to allocate may throw.


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

port          = *DIGIT

3.2.3. Port (rfc3986)

Parameters

Name	Description
n	The port number to set.

Synopsis

Declared in <include/boost/url/url_base.hpp>


url_base&
set_port(core::string_view s);

Description

This port is set to the string, which must contain only digits or be empty. An empty port string is distinct from having no port.


assert( url( "http://www.example.com" ).set_port( "8080" ).authority().buffer() == "www.example.com:8080" );


this->has_port() == true && this->port_number() == n && this->port() == std::to_string(n)

Strong guarantee.

Calls to allocate may throw. Exceptions thrown on invalid input.


port          = *DIGIT

3.2.3. Port (rfc3986)

Exceptions

Name	Thrown on
`s`	does not contain a valid port.

Parameters

Name	Description
s	The port string to set.

Synopsis

Declared in <include/boost/url/url_base.hpp>


url_base&
remove_port() noexcept;

Description

If a port exists, it is removed. The rest of the authority is unchanged.


assert( url( "http://www.example.com:80" ).remove_port().authority().buffer() == "www.example.com" );


this->has_port() == false && this->port_number() == 0 && this->port() == ""

Linear in `this->size()`.

Throws nothing.


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

port          = *DIGIT

3.2.3. Port (rfc3986)

Synopsis

Declared in <include/boost/url/url_base.hpp>


bool
set_path_absolute(bool absolute);

Description

This function adjusts the path to make it absolute or not, depending on the parameter.

NOTE

If an authority is present, the path is always absolute. In this case, the function has no effect.


url u( "path/to/file.txt" );
assert( u.set_path_absolute( true ) );
assert( u.buffer() == "/path/to/file.txt" );


this->is_path_absolute() == true && this->encoded_path().front() == '/'

Linear in `this->size()`.


path          = path-abempty    ; begins with "/" or is empty
              / path-absolute   ; begins with "/" but not "//"
              / path-noscheme   ; begins with a non-colon segment
              / path-rootless   ; begins with a segment
              / path-empty      ; zero characters

path-abempty  = *( "/" segment )
path-absolute = "/" [ segment-nz *( "/" segment ) ]
path-noscheme = segment-nz-nc *( "/" segment )
path-rootless = segment-nz *( "/" segment )
path-empty    = 0

3.3. Path (rfc3986)

Return Value

true on success.

Synopsis

Declared in <include/boost/url/url_base.hpp>


url_base&
set_path(core::string_view s);

Description

This function sets the path to the string, which may be empty. Reserved characters in the string are percent-escaped in the result.

NOTE

The library may adjust the final result to ensure that no other parts of the url is semantically affected.

NOTE

This function does not encode '/' chars, which are unreserved for paths but reserved for path segments. If a path segment should include encoded '/'s to differentiate it from path separators, the functions set_encoded_path or segments should be used instead.


url u( "http://www.example.com" );

u.set_path( "path/to/file.txt" );

assert( u.path() == "/path/to/file.txt" );

Linear in `this->size() + s.size()`.

Strong guarantee.

Calls to allocate may throw.


path          = path-abempty    ; begins with "/" or is empty
              / path-absolute   ; begins with "/" but not "//"
              / path-noscheme   ; begins with a non-colon segment
              / path-rootless   ; begins with a segment
              / path-empty      ; zero characters

path-abempty  = *( "/" segment )
path-absolute = "/" [ segment-nz *( "/" segment ) ]
path-noscheme = segment-nz-nc *( "/" segment )
path-rootless = segment-nz *( "/" segment )
path-empty    = 0

3.3. Path (rfc3986)

Parameters

Name	Description
s	The string to set.

Synopsis

Declared in <include/boost/url/url_base.hpp>


url_base&
set_encoded_path(pct_string_view s);

Description

This function sets the path to the string, which may contain percent-escapes and can be empty. Escapes in the string are preserved, and reserved characters in the string are percent-escaped in the result.

NOTE

The library may adjust the final result to ensure that no other parts of the url is semantically affected.


url u( "http://www.example.com" );

u.set_encoded_path( "path/to/file.txt" );

assert( u.encoded_path() == "/path/to/file.txt" );

Linear in `this->size() + s.size()`.

Strong guarantee.

Calls to allocate may throw. Exceptions thrown on invalid input.


path          = path-abempty    ; begins with "/" or is empty
              / path-absolute   ; begins with "/" but not "//"
              / path-noscheme   ; begins with a non-colon segment
              / path-rootless   ; begins with a segment
              / path-empty      ; zero characters

path-abempty  = *( "/" segment )
path-absolute = "/" [ segment-nz *( "/" segment ) ]
path-noscheme = segment-nz-nc *( "/" segment )
path-rootless = segment-nz *( "/" segment )
path-empty    = 0

3.3. Path (rfc3986)

Exceptions

Name	Thrown on
`s`	contains an invalid percent-encoding.

Parameters

Name	Description
s	The string to set.

Synopsis

Declared in <include/boost/url/url_base.hpp>


urls::segments_ref
segments() noexcept;

» more...


segments_view
segments() const noexcept;

» more...

Description

This function returns a bidirectional view of segments over the path. The returned view references the same underlying character buffer; ownership is not transferred. Any percent-escapes in strings returned when iterating the view are decoded first. The container is modifiable; changes to the container are reflected in the underlying URL.


url u( "http://example.com/path/to/file.txt" );

segments sv = u.segments();

Constant.

Throws nothing.


path          = path-abempty    ; begins with "/" or is empty
              / path-absolute   ; begins with "/" but not "//"
              / path-noscheme   ; begins with a non-colon segment
              / path-rootless   ; begins with a segment
              / path-empty      ; zero characters

path-abempty  = *( "/" segment )
path-absolute = "/" [ segment-nz *( "/" segment ) ]
path-noscheme = segment-nz-nc *( "/" segment )
path-rootless = segment-nz *( "/" segment )
path-empty    = 0

3.3. Path (rfc3986)

Synopsis

Declared in <include/boost/url/url_base.hpp>


urls::segments_ref
segments() noexcept;

Description


url u( "http://example.com/path/to/file.txt" );

segments sv = u.segments();

Constant.

Throws nothing.


path          = path-abempty    ; begins with "/" or is empty
              / path-absolute   ; begins with "/" but not "//"
              / path-noscheme   ; begins with a non-colon segment
              / path-rootless   ; begins with a segment
              / path-empty      ; zero characters

path-abempty  = *( "/" segment )
path-absolute = "/" [ segment-nz *( "/" segment ) ]
path-noscheme = segment-nz-nc *( "/" segment )
path-rootless = segment-nz *( "/" segment )
path-empty    = 0

3.3. Path (rfc3986)

Synopsis

Declared in <include/boost/url/url_base.hpp>


segments_view
segments() const noexcept;

Description

This function returns a bidirectional view of strings over the path. The returned view references the same underlying character buffer; ownership is not transferred. Any percent-escapes in strings returned when iterating the view are decoded first.


segments_view sv = url_view( "/path/to/file.txt" ).segments();

Constant.

Throws nothing.


path          = [ "/" ] segment *( "/" segment )

3.3. Path (rfc3986)

Synopsis

Declared in <include/boost/url/url_base.hpp>


segments_encoded_ref
encoded_segments() noexcept;

» more...


segments_encoded_view
encoded_segments() const noexcept;

» more...

Description

This function returns a bidirectional view of segments over the path. The returned view references the same underlying character buffer; ownership is not transferred. Strings returned when iterating the range may contain percent escapes. The container is modifiable; changes to the container are reflected in the underlying URL.


url u( "http://example.com/path/to/file.txt" );

segments_encoded_ref sv = u.encoded_segments();

Constant.

Throws nothing.


path          = path-abempty    ; begins with "/" or is empty
              / path-absolute   ; begins with "/" but not "//"
              / path-noscheme   ; begins with a non-colon segment
              / path-rootless   ; begins with a segment
              / path-empty      ; zero characters

path-abempty  = *( "/" segment )
path-absolute = "/" [ segment-nz *( "/" segment ) ]
path-noscheme = segment-nz-nc *( "/" segment )
path-rootless = segment-nz *( "/" segment )
path-empty    = 0

3.3. Path (rfc3986)

Synopsis

Declared in <include/boost/url/url_base.hpp>


segments_encoded_ref
encoded_segments() noexcept;

Description


url u( "http://example.com/path/to/file.txt" );

segments_encoded_ref sv = u.encoded_segments();

Constant.

Throws nothing.


path          = path-abempty    ; begins with "/" or is empty
              / path-absolute   ; begins with "/" but not "//"
              / path-noscheme   ; begins with a non-colon segment
              / path-rootless   ; begins with a segment
              / path-empty      ; zero characters

path-abempty  = *( "/" segment )
path-absolute = "/" [ segment-nz *( "/" segment ) ]
path-noscheme = segment-nz-nc *( "/" segment )
path-rootless = segment-nz *( "/" segment )
path-empty    = 0

3.3. Path (rfc3986)

Synopsis

Declared in <include/boost/url/url_base.hpp>


segments_encoded_view
encoded_segments() const noexcept;

Description

This function returns a bidirectional view of strings over the path. The returned view references the same underlying character buffer; ownership is not transferred. Strings returned when iterating the range may contain percent escapes.


segments_encoded_view sv = url_view( "/path/to/file.txt" ).encoded_segments();

Constant.

Throws nothing.


path          = path-abempty    ; begins with "/" or is empty
              / path-absolute   ; begins with "/" but not "//"
              / path-noscheme   ; begins with a non-colon segment
              / path-rootless   ; begins with a segment
              / path-empty      ; zero characters

path-abempty  = *( "/" segment )
path-absolute = "/" [ segment-nz *( "/" segment ) ]
path-noscheme = segment-nz-nc *( "/" segment )
path-rootless = segment-nz *( "/" segment )
path-empty    = 0

3.3. Path (rfc3986)

Synopsis

Declared in <include/boost/url/url_base.hpp>


url_base&
set_query(core::string_view s);

Description

This sets the query to the string, which can be empty. An empty query is distinct from having no query. Reserved characters in the string are percent-escaped in the result.


assert( url( "http://example.com" ).set_query( "id=42" ).query() == "id=42" );


this->has_query() == true && this->query() == s

Strong guarantee.

Calls to allocate may throw.


query           = *( pchar / "/" / "?" )

query-param     = key [ "=" value ]
query-params    = [ query-param ] *( "&" query-param )

3.4. Query (rfc3986)

Query string (Wikipedia)

Parameters

Name	Description
s	The string to set.

Synopsis

Declared in <include/boost/url/url_base.hpp>


url_base&
set_encoded_query(pct_string_view s);

Description

This sets the query to the string, which may contain percent-escapes and can be empty. An empty query is distinct from having no query. Escapes in the string are preserved, and reserved characters in the string are percent-escaped in the result.


assert( url( "http://example.com" ).set_encoded_query( "id=42" ).encoded_query() == "id=42" );


this->has_query() == true && this->query() == decode_view( s );

Strong guarantee.

Calls to allocate may throw. Exceptions thrown on invalid input.


query           = *( pchar / "/" / "?" )

query-param     = key [ "=" value ]
query-params    = [ query-param ] *( "&" query-param )

3.4. Query (rfc3986)

Query string (Wikipedia)

Exceptions

Name	Thrown on
`s`	contains an invalid percent-encoding.

Parameters

Name	Description
s	The string to set.

Synopsis

Declared in <include/boost/url/url_base.hpp>


params_ref
params() noexcept;

» more...


params_view
params() const noexcept;

» more...


params_ref
params(encoding_opts opt) noexcept;

» more...

Description

This function returns a bidirectional view of key/value pairs over the query. The returned view references the same underlying character buffer; ownership is not transferred. Any percent-escapes in strings returned when iterating the view are decoded first. The container is modifiable; changes to the container are reflected in the underlying URL.


params_ref pv = url( "/sql?id=42&name=jane%2Ddoe&page+size=20" ).params();

Constant.

Throws nothing.


query           = *( pchar / "/" / "?" )

query-param     = key [ "=" value ]
query-params    = [ query-param ] *( "&" query-param )

3.4. Query (rfc3986)

Query string (Wikipedia)

Parameters

Name	Description
opt	The options for decoding. If this parameter is omitted, the `space_as_plus` is used.

Synopsis

Declared in <include/boost/url/url_base.hpp>


params_ref
params() noexcept;

Description


params_ref pv = url( "/sql?id=42&name=jane%2Ddoe&page+size=20" ).params();

Constant.

Throws nothing.


query           = *( pchar / "/" / "?" )

query-param     = key [ "=" value ]
query-params    = [ query-param ] *( "&" query-param )

3.4. Query (rfc3986)

Query string (Wikipedia)

Synopsis

Declared in <include/boost/url/url_base.hpp>


params_view
params() const noexcept;

Return the query as a container of parameters

Synopsis

Declared in <include/boost/url/url_base.hpp>


params_ref
params(encoding_opts opt) noexcept;

Description


encoding_opts opt;
opt.space_as_plus = true;
params_ref pv = url( "/sql?id=42&name=jane+doe&page+size=20" ).params(opt);

Constant.

Throws nothing.


query           = *( pchar / "/" / "?" )

query-param     = key [ "=" value ]
query-params    = [ query-param ] *( "&" query-param )

3.4. Query (rfc3986)

Query string (Wikipedia)

Parameters

Name	Description
opt	The options for decoding. If this parameter is omitted, the `space_as_plus` is used.

Synopsis

Declared in <include/boost/url/url_base.hpp>


params_encoded_view
encoded_params() const noexcept;

» more...


params_encoded_ref
encoded_params() noexcept;

» more...

Description

This function returns a bidirectional view of key/value pairs over the query. The returned view references the same underlying character buffer; ownership is not transferred. Strings returned when iterating the range may contain percent escapes.


params_encoded_view pv = url_view( "/sql?id=42&name=jane%2Ddoe&page+size=20" ).encoded_params();

Constant.

Throws nothing.

3.4. Query (rfc3986)


query           = *( pchar / "/" / "?" )

query-param     = key [ "=" value ]
query-params    = [ query-param ] *( "&" query-param )

://en.wikipedia.org/wiki/Query_string" >Query string (Wikipedia)

Synopsis

Declared in <include/boost/url/url_base.hpp>


params_encoded_view
encoded_params() const noexcept;

Description

This function returns a bidirectional view of key/value pairs over the query. The returned view references the same underlying character buffer; ownership is not transferred. Strings returned when iterating the range may contain percent escapes.


params_encoded_view pv = url_view( "/sql?id=42&name=jane%2Ddoe&page+size=20" ).encoded_params();

Constant.

Throws nothing.

3.4. Query (rfc3986)


query           = *( pchar / "/" / "?" )

query-param     = key [ "=" value ]
query-params    = [ query-param ] *( "&" query-param )

://en.wikipedia.org/wiki/Query_string" >Query string (Wikipedia)

Synopsis

Declared in <include/boost/url/url_base.hpp>


params_encoded_ref
encoded_params() noexcept;

Description

This function returns a bidirectional view of key/value pairs over the query. The returned view references the same underlying character buffer; ownership is not transferred. Strings returned when iterating the range may contain percent escapes. The container is modifiable; changes to the container are reflected in the underlying URL.


params_encoded_ref pv = url( "/sql?id=42&name=jane%2Ddoe&page+size=20" ).encoded_params();

Constant.

Throws nothing.


query           = *( pchar / "/" / "?" )

query-param     = key [ "=" value ]
query-params    = [ query-param ] *( "&" query-param )

3.4. Query (rfc3986)

Query string (Wikipedia)

Synopsis

Declared in <include/boost/url/url_base.hpp>


url_base&
set_params(
    std::initializer_list<param_view> ps,
    encoding_opts opts = = {}) noexcept;

Description

This sets the query params to the list of param_view, which can be empty.

An empty list of params is distinct from having no params.

Reserved characters in the string are percent-escaped in the result.


assert( url( "http://example.com" ).set_params( {"id", "42"} ).query() == "id=42" );


this->has_query() == true

Strong guarantee.

Calls to allocate may throw.

Linear.


query           = *( pchar / "/" / "?" )

query-param     = key [ "=" value ]
query-params    = [ query-param ] *( "&" query-param )

://en.wikipedia.org/wiki/Query_string" >Query string (Wikipedia)

Parameters

Name	Description
ps	The params to set.
opts	The options for encoding.

Synopsis

Declared in <include/boost/url/url_base.hpp>


url_base&
set_encoded_params(std::initializer_list<param_pct_view> ps) noexcept;

Description

This sets the query params to the elements in the list, which may contain percent-escapes and can be empty.

An empty list of params is distinct from having no query.

Escapes in the string are preserved, and reserved characters in the string are percent-escaped in the result.


assert( url( "http://example.com" ).set_encoded_params( {"id", "42"} ).encoded_query() == "id=42" );


this->has_query() == true

Linear.

Strong guarantee.

Calls to allocate may throw. Exceptions thrown on invalid input.


query           = *( pchar / "/" / "?" )

query-param     = key [ "=" value ]
query-params    = [ query-param ] *( "&" query-param )

3.4. Query (rfc3986)

Query string (Wikipedia)

Exceptions

Name	Thrown on
`some`	element in `ps` contains an invalid percent-encoding.

Parameters

Name	Description
ps	The params to set.

Synopsis

Declared in <include/boost/url/url_base.hpp>


url_base&
remove_query() noexcept;

Description

If a query is present, it is removed. An empty query is distinct from having no query.


assert( url( "http://www.example.com?id=42" ).remove_query().buffer() == "http://www.example.com" );


this->has_query() == false && this->params().empty()

Throws nothing.


query           = *( pchar / "/" / "?" )

query-param     = key [ "=" value ]
query-params    = [ query-param ] *( "&" query-param )

3.4. Query (rfc3986)

Query string (Wikipedia)

Synopsis

Declared in <include/boost/url/url_base.hpp>


url_base&
remove_fragment() noexcept;

Description

This function removes the fragment. An empty fragment is distinct from having no fragment.


assert( url( "?first=john&last=doe#anchor" ).remove_fragment().buffer() == "?first=john&last=doe" );


this->has_fragment() == false && this->encoded_fragment() == ""

Constant.

Throws nothing.


fragment    = *( pchar / "/" / "?" )

3.5. Fragment

Synopsis

Declared in <include/boost/url/url_base.hpp>


url_base&
set_fragment(core::string_view s);

Description

This function sets the fragment to the specified string, which may be empty. An empty fragment is distinct from having no fragment. Reserved characters in the string are percent-escaped in the result.


assert( url("?first=john&last=doe" ).set_encoded_fragment( "john doe" ).encoded_fragment() == "john%20doe" );


this->has_fragment() == true && this->fragment() == s

Linear in `this->size() + s.size()`.

Strong guarantee.

Calls to allocate may throw.


fragment    = *( pchar / "/" / "?" )

3.5. Fragment

Parameters

Name	Description
s	The string to set.

Synopsis

Declared in <include/boost/url/url_base.hpp>


url_base&
set_encoded_fragment(pct_string_view s);

Description

This function sets the fragment to the specified string, which may contain percent-escapes and which may be empty. An empty fragment is distinct from having no fragment. Escapes in the string are preserved, and reserved characters in the string are percent-escaped in the result.


assert( url("?first=john&last=doe" ).set_encoded_fragment( "john%2Ddoe" ).fragment() == "john-doe" );


this->has_fragment() == true && this->fragment() == decode_view( s )

Linear in `this->size() + s.size()`.

Strong guarantee.

Calls to allocate may throw. Exceptions thrown on invalid input.


fragment    = *( pchar / "/" / "?" )

3.5. Fragment

Exceptions

Name	Thrown on
`s`	contains an invalid percent-encoding.

Parameters

Name	Description
s	The string to set.

Synopsis

Declared in <include/boost/url/url_base.hpp>


url_base&
remove_origin();

Description

This function removes the origin, which consists of the scheme and authority.


assert( url( "http://www.example.com/index.htm" ).remove_origin().buffer() == "/index.htm" );


this->scheme_id() == scheme::none && this->has_authority() == false

Linear in `this->size()`.

Throws nothing.

Normalize the URL components

Synopsis

Declared in <include/boost/url/url_base.hpp>


url_base&
normalize();

Description

Applies Syntax-based normalization to all components of the URL.

Strong guarantee.

Calls to allocate may throw.

6.2.2 Syntax-Based Normalization (rfc3986)

Normalize the URL scheme

Synopsis

Declared in <include/boost/url/url_base.hpp>


url_base&
normalize_scheme();

Description

Applies Syntax-based normalization to the URL scheme.

The scheme is normalized to lowercase.

Strong guarantee.

Calls to allocate may throw.

6.2.2 Syntax-Based Normalization (rfc3986)

Normalize the URL authority

Synopsis

Declared in <include/boost/url/url_base.hpp>


url_base&
normalize_authority();

Description

Applies Syntax-based normalization to the URL authority.

Percent-encoding triplets are normalized to uppercase letters. Percent-encoded octets that correspond to unreserved characters are decoded.

Strong guarantee.

Calls to allocate may throw.

6.2.2 Syntax-Based Normalization (rfc3986)

Normalize the URL path

Synopsis

Declared in <include/boost/url/url_base.hpp>


url_base&
normalize_path();

Description

Applies Syntax-based normalization to the URL path.

Percent-encoding triplets are normalized to uppercase letters. Percent-encoded octets that correspond to unreserved characters are decoded. Redundant path-segments are removed.

Strong guarantee.

Calls to allocate may throw.

6.2.2 Syntax-Based Normalization (rfc3986)

Normalize the URL query

Synopsis

Declared in <include/boost/url/url_base.hpp>


url_base&
normalize_query();

Description

Applies Syntax-based normalization to the URL query.

Percent-encoding triplets are normalized to uppercase letters. Percent-encoded octets that correspond to unreserved characters are decoded.

Strong guarantee.

Calls to allocate may throw.

6.2.2 Syntax-Based Normalization (rfc3986)

Normalize the URL fragment

Synopsis

Declared in <include/boost/url/url_base.hpp>


url_base&
normalize_fragment();

Description

Applies Syntax-based normalization to the URL fragment.

Percent-encoding triplets are normalized to uppercase letters. Percent-encoded octets that correspond to unreserved characters are decoded.

Strong guarantee.

Calls to allocate may throw.

6.2.2 Syntax-Based Normalization (rfc3986)

Resolve a URL reference against this base URL

Synopsis

Declared in <include/boost/url/url_base.hpp>


system::result<void>
resolve(url_view_base const& ref);

Description

This function attempts to resolve a URL reference `ref` against this base URL in a manner similar to that of a web browser resolving an anchor tag.

This URL must satisfy the URI grammar. In other words, it must contain a scheme.

Relative references are only usable when in the context of a base absolute URI. This process of resolving a relative reference within the context of a base URI is defined in detail in rfc3986 (see below).

The resolution process works as if the relative reference is appended to the base URI and the result is normalized.

Given the input base URL, this function resolves the relative reference as if performing the following steps:

Ensure the base URI has at least a scheme

Normalizing the reference path

Merge base and reference paths

Normalize the merged path

This function places the result of the resolution into this URL in place.

If an error occurs, the contents of this URL are unspecified and a result with an `system::error_code` is returned.

NOTE

Abnormal hrefs where the number of ".." segments exceeds the number of segments in the base path are handled by including the unmatched ".." segments in the result, as described in Errata 4547 .


url base1( "/one/two/three" );
base1.resolve("four");
assert( base1.buffer() == "/one/two/four" );

url base2( "http://example.com/" )
base2.resolve("/one");
assert( base2.buffer() == "http://example.com/one" );

url base3( "http://example.com/one" );
base3.resolve("/two");
assert( base3.buffer() == "http://example.com/two" );

url base4( "http://a/b/c/d;p?q" );
base4.resolve("g#s");
assert( base4.buffer() == "http://a/b/c/g#s" );


absolute-URI  = scheme ":" hier-part [ "?" query ]

Basic guarantee.

Calls to allocate may throw.

5. Reference Resolution (rfc3986)

Return Value

An empty result upon success, otherwise an error code if `!base.has_scheme()`.

Parameters

Name	Description
ref	The URL reference to resolve.

Synopsis

Declared in <include/boost/url/url_base.hpp>


friend
system::result<void>
resolve(
    url_view_base const& base,
    url_view_base const& ref,
    url_base& dest);

Description

This function attempts to resolve a URL reference `ref` against the base URL `base` in a manner similar to that of a web browser resolving an anchor tag.

The base URL must satisfy the URI grammar. In other words, it must contain a scheme.

The resolution process works as if the relative reference is appended to the base URI and the result is normalized.

Given the input base URL, this function resolves the relative reference as if performing the following steps:

Ensure the base URI has at least a scheme

Normalizing the reference path

Merge base and reference paths

Normalize the merged path

This function places the result of the resolution into `dest`, which can be any of the url containers that inherit from url_base .

If an error occurs, the contents of `dest` is unspecified and `ec` is set.

NOTE

Abnormal hrefs where the number of ".." segments exceeds the number of segments in the base path are handled by including the unmatched ".." segments in the result, as described in Errata 4547 .


url dest;
system::error_code ec;

resolve("/one/two/three", "four", dest, ec);
assert( dest.str() == "/one/two/four" );

resolve("http://example.com/", "/one", dest, ec);
assert( dest.str() == "http://example.com/one" );

resolve("http://example.com/one", "/two", dest, ec);
assert( dest.str() == "http://example.com/two" );

resolve("http://a/b/c/d;p?q", "g#s", dest, ec);
assert( dest.str() == "http://a/b/c/g#s" );


absolute-URI  = scheme ":" hier-part [ "?" query ]

Basic guarantee.

Calls to allocate may throw.

5. Reference Resolution (rfc3986)

Return Value

An empty result upon success, otherwise an error code if `!base.has_scheme()`.

Parameters

Name	Description
base	The base URL to resolve against.
ref	The URL reference to resolve.
dest	The container where the result is written, upon success.

Synopsis

Declared in <include/boost/url/params_encoded_ref.hpp>


class params_encoded_ref
    : public params_encoded_base;

Types

Name	Description
`const_iterator`	A Bidirectional iterator to a query parameter
`const_reference`	The reference type
`difference_type`	A signed integer type used to represent differences.
`iterator`	A Bidirectional iterator to a query parameter
`reference`	The reference type
`size_type`	An unsigned integer type to represent sizes.
`value_type`	The value type

Member Functions

Name	Description
`append`	Append params
`assign`	Assign params
`begin`	Return an iterator to the beginning
`buffer`	Return the query corresponding to these params
`clear`	Clear the contents of the container
`contains`	Return true if a matching key exists
`count`	Return the number of matching keys
`empty`	Return true if there are no params
`end`	Return an iterator to the end
`erase`	Erase params
`find`	Find a matching key
`find_last`	Find a matching key
`insert`	Insert params
`operator params_encoded_view`	Conversion
`operator=`	Assignment
`params_encoded_ref` [constructor]	Constructor
`replace`	Replace params
`set`	Set a value
`size`	Return the number of params
`unset`	Remove the value on an element
`url`	Return the referenced url

Static Member Functions

Name	Description
`max_size`	Return the maximum number of characters possible

Description

Objects of this type are used to interpret the query parameters as a bidirectional view of key value pairs.

The view does not retain ownership of the elements and instead references the original url. The caller is responsible for ensuring that the lifetime of the referenced url extends until it is no longer referenced.

The view is modifiable; calling non-const members causes changes to the referenced url.


url u( "?first=John&last=Doe" );

params_encoded_ref p = u.encoded_params();

Changes to the underlying character buffer

can invalidate iterators which reference it. Modifications made through the container invalidate some iterators to the underlying character buffer:

append : Only `end()`.

assign , clear , `operator=` : All params.

erase : Erased params and all params after (including `end()`).

insert : All params at or after the insertion point (including `end()`).

replace , set : Modified params and all params after (including `end()`).

Constructor

Synopsis

Declared in <include/boost/url/params_encoded_ref.hpp>


constexpr
params_encoded_ref(params_encoded_ref const& other) = default;

Description

After construction, both views reference the same url. Ownership is not transferred; the caller is responsible for ensuring the lifetime of the url extends until it is no longer referenced.


&this->url() == &other.url();

Constant.

Throws nothing.

Parameters

Name	Description
other	The other view.

Assignment

Synopsis

Declared in <include/boost/url/params_encoded_ref.hpp>


params_encoded_ref&
operator=(params_encoded_ref const& other);

» more...


params_encoded_ref&
operator=(std::initializer_list<param_pct_view> init);

» more...

Description

The previous contents of this are replaced by the contents of `other.

All iterators are invalidated.

NOTE

The strings referenced by `other` must not come from the underlying url, or else the behavior is undefined.


this->assign( other.begin(), other.end() );

Linear in `other.buffer().size()`.

Strong guarantee.

Calls to allocate may throw.

Exceptions

Name	Thrown on
`[object Object]`	contains an invalid percent-encoding.

Parameters

Name	Description
other	The params to assign.
init	The list of params to assign.

Assignment

Synopsis

Declared in <include/boost/url/params_encoded_ref.hpp>


params_encoded_ref&
operator=(params_encoded_ref const& other);

Description

The previous contents of this are replaced by the contents of `other.

All iterators are invalidated.

NOTE

The strings referenced by `other` must not come from the underlying url, or else the behavior is undefined.


this->assign( other.begin(), other.end() );

Linear in `other.buffer().size()`.

Strong guarantee.

Calls to allocate may throw.

Parameters

Name	Description
other	The params to assign.

Assignment

Synopsis

Declared in <include/boost/url/params_encoded_ref.hpp>


params_encoded_ref&
operator=(std::initializer_list<param_pct_view> init);

Description

After assignment, the previous contents of the query parameters are replaced by the contents of the initializer-list.

All iterators are invalidated.

None of character buffers referenced by

`init` may overlap the character buffer of the underlying url, or else the behavior is undefined.


this->assign( init.begin(), init.end() );

Linear in `init.size()`.

Strong guarantee.

Calls to allocate may throw. Exceptions thrown on invalid input.

Exceptions

Name	Thrown on
`init`	contains an invalid percent-encoding.

Parameters

Name	Description
init	The list of params to assign.

Conversion

Synopsis

Declared in <include/boost/url/params_encoded_ref.hpp>


operator params_encoded_view() const noexcept;

Description

Constant.

Throws nothing.

Return the referenced url

Synopsis

Declared in <include/boost/url/params_encoded_ref.hpp>


url_base&
url() const noexcept;

Description

This function returns the url referenced by the view.


url u( "?key=value" );

assert( &u.encoded_params().url() == &u );


Throws nothing.

Clear the contents of the container

Synopsis

Declared in <include/boost/url/params_encoded_ref.hpp>


void
clear() noexcept;

Description

All iterators are invalidated.


this->url().remove_query();


this->empty() == true && this->url().has_query() == false

Constant.

Throws nothing.

Assign params

Synopsis

Declared in <include/boost/url/params_encoded_ref.hpp>


void
assign(std::initializer_list<param_pct_view> init);

» more...


template<class FwdIt>
void
assign(
    FwdIt first,
    FwdIt last);

» more...

Description

This function replaces the entire contents of the view with the params in the initializer-list .

All iterators are invalidated.

NOTE

The strings referenced by the inputs must not come from the underlying url, or else the behavior is undefined.


url u;

u.encoded_params().assign({ { "first", "John" }, { "last", "Doe" } });

Linear in `init.size()`.

Strong guarantee.

Calls to allocate may throw. Exceptions thrown on invalid input.

Exceptions

Name	Thrown on
`[object Object]`	contains an invalid percent-encoding.
`[object Object]`	range contains an invalid percent-encoding.

Parameters

Name	Description
init	The list of params to assign.
first,	last The range of params to assign.

Assign params

Synopsis

Declared in <include/boost/url/params_encoded_ref.hpp>


void
assign(std::initializer_list<param_pct_view> init);

Description

This function replaces the entire contents of the view with the params in the initializer-list .

All iterators are invalidated.

NOTE

The strings referenced by the inputs must not come from the underlying url, or else the behavior is undefined.


url u;

u.encoded_params().assign({ { "first", "John" }, { "last", "Doe" } });

Linear in `init.size()`.

Strong guarantee.

Calls to allocate may throw. Exceptions thrown on invalid input.

Exceptions

Name	Thrown on
`init`	contains an invalid percent-encoding.

Parameters

Name	Description
init	The list of params to assign.

Assign params

Synopsis

Declared in <include/boost/url/params_encoded_ref.hpp>


template<class FwdIt>
void
assign(
    FwdIt first,
    FwdIt last);

Description

This function replaces the entire contents of the view with the params in the range.

All iterators are invalidated.

NOTE

The strings referenced by the inputs must not come from the underlying url, or else the behavior is undefined.


std::is_convertible< std::iterator_traits< FwdIt >::reference_type, param_pct_view >::value == true

Linear in the size of the range.

Strong guarantee.

Calls to allocate may throw. Exceptions thrown on invalid input.

Exceptions

Name	Thrown on
`The`	range contains an invalid percent-encoding.

Parameters

Name	Description
first,	last The range of params to assign.

Append params

Synopsis

Declared in <include/boost/url/params_encoded_ref.hpp>


iterator
append(param_pct_view const& p);

» more...


iterator
append(std::initializer_list<param_pct_view> init);

» more...


template<class FwdIt>
iterator
append(
    FwdIt first,
    FwdIt last);

» more...

Description

This function appends a param to the view.

The `end()` iterator is invalidated.


url u;

u.encoded_params().append( { "first", "John" } );

Linear in `this->url().encoded_query().size()`.

Strong guarantee.

Calls to allocate may throw. Exceptions thrown on invalid input.

Exceptions

Name	Thrown on
`[object Object]`	contains an invalid percent-encoding.
`[object Object]`	contains an invalid percent-encoding.
`[object Object]`	range contains an invalid percent-encoding.

Return Value

An iterator to the new element.

Parameters

Name	Description
p	The param to append.
init	The list of params to append.
first,	last The range of params to append.

Append params

Synopsis

Declared in <include/boost/url/params_encoded_ref.hpp>


iterator
append(param_pct_view const& p);

Description

This function appends a param to the view.

The `end()` iterator is invalidated.


url u;

u.encoded_params().append( { "first", "John" } );

Linear in `this->url().encoded_query().size()`.

Strong guarantee.

Calls to allocate may throw. Exceptions thrown on invalid input.

Exceptions

Name	Thrown on
`p`	contains an invalid percent-encoding.

Return Value

An iterator to the new element.

Parameters

Name	Description
p	The param to append.

Append params

Synopsis

Declared in <include/boost/url/params_encoded_ref.hpp>


iterator
append(std::initializer_list<param_pct_view> init);

Description

This function appends the params in an initializer-list to the view.

The `end()` iterator is invalidated.


url u;

u.encoded_params().append({ {"first", "John"}, {"last", "Doe"} });

Linear in `this->url().encoded_query().size()`.

Strong guarantee.

Calls to allocate may throw. Exceptions thrown on invalid input.

Exceptions

Name	Thrown on
`init`	contains an invalid percent-encoding.

Return Value

An iterator to the first new element.

Parameters

Name	Description
init	The list of params to append.

Append params

Synopsis

Declared in <include/boost/url/params_encoded_ref.hpp>


template<class FwdIt>
iterator
append(
    FwdIt first,
    FwdIt last);

Description

This function appends a range of params to the view.

The `end()` iterator is invalidated.

NOTE

The strings referenced by the inputs must not come from the underlying url, or else the behavior is undefined.


std::is_convertible< std::iterator_traits< FwdIt >::reference_type, param_pct_view >::value == true

Linear in `this->url().encoded_query().size()`.

Strong guarantee.

Calls to allocate may throw. Exceptions thrown on invalid input.

Exceptions

Name	Thrown on
`The`	range contains an invalid percent-encoding.

Return Value

An iterator to the first new element.

Parameters

Name	Description
first,	last The range of params to append.

Insert params

Synopsis

Declared in <include/boost/url/params_encoded_ref.hpp>


iterator
insert(
    iterator before,
    param_pct_view const& p);

» more...


iterator
insert(
    iterator before,
    std::initializer_list<param_pct_view> init);

» more...


template<class FwdIt>
iterator
insert(
    iterator before,
    FwdIt first,
    FwdIt last);

» more...

Description

This function inserts a param before the specified position.

All iterators that are equal to `before` or come after are invalidated.

Linear in `this->url().encoded_query().size()`.

Strong guarantee.

Calls to allocate may throw. Exceptions thrown on invalid input.

Exceptions

Name	Thrown on
`[object Object]`	contains an invalid percent-encoding.
`[object Object]`	contains an invalid percent-encoding.
`[object Object]`	range contains an invalid percent-encoding.

Return Value

An iterator to the inserted element.

Parameters

Name	Description
before	An iterator before which the param is inserted. This may be equal to `end()`.
p	The param to insert.
init	The list of params to insert.
first,	last The range of params to insert.

Insert params

Synopsis

Declared in <include/boost/url/params_encoded_ref.hpp>


iterator
insert(
    iterator before,
    param_pct_view const& p);

Description

This function inserts a param before the specified position.

All iterators that are equal to `before` or come after are invalidated.

Linear in `this->url().encoded_query().size()`.

Strong guarantee.

Calls to allocate may throw. Exceptions thrown on invalid input.

Exceptions

Name	Thrown on
`p`	contains an invalid percent-encoding.

Return Value

An iterator to the inserted element.

Parameters

Name	Description
before	An iterator before which the param is inserted. This may be equal to `end()`.
p	The param to insert.

Insert params

Synopsis

Declared in <include/boost/url/params_encoded_ref.hpp>


iterator
insert(
    iterator before,
    std::initializer_list<param_pct_view> init);

Description

This function inserts the params in an initializer-list before the specified position.

All iterators that are equal to `before` or come after are invalidated.

NOTE

The strings referenced by the inputs must not come from the underlying url, or else the behavior is undefined.

Linear in `this->url().encoded_query().size()`.

Strong guarantee.

Calls to allocate may throw. Exceptions thrown on invalid input.

Exceptions

Name	Thrown on
`init`	contains an invalid percent-encoding.

Return Value

An iterator to the first element inserted, or `before` if `init.size() == 0`.

Parameters

Name	Description
before	An iterator before which the element is inserted. This may be equal to `end()`.
init	The list of params to insert.

Insert params

Synopsis

Declared in <include/boost/url/params_encoded_ref.hpp>


template<class FwdIt>
iterator
insert(
    iterator before,
    FwdIt first,
    FwdIt last);

Description

This function inserts a range of params before the specified position.

All iterators that are equal to `before` or come after are invalidated.

NOTE

The strings referenced by the inputs must not come from the underlying url, or else the behavior is undefined.


std::is_convertible< std::iterator_traits< FwdIt >::reference_type, param_pct_view >::value == true

Linear in `this->url().encoded_query().size()`.

Strong guarantee.

Calls to allocate may throw. Exceptions thrown on invalid input.

Exceptions

Name	Thrown on
`The`	range contains an invalid percent-encoding.

Return Value

An iterator to the first element inserted, or `before` if `first == last`.

Parameters

Name	Description
before	An iterator before which the element is inserted. This may be equal to `end()`.
first,	last The range of params to insert.

Erase params

Synopsis

Declared in <include/boost/url/params_encoded_ref.hpp>


iterator
erase(iterator pos) noexcept;

» more...


iterator
erase(
    iterator first,
    iterator last) noexcept;

» more...


std::size_t
erase(
    pct_string_view key,
    ignore_case_param ic = = {}) noexcept;

» more...

Description

This function removes an element from the container.

All iterators that are equal to `pos` or come after are invalidated.


url u( "?first=John&last=Doe" );

params_encoded_ref::iterator it = u.encoded_params().erase( u.encoded_params().begin() );

assert( u.encoded_query() == "last=Doe" );

Linear in `this->url().encoded_query().size()`.

Throws nothing.

Exceptions

Name	Thrown on
`[object Object]`	contains an invalid percent-encoding.

Return Value

An iterator to one past the removed element.

Parameters

Name	Description
pos	An iterator to the element.
first,	last The range of params to erase.
key	The key to match. By default, a case-sensitive comparison is used.
ic	An optional parameter. If the value ignore_case is passed here, the comparison is case-insensitive.

Erase params

Synopsis

Declared in <include/boost/url/params_encoded_ref.hpp>


iterator
erase(iterator pos) noexcept;

Description

This function removes an element from the container.

All iterators that are equal to `pos` or come after are invalidated.


url u( "?first=John&last=Doe" );

params_encoded_ref::iterator it = u.encoded_params().erase( u.encoded_params().begin() );

assert( u.encoded_query() == "last=Doe" );

Linear in `this->url().encoded_query().size()`.

Throws nothing.

Return Value

An iterator to one past the removed element.

Parameters

Name	Description
pos	An iterator to the element.

Erase params

Synopsis

Declared in <include/boost/url/params_encoded_ref.hpp>


iterator
erase(
    iterator first,
    iterator last) noexcept;

Description

This function removes a range of params from the container.

All iterators that are equal to `first` or come after are invalidated.

Linear in `this->url().encoded_query().size()`.

Throws nothing.

Return Value

An iterator to one past the removed range.

Parameters

Name	Description
first,	last The range of params to erase.

Erase params

Synopsis

Declared in <include/boost/url/params_encoded_ref.hpp>


std::size_t
erase(
    pct_string_view key,
    ignore_case_param ic = = {}) noexcept;

Description

All iterators are invalidated.


this->count( key, ic ) == 0

Linear in `this->url().encoded_query().size()`.

Exceptions thrown on invalid input.

Exceptions

Name	Thrown on
`key`	contains an invalid percent-encoding.

Return Value

The number of params removed from the container.

Parameters

Name	Description
key	The key to match. By default, a case-sensitive comparison is used.
ic	An optional parameter. If the value ignore_case is passed here, the comparison is case-insensitive.

Replace params

Synopsis

Declared in <include/boost/url/params_encoded_ref.hpp>


iterator
replace(
    iterator pos,
    param_pct_view const& p);

» more...


iterator
replace(
    iterator from,
    iterator to,
    std::initializer_list<param_pct_view> init);

» more...


template<class FwdIt>
iterator
replace(
    iterator from,
    iterator to,
    FwdIt first,
    FwdIt last);

» more...

Description

This function replaces the contents of the element at `pos` with the specified param.

All iterators that are equal to `pos` or come after are invalidated.

NOTE

The strings passed in must not come from the element being replaced, or else the behavior is undefined.


url u( "?first=John&last=Doe" );

u.encoded_params().replace( u.encoded_params().begin(), { "title", "Mr" });

assert( u.encoded_query() == "title=Mr&last=Doe" );

Linear in `this->url().encoded_query().size()`.

Strong guarantee.

Calls to allocate may throw. Exceptions thrown on invalid input.

Exceptions

Name	Thrown on
`[object Object]`	contains an invalid percent-encoding.
`[object Object]`	contains an invalid percent-encoding.
`[object Object]`	range contains an invalid percent-encoding.

Return Value

An iterator to the element.

Parameters

Name	Description
pos	An iterator to the element.
p	The param to assign.
from,to	The range of params to replace.
init	The list of params to assign.
first,	last The range of params to assign.

Replace params

Synopsis

Declared in <include/boost/url/params_encoded_ref.hpp>


iterator
replace(
    iterator pos,
    param_pct_view const& p);

Description

This function replaces the contents of the element at `pos` with the specified param.

All iterators that are equal to `pos` or come after are invalidated.

NOTE

The strings passed in must not come from the element being replaced, or else the behavior is undefined.


url u( "?first=John&last=Doe" );

u.encoded_params().replace( u.encoded_params().begin(), { "title", "Mr" });

assert( u.encoded_query() == "title=Mr&last=Doe" );

Linear in `this->url().encoded_query().size()`.

Strong guarantee.

Calls to allocate may throw. Exceptions thrown on invalid input.

Exceptions

Name	Thrown on
`p`	contains an invalid percent-encoding.

Return Value

An iterator to the element.

Parameters

Name	Description
pos	An iterator to the element.
p	The param to assign.

Replace params

Synopsis

Declared in <include/boost/url/params_encoded_ref.hpp>


iterator
replace(
    iterator from,
    iterator to,
    std::initializer_list<param_pct_view> init);

Description

This function replaces a range of params with the params in an initializer-list .

All iterators that are equal to `from` or come after are invalidated.

NOTE

The strings referenced by the inputs must not come from the underlying url, or else the behavior is undefined.

Linear in `this->url().encoded_query().size()`.

Strong guarantee.

Calls to allocate may throw. Exceptions thrown on invalid input.

Exceptions

Name	Thrown on
`init`	contains an invalid percent-encoding.

Return Value

An iterator to the first element inserted, or one past `to` if `init.size() == 0`.

Parameters

Name	Description
from,to	The range of params to replace.
init	The list of params to assign.

Replace params

Synopsis

Declared in <include/boost/url/params_encoded_ref.hpp>


template<class FwdIt>
iterator
replace(
    iterator from,
    iterator to,
    FwdIt first,
    FwdIt last);

Description

This function replaces a range of params with a range of params.

All iterators that are equal to `from` or come after are invalidated.

NOTE

The strings referenced by the inputs must not come from the underlying url, or else the behavior is undefined.


std::is_convertible< std::iterator_traits< FwdIt >::reference_type, param_pct_view >::value == true

Linear in `this->url().encoded_query().size()`.

Strong guarantee.

Calls to allocate may throw. Exceptions thrown on invalid input.

Exceptions

Name	Thrown on
`The`	range contains an invalid percent-encoding.

Return Value

An iterator to the first element inserted, or one past `to` if `first == last`.

Parameters

Name	Description
from,to	The range of params to replace.
first,	last The range of params to assign.

Remove the value on an element

Synopsis

Declared in <include/boost/url/params_encoded_ref.hpp>


iterator
unset(iterator pos) noexcept;

Description

This function removes the value of an element at the specified position. After the call returns, `has_value` for the element is false.

All iterators that are equal to `pos` or come after are invalidated.


url u( "?first=John&last=Doe" );

u.encoded_params().unset( u.encoded_params().begin() );

assert( u.encoded_query() == "first&last=Doe" );

Linear in `this->url().encoded_query().size()`.

Throws nothing.

Return Value

An iterator to the element.

Parameters

Name	Description
pos	An iterator to the element.

Set a value

Synopsis

Declared in <include/boost/url/params_encoded_ref.hpp>


iterator
set(
    iterator pos,
    pct_string_view value);

» more...


iterator
set(
    pct_string_view key,
    pct_string_view value,
    ignore_case_param ic = = {});

» more...

Description

This function replaces the value of an element at the specified position.

All iterators that are equal to `pos` or come after are invalidated.

NOTE

The string passed in must not come from the element being replaced, or else the behavior is undefined.


url u( "?id=42&id=69" );

u.encoded_params().set( u.encoded_params().begin(), "none" );

assert( u.encoded_query() == "id=none&id=69" );

Linear in `this->url().encoded_query().size()`.

Strong guarantee.

Calls to allocate may throw. Exceptions thrown on invalid input.

Exceptions

Name	Thrown on
`[object Object]`	contains an invalid percent-encoding.
`[object Object]`	or `value` contain an invalid percent-encoding.

Return Value

An iterator to the element.

Parameters

Name	Description
pos	An iterator to the element.
value	The value to assign. The empty string still counts as a value. That is, `has_value` for the element is true.
key	The key to match. By default, a case-sensitive comparison is used.
ic	An optional parameter. If the value ignore_case is passed here, the comparison is case-insensitive.

Set a value

Synopsis

Declared in <include/boost/url/params_encoded_ref.hpp>


iterator
set(
    iterator pos,
    pct_string_view value);

Description

This function replaces the value of an element at the specified position.

All iterators that are equal to `pos` or come after are invalidated.

NOTE

The string passed in must not come from the element being replaced, or else the behavior is undefined.


url u( "?id=42&id=69" );

u.encoded_params().set( u.encoded_params().begin(), "none" );

assert( u.encoded_query() == "id=none&id=69" );

Linear in `this->url().encoded_query().size()`.

Strong guarantee.

Calls to allocate may throw. Exceptions thrown on invalid input.

Exceptions

Name	Thrown on
`value`	contains an invalid percent-encoding.

Return Value

An iterator to the element.

Parameters

Name	Description
pos	An iterator to the element.
value	The value to assign. The empty string still counts as a value. That is, `has_value` for the element is true.

Set a value

Synopsis

Declared in <include/boost/url/params_encoded_ref.hpp>


iterator
set(
    pct_string_view key,
    pct_string_view value,
    ignore_case_param ic = = {});

Description

This function performs one of two actions depending on the value of `this->contains( key, ic )`.

If key is contained in the view then one of the matching params has its value changed to the specified value. The remaining params with a matching key are erased. Otherwise,

If `key` is not contained in the view, then the function apppends the param `{ key, value }`.

All iterators are invalidated.

NOTE

The strings passed in must not come from the element being replaced, or else the behavior is undefined.


url u( "?id=42&id=69" );

u.encoded_params().set( "id", "none" );

assert( u.encoded_params().count( "id" ) == 1 );


this->count( key, ic ) == 1 && this->find( key, ic )->value == value

Linear in `this->url().encoded_query().size()`.

Strong guarantee.

Calls to allocate may throw. Exceptions thrown on invalid input.

Exceptions

Name	Thrown on
`key`	or `value` contain an invalid percent-encoding.

Return Value

An iterator to the appended or modified element.

Parameters

Name	Description
key	The key to match. By default, a case-sensitive comparison is used.
value	The value to assign. The empty string still counts as a value. That is, `has_value` for the element is true.
ic	An optional parameter. If the value ignore_case is passed here, the comparison is case-insensitive.

Common functionality for containers

Synopsis

Declared in <include/boost/url/segments_encoded_base.hpp>


class segments_encoded_base;

Types

Name	Description
`const_iterator`	A Bidirectional iterator to a path segment
`const_reference`	The reference type
`difference_type`	A signed integer type used to represent differences.
`iterator`	A Bidirectional iterator to a path segment
`reference`	The reference type
`size_type`	An unsigned integer type used to represent size.
`value_type`	The value type

Member Functions

Name	Description
`back`	Return the last segment
`begin`	Return an iterator to the beginning
`buffer`	Return the referenced character buffer.
`empty`	Return true if there are no segments
`end`	Return an iterator to the end
`front`	Return the first segment
`is_absolute`	Returns true if this references an absolute path.
`size`	Return the number of segments

Static Member Functions

Name	Description
`max_size`	Return the maximum number of characters possible

Description

This base class is used by the library to provide common member functions for containers. This cannot be instantiated directly; Instead, use one of the containers or functions:

segments_ref

segments_view

segments_encoded_ref

segments_encoded_view

A Bidirectional iterator to a path segment

Synopsis

Declared in <include/boost/url/impl/segments_encoded_base.hpp>


class iterator;

Types

Name	Description
`difference_type`
`iterator_category`
`pointer`
`reference`
`value_type`

Member Functions

Name	Description
`iterator` [constructor]
`operator!=`
`operator*`
`operator++`
`operator--`
`operator->`
`operator=`
`operator==`

Description

Objects of this type allow iteration through the segments in the path. Strings returned by iterators may contain percent escapes. The values returned are read-only; changes to segments must be made through the container instead, if the container supports modification.

Synopsis

Declared in <include/boost/url/impl/segments_encoded_base.hpp>


using value_type = segments_encoded_base::value_type;

Synopsis

Declared in <include/boost/url/impl/segments_encoded_base.hpp>


using reference = segments_encoded_base::reference;

Synopsis

Declared in <include/boost/url/impl/segments_encoded_base.hpp>


using pointer = reference;

Synopsis

Declared in <include/boost/url/impl/segments_encoded_base.hpp>


using difference_type = std::ptrdiff_t;

Synopsis

Declared in <include/boost/url/impl/segments_encoded_base.hpp>


using iterator_category = std::bidirectional_iterator_tag;

Synopsis

Declared in <include/boost/url/impl/segments_encoded_base.hpp>


constexpr
iterator() = default;

» more...


constexpr
iterator(iterator const&) = default;

» more...

Synopsis

Declared in <include/boost/url/impl/segments_encoded_base.hpp>


constexpr
iterator() = default;

Synopsis

Declared in <include/boost/url/impl/segments_encoded_base.hpp>


constexpr
iterator(iterator const&) = default;

Synopsis

Declared in <include/boost/url/impl/segments_encoded_base.hpp>


constexpr
iterator&
operator=(iterator const&) = default;

Synopsis

Declared in <include/boost/url/impl/segments_encoded_base.hpp>


reference
operator*() const noexcept;

Synopsis

Declared in <include/boost/url/impl/segments_encoded_base.hpp>


pointer
operator->() const noexcept;

Synopsis

Declared in <include/boost/url/impl/segments_encoded_base.hpp>


iterator&
operator++() noexcept;

» more...


iterator
operator++(int) noexcept;

» more...

Synopsis

Declared in <include/boost/url/impl/segments_encoded_base.hpp>


iterator&
operator++() noexcept;

Synopsis

Declared in <include/boost/url/impl/segments_encoded_base.hpp>


iterator
operator++(int) noexcept;

Synopsis

Declared in <include/boost/url/impl/segments_encoded_base.hpp>


iterator&
operator--() noexcept;

» more...


iterator
operator--(int) noexcept;

» more...

Synopsis

Declared in <include/boost/url/impl/segments_encoded_base.hpp>


iterator&
operator--() noexcept;

Synopsis

Declared in <include/boost/url/impl/segments_encoded_base.hpp>


iterator
operator--(int) noexcept;

Synopsis

Declared in <include/boost/url/impl/segments_encoded_base.hpp>


bool
operator==(iterator const& other) const noexcept;

Synopsis

Declared in <include/boost/url/impl/segments_encoded_base.hpp>


bool
operator!=(iterator const& other) const noexcept;

A Bidirectional iterator to a path segment

Synopsis

Declared in <include/boost/url/segments_encoded_base.hpp>


using const_iterator = iterator;

Description

The value type

Synopsis

Declared in <include/boost/url/segments_encoded_base.hpp>


using value_type = std::string;

Description

Values of this type represent a segment where unique ownership is retained by making a copy.


segments_encoded_base::value_type ps( url_view( "/path/to/file.txt" ).encoded_segments().back() );

The reference type

Synopsis

Declared in <include/boost/url/segments_encoded_base.hpp>


using reference = pct_string_view;

Description

This is the type of value returned when iterators of the view are dereferenced.

The reference type

Synopsis

Declared in <include/boost/url/segments_encoded_base.hpp>


using const_reference = pct_string_view;

Description

This is the type of value returned when iterators of the view are dereferenced.

An unsigned integer type used to represent size.

Synopsis

Declared in <include/boost/url/segments_encoded_base.hpp>


using size_type = std::size_t;

A signed integer type used to represent differences.

Synopsis

Declared in <include/boost/url/segments_encoded_base.hpp>


using difference_type = std::ptrdiff_t;

Return the maximum number of characters possible

Synopsis

Declared in <include/boost/url/segments_encoded_base.hpp>


constexpr
static
std::size_t
max_size() noexcept;

Description

This represents the largest number of characters that are possible in a path, not including any null terminator.

Throws nothing.

Return the referenced character buffer.

Synopsis

Declared in <include/boost/url/segments_encoded_base.hpp>


pct_string_view
buffer() const noexcept;

Description

This function returns the character buffer referenced by the view. The returned string may contain percent escapes.


assert( url_view( "/path/to/file.txt" ).encoded_segments().buffer() == "/path/to/file.txt" );

Constant.

Throws nothing.

Returns true if this references an absolute path.

Synopsis

Declared in <include/boost/url/segments_encoded_base.hpp>


bool
is_absolute() const noexcept;

Description

Absolute paths always start with a forward slash ('/').


assert( url_view( "/path/to/file.txt" ).encoded_segments().is_absolute() == true );

Constant.

Throws nothing.

Return true if there are no segments

Synopsis

Declared in <include/boost/url/segments_encoded_base.hpp>


bool
empty() const noexcept;

Description


assert( ! url_view( "/index.htm" ).encoded_segments().empty() );

Constant.

Throws nothing.

Return the number of segments

Synopsis

Declared in <include/boost/url/segments_encoded_base.hpp>


std::size_t
size() const noexcept;

Description


assert( url_view( "/path/to/file.txt" ).encoded_segments().size() == 3 );

Constant.

Throws nothing.

Return the first segment

Synopsis

Declared in <include/boost/url/segments_encoded_base.hpp>


pct_string_view
front() const noexcept;

Description

This function returns a string with the first segment of the path without any leading or trailing '/' separators. The returned string may contain percent escapes.


this->empty() == false


return *begin();


assert( url_view( "/path/to/file.txt" ).encoded_segments().front() == "path" );

Constant.

Throws nothing.

Return the last segment

Synopsis

Declared in <include/boost/url/segments_encoded_base.hpp>


pct_string_view
back() const noexcept;

Description

This function returns a string with the last segment of the path without any leading or trailing '/' separators. The returned string may contain percent escapes.


this->empty() == false


assert( url_view( "/path/to/file.txt" ).encoded_segments().back() == "file.txt" );


this->empty() == false


return *--end();

Constant.

Throws nothing.

Return an iterator to the beginning

Synopsis

Declared in <include/boost/url/segments_encoded_base.hpp>


iterator
begin() const noexcept;

Description

Linear in `this->front().size()` or

constant if `this->empty()`.

Throws nothing.

Return an iterator to the end

Synopsis

Declared in <include/boost/url/segments_encoded_base.hpp>


iterator
end() const noexcept;

Description

Constant.

Throws nothing.

A view representing path segments in a URL

Synopsis

Declared in <include/boost/url/segments_encoded_view.hpp>


class segments_encoded_view
    : public segments_encoded_base;

Types

Name	Description
`const_iterator`	A Bidirectional iterator to a path segment
`const_reference`	The reference type
`difference_type`	A signed integer type used to represent differences.
`iterator`	A Bidirectional iterator to a path segment
`reference`	The reference type
`size_type`	An unsigned integer type used to represent size.
`value_type`	The value type

Member Functions

Name	Description
`back`	Return the last segment
`begin`	Return an iterator to the beginning
`buffer`	Return the referenced character buffer.
`empty`	Return true if there are no segments
`end`	Return an iterator to the end
`front`	Return the first segment
`is_absolute`	Returns true if this references an absolute path.
`operator segments_view`	Conversion
`operator=`	Assignment
`segments_encoded_view` [constructor]	Constructor
`size`	Return the number of segments

Static Member Functions

Name	Description
`max_size`	Return the maximum number of characters possible

Friends

Name	Description
`parse_path`	Parse a string and return an encoded segment view

Description

Objects of this type are used to interpret the path as a bidirectional view of segment strings.


url_view u( "/path/to/file.txt" );

segments_encoded_view ps = u.encoded_segments();

assert( ps.buffer().data() == u.buffer().data() );

Changes to the underlying character buffer

can invalidate iterators which reference it.

Synopsis

Declared in <include/boost/url/segments_encoded_view.hpp>


constexpr
segments_encoded_view() = default;

» more...


constexpr
segments_encoded_view(segments_encoded_view const&) noexcept = default;

» more...


segments_encoded_view(core::string_view s);

» more...

Description

Default-constructed segments have zero elements.


segments_encoded_view ps;


return segments_encoded_view( "" );

Constant.

Throws nothing.

Exceptions

Name	Thrown on
`[object Object]`	contains an invalid path.

Parameters

Name	Description
s	The string to parse.

Constructor

Synopsis

Declared in <include/boost/url/segments_encoded_view.hpp>


constexpr
segments_encoded_view() = default;

Description

Default-constructed segments have zero elements.


segments_encoded_view ps;


return segments_encoded_view( "" );

Constant.

Throws nothing.

Constructor

Synopsis

Declared in <include/boost/url/segments_encoded_view.hpp>


constexpr
segments_encoded_view(segments_encoded_view const&) noexcept = default;

Description

After construction, both views reference the same character buffer.

Ownership is not transferred; the caller is responsible for ensuring the lifetime of the buffer extends until it is no longer referenced.


this->buffer().data() == other.buffer().data()

Constant.

Throws nothing

Constructor

Synopsis

Declared in <include/boost/url/segments_encoded_view.hpp>


segments_encoded_view(core::string_view s);

Description

This function constructs segments from a valid path string, which can contain percent escapes. Upon construction, the view references the character buffer pointed to by `s`. caller is responsible for ensuring that the lifetime of the buffer extends until the view is destroyed.


segments_encoded_view ps( "/path/to/file.txt" );


return parse_path( s ).value();


this->buffer().data() == s.data()

Linear in `s`.

Exceptions thrown on invalid input.


path = [ "/" ] [ segment *( "/" segment ) ]

segment = *pchar

3.3. Path

Exceptions

Name	Thrown on
`s`	contains an invalid path.

Parameters

Name	Description
s	The string to parse.

Assignment

Synopsis

Declared in <include/boost/url/segments_encoded_view.hpp>


constexpr
segments_encoded_view&
operator=(segments_encoded_view const&) = default;

Description

After assignment, both views reference the same underlying character buffer.

Ownership is not transferred; the caller is responsible for ensuring the lifetime of the buffer extends until it is no longer referenced.


this->buffer().data() == other.buffer().data()

Constant

Throws nothing

Conversion

Synopsis

Declared in <include/boost/url/segments_encoded_view.hpp>


operator segments_view() const noexcept;

Description

This conversion returns a new view which references the same underlying character buffer, and whose iterators and members return ordinary strings with decoding applied to any percent escapes.

Ownership is not transferred; the caller is responsible for ensuring the lifetime of the buffer extends until it is no longer referenced.


segments_view ps = parse_path( "/path/to/file.txt" ).value();


segments_view( *this ).buffer().data() == this->buffer().data()

Constant

Throws nothing

Parse a string and return an encoded segment view

Synopsis

Declared in <include/boost/url/segments_encoded_view.hpp>


friend
system::result<segments_encoded_view>
parse_path(core::string_view s) noexcept;

Description

This function parses the string and returns the corresponding path object if the string is valid, otherwise returns an error.


path          = [ "/" ] segment *( "/" segment )

No-throw guarantee.

3.3. Path (rfc3986)

Return Value

A valid view on success, otherwise an error code.

Parameters

Name	Description
s	The string to parse

Synopsis

Declared in <include/boost/url/segments_encoded_ref.hpp>


class segments_encoded_ref
    : public segments_encoded_base;

Types

Name	Description
`const_iterator`	A Bidirectional iterator to a path segment
`const_reference`	The reference type
`difference_type`	A signed integer type used to represent differences.
`iterator`	A Bidirectional iterator to a path segment
`reference`	The reference type
`size_type`	An unsigned integer type used to represent size.
`value_type`	The value type

Member Functions

Name	Description
`assign`	Assign segments
`back`	Return the last segment
`begin`	Return an iterator to the beginning
`buffer`	Return the referenced character buffer.
`clear`	Clear the contents of the container
`empty`	Return true if there are no segments
`end`	Return an iterator to the end
`erase`	Erase segments
`front`	Return the first segment
`insert`	Insert segments
`is_absolute`	Returns true if this references an absolute path.
`operator segments_encoded_view`	Conversion
`operator=`	Assignment
`pop_back`	Remove the last segment
`push_back`	Append a segment
`replace`	Replace segments
`segments_encoded_ref` [constructor]	Constructor
`size`	Return the number of segments
`url`	Return the referenced url

Static Member Functions

Name	Description
`max_size`	Return the maximum number of characters possible

Description

Objects of this type are used to interpret the path as a bidirectional view of segments, where each segment is a string which may contain percent-escapes.

The view is modifiable; calling non-const members causes changes to the referenced url.


url u( "/path/to/file.txt" );

segments_encoded_ref ps = u.encoded_segments();

The strings returned when iterators are dereferenced have type pct_string_view and may contain percent-escapes.

Reserved characters in inputs are automatically escaped. Escapes in inputs are preserved.

Exceptions are thrown on invalid inputs.

Changes to the underlying character buffer

can invalidate iterators which reference it. Modifications made through the container invalidate some or all iterators:

push_back : Only `end()`.

assign , clear , operator= : All elements.

erase : Erased elements and all elements after (including `end()`).

insert : All elements at or after the insertion point (including `end()`).

replace : Modified elements and all elements after (including `end()`).

Synopsis

Declared in <include/boost/url/segments_encoded_ref.hpp>


constexpr
segments_encoded_ref(segments_encoded_ref const& other) = default;

Description

After construction, both views reference the same url. Ownership is not transferred; the caller is responsible for ensuring the lifetime of the url extends until it is no longer referenced.


&this->url() == &other.url();

Constant.

Throws nothing.

Parameters

Name	Description
other	The other view.

Assignment

Synopsis

Declared in <include/boost/url/segments_encoded_ref.hpp>


segments_encoded_ref&
operator=(segments_encoded_ref const& other);

» more...


segments_encoded_ref&
operator=(segments_encoded_view const& other);

» more...


segments_encoded_ref&
operator=(std::initializer_list<pct_string_view> init);

» more...

Description

The existing contents are replaced by a copy of the other segments.

All iterators are invalidated.

NOTE

None of the character buffers referenced by `other` may overlap the buffer of the underlying url, or else the behavior is undefined.


this->assign( other.begin(), other.end() );

Linear in `other.buffer().size()`.

Strong guarantee.

Calls to allocate may throw.

Exceptions

Name	Thrown on
`[object Object]`	list contains an invalid percent-encoding.

Parameters

Name	Description
other	The segments to assign.
init	The list of segments to assign.

Assignment

Synopsis

Declared in <include/boost/url/segments_encoded_ref.hpp>


segments_encoded_ref&
operator=(segments_encoded_ref const& other);

Description

The existing contents are replaced by a copy of the other segments.

All iterators are invalidated.

NOTE

None of the character buffers referenced by `other` may overlap the buffer of the underlying url, or else the behavior is undefined.


this->assign( other.begin(), other.end() );

Linear in `other.buffer().size()`.

Strong guarantee.

Calls to allocate may throw.

Parameters

Name	Description
other	The segments to assign.

Synopsis

Declared in <include/boost/url/segments_encoded_ref.hpp>


segments_encoded_ref&
operator=(segments_encoded_view const& other);

Assignment

Synopsis

Declared in <include/boost/url/segments_encoded_ref.hpp>


segments_encoded_ref&
operator=(std::initializer_list<pct_string_view> init);

Description

The existing contents are replaced by a copy of the contents of the initializer list. Reserved characters in the list are automatically escaped. Escapes in the list are preserved.

All iterators are invalidated.


url u;

u.encoded_segments() = {"path", "to", "file.txt"};

None of the character buffers referenced

by the list may overlap the character buffer of the underlying url, or else the behavior is undefined.


this->assign( init.begin(), init.end() );

Linear in `init.size() + this->url().encoded_query().size() + this->url().encoded_fragment().size()`.

Strong guarantee.

Calls to allocate may throw. Exceptions thrown on invalid input.

Exceptions

Name	Thrown on
`The`	list contains an invalid percent-encoding.

Parameters

Name	Description
init	The list of segments to assign.

Conversion

Synopsis

Declared in <include/boost/url/segments_encoded_ref.hpp>


operator segments_encoded_view() const noexcept;

Synopsis

Declared in <include/boost/url/segments_encoded_ref.hpp>


url_base&
url() const noexcept;

Description

This function returns the url referenced by the view.


url u( "/path/to/file.txt" );

assert( &u.encoded_segments().url() == &u );

Throws nothing.

Clear the contents of the container

Synopsis

Declared in <include/boost/url/segments_encoded_ref.hpp>


void
clear() noexcept;

Description

All iterators are invalidated.


this->url().set_encoded_path( "" );


this->empty() == true

Linear in `this->url().encoded_query().size() + this->url().encoded_fragment().size()`.

Throws nothing.

Assign segments

Synopsis

Declared in <include/boost/url/segments_encoded_ref.hpp>


void
assign(std::initializer_list<pct_string_view> init);

» more...


template<class FwdIt>
void
assign(
    FwdIt first,
    FwdIt last);

» more...

Description

The existing contents are replaced by a copy of the contents of the initializer list. Reserved characters in the list are automatically escaped. Escapes in the list are preserved.

All iterators are invalidated.

NOTE

None of the character buffers referenced by the list may overlap the character buffer of the underlying url, or else the behavior is undefined.


url u;

u.segments().assign( {"path", "to", "file.txt"} );

Linear in `init.size() + this->url().encoded_query().size() + this->url().encoded_fragment().size()`.

Strong guarantee.

Calls to allocate may throw. Exceptions thrown on invalid input.

Exceptions

Name	Thrown on
`[object Object]`	list contains an invalid percent-encoding.

Parameters

Name	Description
init	The list of segments to assign.
first,	last The range of segments to assign.

Assign segments

Synopsis

Declared in <include/boost/url/segments_encoded_ref.hpp>


void
assign(std::initializer_list<pct_string_view> init);

Description

The existing contents are replaced by a copy of the contents of the initializer list. Reserved characters in the list are automatically escaped. Escapes in the list are preserved.

All iterators are invalidated.

NOTE

None of the character buffers referenced by the list may overlap the character buffer of the underlying url, or else the behavior is undefined.


url u;

u.segments().assign( {"path", "to", "file.txt"} );

Linear in `init.size() + this->url().encoded_query().size() + this->url().encoded_fragment().size()`.

Strong guarantee.

Calls to allocate may throw. Exceptions thrown on invalid input.

Exceptions

Name	Thrown on
`The`	list contains an invalid percent-encoding.

Parameters

Name	Description
init	The list of segments to assign.

Assign segments

Synopsis

Declared in <include/boost/url/segments_encoded_ref.hpp>


template<class FwdIt>
void
assign(
    FwdIt first,
    FwdIt last);

Description

The existing contents are replaced by a copy of the contents of the range. Reserved characters in the range are automatically escaped. Escapes in the range are preserved.

All iterators are invalidated.

NOTE

None of the character buffers referenced by the range may overlap the character buffer of the underlying url, or else the behavior is undefined.


std::is_convertible< std::iterator_traits< FwdIt >::reference_type, pct_string_view >::value == true

Linear in `std::distance( first, last ) + this->url().encoded_query().size() + this->url().encoded_fragment().size()`.

Strong guarantee.

Calls to allocate may throw. Exceptions thrown on invalid input.

Exceptions

Name	Thrown on
`The`	range contains an invalid percent-encoding.

Parameters

Name	Description
first,	last The range of segments to assign.

Insert segments

Synopsis

Declared in <include/boost/url/segments_encoded_ref.hpp>


iterator
insert(
    iterator before,
    pct_string_view s);

» more...


iterator
insert(
    iterator before,
    std::initializer_list<pct_string_view> init);

» more...


template<class FwdIt>
iterator
insert(
    iterator before,
    FwdIt first,
    FwdIt last);

» more...

Description

This function inserts a segment before the specified position. Reserved characters in the segment are automatically escaped. Escapes in the segment are preserved.

All iterators that are equal to `before` or come after are invalidated.

Linear in `s.size() + this->url().encoded_resource().size()`.

Strong guarantee.

Calls to allocate may throw. Exceptions thrown on invalid input.

Exceptions

Name	Thrown on
`[object Object]`	segment contains an invalid percent-encoding.

Return Value

An iterator to the inserted segment.

Parameters

Name	Description
before	An iterator before which the segment is inserted. This may be equal to `end()`.
s	The segment to insert.
init	The list of segments to insert.
first,	last The range of segments to insert.

Insert segments

Synopsis

Declared in <include/boost/url/segments_encoded_ref.hpp>


iterator
insert(
    iterator before,
    pct_string_view s);

Description

This function inserts a segment before the specified position. Reserved characters in the segment are automatically escaped. Escapes in the segment are preserved.

All iterators that are equal to `before` or come after are invalidated.

Linear in `s.size() + this->url().encoded_resource().size()`.

Strong guarantee.

Calls to allocate may throw. Exceptions thrown on invalid input.

Exceptions

Name	Thrown on
`The`	segment contains an invalid percent-encoding.

Return Value

An iterator to the inserted segment.

Parameters

Name	Description
before	An iterator before which the segment is inserted. This may be equal to `end()`.
s	The segment to insert.

Insert segments

Synopsis

Declared in <include/boost/url/segments_encoded_ref.hpp>


iterator
insert(
    iterator before,
    std::initializer_list<pct_string_view> init);

Description

This function inserts the segments in an initializer list before the specified position. Reserved characters in the list are automatically escaped. Escapes in the list are preserved.

All iterators that are equal to `before` or come after are invalidated.

NOTE

None of the character buffers referenced by the list may overlap the character buffer of the underlying url, or else the behavior is undefined.


url u( "/file.txt" );

u.encoded_segments().insert( u.encoded_segments().begin(), { "path", "to" } );

Linear in `init.size() + this->url().encoded_resource().size()`.

Strong guarantee.

Calls to allocate may throw. Exceptions thrown on invalid input.

Exceptions

Name	Thrown on
`The`	list contains an invalid percent-encoding.

Return Value

An iterator to the first element inserted, or `before` if `init.size() == 0`.

Parameters

Name	Description
before	An iterator before which the list is inserted. This may be equal to `end()`.
init	The list of segments to insert.

Insert segments

Synopsis

Declared in <include/boost/url/segments_encoded_ref.hpp>


template<class FwdIt>
iterator
insert(
    iterator before,
    FwdIt first,
    FwdIt last);

Description

This function inserts the segments in a range before the specified position. Reserved characters in the range are automatically escaped. Escapes in the range are preserved.

All iterators that are equal to `before` or come after are invalidated.

NOTE

None of the character buffers referenced by the range may overlap the character buffer of the underlying url, or else the behavior is undefined.


std::is_convertible< std::iterator_traits< FwdIt >::reference_type, pct_string_view >::value == true

Linear in `std::distance( first, last ) + this->url().encoded_resource().size()`.

Strong guarantee.

Calls to allocate may throw. Exceptions thrown on invalid input.

Exceptions

Name	Thrown on
`The`	range contains an invalid percent-encoding.

Return Value

An iterator to the first segment inserted, or `before` if `init.empty()`.

Parameters

Name	Description
before	An iterator before which the range is inserted. This may be equal to `end()`.
first,	last The range of segments to insert.

Erase segments

Synopsis

Declared in <include/boost/url/segments_encoded_ref.hpp>


iterator
erase(iterator pos) noexcept;

» more...


iterator
erase(
    iterator first,
    iterator last) noexcept;

» more...

Description

This function removes a segment.

All iterators that are equal to `pos` or come after are invalidated.

Linear in `this->url().encoded_resource().size()`.

Throws nothing.

Return Value

An iterator to one past the removed segment.

Parameters

Name	Description
pos	An iterator to the element.
first,	last The range of segments to erase.

Erase segments

Synopsis

Declared in <include/boost/url/segments_encoded_ref.hpp>


iterator
erase(iterator pos) noexcept;

Description

This function removes a segment.

All iterators that are equal to `pos` or come after are invalidated.

Linear in `this->url().encoded_resource().size()`.

Throws nothing.

Return Value

An iterator to one past the removed segment.

Parameters

Name	Description
pos	An iterator to the element.

Erase segments

Synopsis

Declared in <include/boost/url/segments_encoded_ref.hpp>


iterator
erase(
    iterator first,
    iterator last) noexcept;

Description

This function removes a range of segments from the container.

All iterators that are equal to `first` or come after are invalidated.

Linear in `this->url().encoded_resource().size()`.

Throws nothing.

Return Value

An iterator to one past the removed range.

Parameters

Name	Description
first,	last The range of segments to erase.

Replace segments

Synopsis

Declared in <include/boost/url/segments_encoded_ref.hpp>


iterator
replace(
    iterator pos,
    pct_string_view s);

» more...


iterator
replace(
    iterator from,
    iterator to,
    pct_string_view s);

» more...


iterator
replace(
    iterator from,
    iterator to,
    std::initializer_list<pct_string_view> init);

» more...


template<class FwdIt>
iterator
replace(
    iterator from,
    iterator to,
    FwdIt first,
    FwdIt last);

» more...

Description

This function replaces the segment at the specified position. Reserved characters in the string are automatically escaped. Escapes in the string are preserved.

All iterators that are equal to `pos` or come after are invalidated.

Linear in `s.size() + this->url().encoded_resouce().size()`.

Strong guarantee.

Calls to allocate may throw.

Exceptions

Name	Thrown on
`[object Object]`	string contains an invalid percent-encoding.

Return Value

An iterator to the replaced segment.

Parameters

Name	Description
pos	An iterator to the segment.
s	The string to assign.
from,	to The range of segments to replace.
init	The list of segments to assign.
first,	last The range of segments to assign.

Replace segments

Synopsis

Declared in <include/boost/url/segments_encoded_ref.hpp>


iterator
replace(
    iterator pos,
    pct_string_view s);

Description

This function replaces the segment at the specified position. Reserved characters in the string are automatically escaped. Escapes in the string are preserved.

All iterators that are equal to `pos` or come after are invalidated.

Linear in `s.size() + this->url().encoded_resouce().size()`.

Strong guarantee.

Calls to allocate may throw.

Return Value

An iterator to the replaced segment.

Parameters

Name	Description
pos	An iterator to the segment.
s	The string to assign.

Replace segments

Synopsis

Declared in <include/boost/url/segments_encoded_ref.hpp>


iterator
replace(
    iterator from,
    iterator to,
    pct_string_view s);

Description

This function replaces a range of segments with one segment. Reserved characters in the string are automatically escaped. Escapes in the string are preserved.

All iterators that are equal to `from` or come after are invalidated.

Linear in `s.size() + this->url().encoded_resouce().size()`.

Strong guarantee.

Calls to allocate may throw. Exceptions thrown on invalid input.

Exceptions

Name	Thrown on
`The`	string contains an invalid percent-encoding.

Return Value

An iterator to the new segment.

Parameters

Name	Description
from,	to The range of segments to replace.
s	The string to assign.

Replace segments

Synopsis

Declared in <include/boost/url/segments_encoded_ref.hpp>


iterator
replace(
    iterator from,
    iterator to,
    std::initializer_list<pct_string_view> init);

Description

This function replaces a range of segments with a list of segments in an initializer list. Reserved characters in the list are automatically escaped. Escapes in the list are preserved.

All iterators that are equal to `from` or come after are invalidated.

None of the character buffers referenced

by the list may overlap the character buffer of the underlying url, or else the behavior is undefined.

Linear in `init.size() + this->url().encoded_resouce().size()`.

Strong guarantee.

Calls to allocate may throw. Exceptions thrown on invalid input.

Exceptions

Name	Thrown on
`The`	list contains an invalid percent-encoding.

Return Value

An iterator to the first segment inserted, or one past `to` if `init.size() == 0`.

Parameters

Name	Description
from,	to The range of segments to replace.
init	The list of segments to assign.

Replace segments

Synopsis

Declared in <include/boost/url/segments_encoded_ref.hpp>


template<class FwdIt>
iterator
replace(
    iterator from,
    iterator to,
    FwdIt first,
    FwdIt last);

Description

This function replaces a range of segments with annother range of segments. Reserved characters in the new range are automatically escaped. Escapes in the new range are preserved.

All iterators that are equal to `from` or come after are invalidated.

None of the character buffers referenced

by the new range may overlap the character buffer of the underlying url, or else the behavior is undefined.

Linear in `std::distance( first, last ) + this->url().encoded_resouce().size()`.

Strong guarantee.

Calls to allocate may throw. Exceptions thrown on invalid input.

Exceptions

Name	Thrown on
`The`	range contains an invalid percent-encoding.

Return Value

An iterator to the first segment inserted, or one past `to` if `init.size() == 0`.

Parameters

Name	Description
from,	to The range of segments to replace.
first,	last The range of segments to assign.

Append a segment

Synopsis

Declared in <include/boost/url/segments_encoded_ref.hpp>


void
push_back(pct_string_view s);

Description

This function appends a segment to the end of the path. Reserved characters in the string are automatically escaped. Escapes in the string are preserved.

All end iterators are invalidated.


this->back() == s

Strong guarantee.

Calls to allocate may throw. Exceptions thrown on invalid input.

Exceptions

Name	Thrown on
`The`	string contains an invalid percent-encoding.

Parameters

Name	Description
s	The segment to append.

Remove the last segment

Synopsis

Declared in <include/boost/url/segments_encoded_ref.hpp>


void
pop_back() noexcept;

Description

This function removes the last segment from the container.

Iterators to the last segment as well as all end iterators are invalidated.


not this->empty()

Throws nothing.

Common functionality for containers

Synopsis

Declared in <include/boost/url/segments_base.hpp>


class segments_base;

Types

Name	Description
`const_iterator`	A Bidirectional iterator to a path segment
`const_reference`	The reference type
`difference_type`	A signed integer type used to represent differences.
`iterator`	A Bidirectional iterator to a path segment
`reference`	The reference type
`size_type`	An unsigned integer type used to represent size.
`value_type`	The value type

Member Functions

Name	Description
`back`	Return the last segment
`begin`	Return an iterator to the beginning
`buffer`	Return the referenced character buffer.
`empty`	Return true if there are no segments
`end`	Return an iterator to the end
`front`	Return the first segment
`is_absolute`	Returns true if this references an absolute path.
`size`	Return the number of segments

Static Member Functions

Name	Description
`max_size`	Return the maximum number of characters possible

Description

This base class is used by the library to provide common member functions for containers. This cannot be instantiated directly; Instead, use one of the containers or functions:

segments_ref

segments_view

segments_encoded_ref

segments_encoded_view

A Bidirectional iterator to a path segment

Synopsis

Declared in <include/boost/url/impl/segments_base.hpp>


class iterator;

Types

Name	Description
`difference_type`
`iterator_category`
`pointer`
`reference`
`value_type`

Member Functions

Name	Description
`iterator` [constructor]
`operator!=`
`operator*`
`operator++`
`operator--`
`operator->`
`operator=`
`operator==`

Description

Objects of this type allow iteration through the segments in the path. Any percent-escapes in returned strings are decoded first. The values returned are read-only; changes to segments must be made through the container instead, if the container supports modification.

The strings produced when iterators are dereferenced belong to the iterator and become invalidated when that particular iterator is incremented, decremented, or destroyed.

Synopsis

Declared in <include/boost/url/impl/segments_base.hpp>


using value_type = segments_base::value_type;

Synopsis

Declared in <include/boost/url/impl/segments_base.hpp>


using reference = segments_base::reference;

Synopsis

Declared in <include/boost/url/impl/segments_base.hpp>


using pointer = reference;

Synopsis

Declared in <include/boost/url/impl/segments_base.hpp>


using difference_type = segments_base::difference_type;

Synopsis

Declared in <include/boost/url/impl/segments_base.hpp>


using iterator_category = std::bidirectional_iterator_tag;

Synopsis

Declared in <include/boost/url/impl/segments_base.hpp>


constexpr
iterator() = default;

» more...


constexpr
iterator(iterator const&) = default;

» more...

Synopsis

Declared in <include/boost/url/impl/segments_base.hpp>


constexpr
iterator() = default;

Synopsis

Declared in <include/boost/url/impl/segments_base.hpp>


constexpr
iterator(iterator const&) = default;

Synopsis

Declared in <include/boost/url/impl/segments_base.hpp>


constexpr
iterator&
operator=(iterator const&) noexcept = default;

Synopsis

Declared in <include/boost/url/impl/segments_base.hpp>


reference
operator*() const;

Synopsis

Declared in <include/boost/url/impl/segments_base.hpp>


pointer
operator->() const = delete;

Synopsis

Declared in <include/boost/url/impl/segments_base.hpp>


iterator&
operator++() noexcept;

» more...


iterator
operator++(int) noexcept;

» more...

Synopsis

Declared in <include/boost/url/impl/segments_base.hpp>


iterator&
operator++() noexcept;

Synopsis

Declared in <include/boost/url/impl/segments_base.hpp>


iterator
operator++(int) noexcept;

Synopsis

Declared in <include/boost/url/impl/segments_base.hpp>


iterator&
operator--() noexcept;

» more...


iterator
operator--(int) noexcept;

» more...

Synopsis

Declared in <include/boost/url/impl/segments_base.hpp>


iterator&
operator--() noexcept;

Synopsis

Declared in <include/boost/url/impl/segments_base.hpp>


iterator
operator--(int) noexcept;

Synopsis

Declared in <include/boost/url/impl/segments_base.hpp>


bool
operator==(iterator const& other) const noexcept;

Synopsis

Declared in <include/boost/url/impl/segments_base.hpp>


bool
operator!=(iterator const& other) const noexcept;

A Bidirectional iterator to a path segment

Synopsis

Declared in <include/boost/url/segments_base.hpp>


using const_iterator = iterator;

Description

The strings produced when iterators are dereferenced belong to the iterator and become invalidated when that particular iterator is incremented, decremented, or destroyed.

The value type

Synopsis

Declared in <include/boost/url/segments_base.hpp>


using value_type = std::string;

Description

Values of this type represent a segment where unique ownership is retained by making a copy.


segments_base::value_type ps( url_view( "/path/to/file.txt" ).segments().back() );

The reference type

Synopsis

Declared in <include/boost/url/segments_base.hpp>


using reference = std::string;

Description

This is the type of value returned when iterators of the view are dereferenced.

The reference type

Synopsis

Declared in <include/boost/url/segments_base.hpp>


using const_reference = std::string;

Description

This is the type of value returned when iterators of the view are dereferenced.

An unsigned integer type used to represent size.

Synopsis

Declared in <include/boost/url/segments_base.hpp>


using size_type = std::size_t;

A signed integer type used to represent differences.

Synopsis

Declared in <include/boost/url/segments_base.hpp>


using difference_type = std::ptrdiff_t;

Return the maximum number of characters possible

Synopsis

Declared in <include/boost/url/segments_base.hpp>


constexpr
static
std::size_t
max_size() noexcept;

Description

This represents the largest number of characters that are possible in a path, not including any null terminator.

Throws nothing.

Return the referenced character buffer.

Synopsis

Declared in <include/boost/url/segments_base.hpp>


pct_string_view
buffer() const noexcept;

Description

This function returns the character buffer referenced by the view. The returned string may contain percent escapes.


assert( url_view( "/path/to/file.txt" ).segments().buffer() == "/path/to/file.txt" );

Constant.

Throws nothing.

Returns true if this references an absolute path.

Synopsis

Declared in <include/boost/url/segments_base.hpp>


bool
is_absolute() const noexcept;

Description

Absolute paths always start with a forward slash ('/').


assert( url_view( "/path/to/file.txt" ).segments().is_absolute() == true );

Constant.

Throws nothing.

Return true if there are no segments

Synopsis

Declared in <include/boost/url/segments_base.hpp>


bool
empty() const noexcept;

Description


assert( ! url_view( "/index.htm" ).segments().empty() );

Constant.

Throws nothing.

Return the number of segments

Synopsis

Declared in <include/boost/url/segments_base.hpp>


std::size_t
size() const noexcept;

Description


assert( url_view( "/path/to/file.txt" ).segments().size() == 3 );

Constant.

Throws nothing.

Return the first segment

Synopsis

Declared in <include/boost/url/segments_base.hpp>


std::string
front() const noexcept;

Description

This function returns a string with the first segment of the path without any leading or trailing '/' separators. Any percent-escapes in the string are decoded first.


this->empty() == false


return *begin();


assert( url_view( "/path/to/file.txt" ).segments().front() == "path" );

Linear in `this->front().size()`.

Calls to allocate may throw.

Return the last segment

Synopsis

Declared in <include/boost/url/segments_base.hpp>


std::string
back() const noexcept;

Description


this->empty() == false


assert( url_view( "/path/to/file.txt" ).segments().back() == "file.txt" );


this->empty() == false


return *--end();

Linear in `this->back().size()`.

Calls to allocate may throw.

Return an iterator to the beginning

Synopsis

Declared in <include/boost/url/segments_base.hpp>


iterator
begin() const noexcept;

Description

Linear in `this->front().size()` or

constant if `this->empty()`.

Throws nothing.

Return an iterator to the end

Synopsis

Declared in <include/boost/url/segments_base.hpp>


iterator
end() const noexcept;

Description

Constant.

Throws nothing.

A view representing path segments in a URL

Synopsis

Declared in <include/boost/url/segments_view.hpp>


class segments_view
    : public segments_base;

Types

Name	Description
`const_iterator`	A Bidirectional iterator to a path segment
`const_reference`	The reference type
`difference_type`	A signed integer type used to represent differences.
`iterator`	A Bidirectional iterator to a path segment
`reference`	The reference type
`size_type`	An unsigned integer type used to represent size.
`value_type`	The value type

Member Functions

Name	Description
`back`	Return the last segment
`begin`	Return an iterator to the beginning
`buffer`	Return the referenced character buffer.
`empty`	Return true if there are no segments
`end`	Return an iterator to the end
`front`	Return the first segment
`is_absolute`	Returns true if this references an absolute path.
`operator=`	Assignment
`segments_view` [constructor]	Constructor
`size`	Return the number of segments

Static Member Functions

Name	Description
`max_size`	Return the maximum number of characters possible

Description

Objects of this type are used to interpret the path as a bidirectional view of segment strings.


url_view u( "/path/to/file.txt" );

segments_view ps = u.segments();

assert( ps.buffer().data() == u.buffer().data() );

Percent escapes in strings returned when dereferencing iterators are automatically decoded.

Changes to the underlying character buffer

can invalidate iterators which reference it.

Synopsis

Declared in <include/boost/url/segments_view.hpp>


constexpr
segments_view() = default;

» more...


constexpr
segments_view(segments_view const& other) = default;

» more...


segments_view(core::string_view s);

» more...

Description

Default-constructed segments have zero elements.


segments_view ps;


return segments_view( "" );

Constant.

Throws nothing.

Exceptions

Name	Thrown on
`[object Object]`	contains an invalid path.

Parameters

Name	Description
s	The string to parse.

Constructor

Synopsis

Declared in <include/boost/url/segments_view.hpp>


constexpr
segments_view() = default;

Description

Default-constructed segments have zero elements.


segments_view ps;


return segments_view( "" );

Constant.

Throws nothing.

Constructor

Synopsis

Declared in <include/boost/url/segments_view.hpp>


constexpr
segments_view(segments_view const& other) = default;

Description

After construction, viewss reference the same underlying character buffer.

Ownership is not transferred; the caller is responsible for ensuring the lifetime of the buffer extends until it is no longer referenced.


this->buffer().data() == other.buffer().data()

Constant

Throws nothing

Constructor

Synopsis

Declared in <include/boost/url/segments_view.hpp>


segments_view(core::string_view s);

Description


segments_view ps( "/path/to/file.txt" );


return parse_path( s ).value();


this->buffer().data() == s.data()

Linear in `s`.

Exceptions thrown on invalid input.


path = [ "/" ] [ segment *( "/" segment ) ]

segment = *pchar

3.3. Path

Exceptions

Name	Thrown on
`s`	contains an invalid path.

Parameters

Name	Description
s	The string to parse.

Assignment

Synopsis

Declared in <include/boost/url/segments_view.hpp>


constexpr
segments_view&
operator=(segments_view const& other) = default;

Description

After assignment, both views reference the same underlying character buffer.

Ownership is not transferred; the caller is responsible for ensuring the lifetime of the buffer extends until it is no longer referenced.


this->buffer().data() == other.buffer().data()

Constant

Throws nothing

A view representing path segments in a URL

Synopsis

Declared in <include/boost/url/segments_ref.hpp>


class segments_ref
    : public segments_base;

Types

Name	Description
`const_iterator`	A Bidirectional iterator to a path segment
`const_reference`	The reference type
`difference_type`	A signed integer type used to represent differences.
`iterator`	A Bidirectional iterator to a path segment
`reference`	The reference type
`size_type`	An unsigned integer type used to represent size.
`value_type`	The value type

Member Functions

Name	Description
`assign`	Assign segments
`back`	Return the last segment
`begin`	Return an iterator to the beginning
`buffer`	Return the referenced character buffer.
`clear`	Clear the contents of the container
`empty`	Return true if there are no segments
`end`	Return an iterator to the end
`erase`	Erase segments
`front`	Return the first segment
`insert`	Insert segments
`is_absolute`	Returns true if this references an absolute path.
`operator segments_view`	Conversion
`operator=`	Assignment
`pop_back`	Remove the last segment
`push_back`	Append a segment
`replace`	Replace segments
`segments_ref` [constructor]	Constructor
`size`	Return the number of segments
`url`	Return the referenced url

Static Member Functions

Name	Description
`max_size`	Return the maximum number of characters possible

Description

Objects of this type are used to interpret the path as a bidirectional view of segments, where each segment is a string with percent escapes automatically decoded.

The view is modifiable; calling non-const members causes changes to the referenced url.


url u( "/path/to/file.txt" );

segments_ref ps = u.segments();

Percent escapes in strings returned when dereferencing iterators are automatically decoded. Reserved characters in strings supplied to modifier functions are automatically percent-escaped.

Changes to the underlying character buffer

can invalidate iterators which reference it. Modifications made through the container invalidate some or all iterators:

push_back : Only `end()`.

assign , clear , operator= : All elements.

erase : Erased elements and all elements after (including `end()`).

insert : All elements at or after the insertion point (including `end()`).

replace : Modified elements and all elements after (including `end()`).

Synopsis

Declared in <include/boost/url/segments_ref.hpp>


constexpr
segments_ref(segments_ref const& other) = default;

Description

After construction, both views reference the same url. Ownership is not transferred; the caller is responsible for ensuring the lifetime of the url extends until it is no longer referenced.


&this->url() == &other.url();

Constant.

Throws nothing.

Parameters

Name	Description
other	The other view.

Assignment

Synopsis

Declared in <include/boost/url/segments_ref.hpp>


segments_ref&
operator=(segments_ref const& other);

» more...


segments_ref&
operator=(segments_view const& other);

» more...


segments_ref&
operator=(std::initializer_list<core::string_view> init);

» more...

Description

The existing contents are replaced by a copy of the other segments.

All iterators are invalidated.

NOTE

None of the character buffers referenced by `other` may overlap the buffer of the underlying url, or else the behavior is undefined.


this->assign( other.begin(), other.end() );

Linear in `other.buffer().size()`.

Strong guarantee.

Calls to allocate may throw.

Parameters

Name	Description
other	The segments to assign.
init	The list of segments to assign.

Assignment

Synopsis

Declared in <include/boost/url/segments_ref.hpp>


segments_ref&
operator=(segments_ref const& other);

Description

The existing contents are replaced by a copy of the other segments.

All iterators are invalidated.

NOTE

None of the character buffers referenced by `other` may overlap the buffer of the underlying url, or else the behavior is undefined.


this->assign( other.begin(), other.end() );

Linear in `other.buffer().size()`.

Strong guarantee.

Calls to allocate may throw.

Parameters

Name	Description
other	The segments to assign.

Synopsis

Declared in <include/boost/url/segments_ref.hpp>


segments_ref&
operator=(segments_view const& other);

Assignment

Synopsis

Declared in <include/boost/url/segments_ref.hpp>


segments_ref&
operator=(std::initializer_list<core::string_view> init);

Description

The existing contents are replaced by a copy of the contents of the initializer list. Reserved characters in the list are automatically escaped.

All iterators are invalidated.


url u;

u.segments() = { "path", "to", "file.txt" };

None of the character buffers referenced

by the list may overlap the character buffer of the underlying url, or else the behavior is undefined.


this->assign( init.begin(), init.end() );

Linear in `init.size() + this->url().encoded_query().size() + this->url().encoded_fragment().size()`.

Strong guarantee.

Calls to allocate may throw.

Parameters

Name	Description
init	The list of segments to assign.

Conversion

Synopsis

Declared in <include/boost/url/segments_ref.hpp>


operator segments_view() const noexcept;

Synopsis

Declared in <include/boost/url/segments_ref.hpp>


url_base&
url() const noexcept;

Description

This function returns the url referenced by the view.


url u( "/path/to/file.txt" );

assert( &u.segments().url() == &u );

Throws nothing.

Clear the contents of the container

Synopsis

Declared in <include/boost/url/segments_ref.hpp>


void
clear() noexcept;

Description

All iterators are invalidated.


this->url().set_encoded_path( "" );


this->empty() == true

Linear in `this->url().encoded_query().size() + this->url().encoded_fragment().size()`.

Throws nothing.

Assign segments

Synopsis

Declared in <include/boost/url/segments_ref.hpp>


void
assign(std::initializer_list<core::string_view> init);

» more...


template<class FwdIt>
void
assign(
    FwdIt first,
    FwdIt last);

» more...

Description

The existing contents are replaced by a copy of the contents of the initializer list. Reserved characters in the list are automatically escaped.

All iterators are invalidated.

NOTE

None of the character buffers referenced by `init` may overlap the character buffer of the underlying url, or else the behavior is undefined.


url u;

u.segments().assign( { "path", "to", "file.txt" } );

Linear in `init.size() + this->url().encoded_query().size() + this->url().encoded_fragment().size()`.

Strong guarantee.

Calls to allocate may throw.

Parameters

Name	Description
init	The list of segments to assign.
first,	last The range of segments to assign.

Assign segments

Synopsis

Declared in <include/boost/url/segments_ref.hpp>


void
assign(std::initializer_list<core::string_view> init);

Description

The existing contents are replaced by a copy of the contents of the initializer list. Reserved characters in the list are automatically escaped.

All iterators are invalidated.

NOTE

None of the character buffers referenced by `init` may overlap the character buffer of the underlying url, or else the behavior is undefined.


url u;

u.segments().assign( { "path", "to", "file.txt" } );

Linear in `init.size() + this->url().encoded_query().size() + this->url().encoded_fragment().size()`.

Strong guarantee.

Calls to allocate may throw.

Parameters

Name	Description
init	The list of segments to assign.

Assign segments

Synopsis

Declared in <include/boost/url/segments_ref.hpp>


template<class FwdIt>
void
assign(
    FwdIt first,
    FwdIt last);

Description

The existing contents are replaced by a copy of the contents of the range. Reserved characters in the range are automatically escaped.

All iterators are invalidated.

NOTE

None of the character buffers referenced by the range may overlap the character buffer of the underlying url, or else the behavior is undefined.


std::is_convertible< std::iterator_traits< FwdIt >::reference_type, core::string_view >::value == true

Linear in `std::distance( first, last ) + this->url().encoded_query().size() + this->url().encoded_fragment().size()`.

Strong guarantee.

Calls to allocate may throw.

Parameters

Name	Description
first,	last The range of segments to assign.

Insert segments

Synopsis

Declared in <include/boost/url/segments_ref.hpp>


iterator
insert(
    iterator before,
    core::string_view s);

» more...


iterator
insert(
    iterator before,
    std::initializer_list<core::string_view> init);

» more...


template<class FwdIt>
iterator
insert(
    iterator before,
    FwdIt first,
    FwdIt last);

» more...

Description

This function inserts a segment before the specified position. Reserved characters in the segment are automatically escaped.

All iterators that are equal to `before` or come after are invalidated.

Linear in `s.size() + this->url().encoded_resource().size()`.

Strong guarantee.

Calls to allocate may throw.

Return Value

An iterator to the inserted segment.

Parameters

Name	Description
before	An iterator before which the segment is inserted. This may be equal to `end()`.
s	The segment to insert.
init	The list of segments to insert.
first,	last The range of segments to insert.

Insert segments

Synopsis

Declared in <include/boost/url/segments_ref.hpp>


iterator
insert(
    iterator before,
    core::string_view s);

Description

This function inserts a segment before the specified position. Reserved characters in the segment are automatically escaped.

All iterators that are equal to `before` or come after are invalidated.

Linear in `s.size() + this->url().encoded_resource().size()`.

Strong guarantee.

Calls to allocate may throw.

Return Value

An iterator to the inserted segment.

Parameters

Name	Description
before	An iterator before which the segment is inserted. This may be equal to `end()`.
s	The segment to insert.

Insert segments

Synopsis

Declared in <include/boost/url/segments_ref.hpp>


iterator
insert(
    iterator before,
    std::initializer_list<core::string_view> init);

Description

This function inserts the segments in an initializer list before the specified position. Reserved characters in the list are percent-escaped in the result.

All iterators that are equal to `before` or come after are invalidated.

NOTE

None of the character buffers referenced by the list may overlap the character buffer of the underlying url, or else the behavior is undefined.


url u( "/file.txt" );

u.segments().insert( u.segments().begin(), { "path", "to" } );

Linear in `init.size() + this->url().encoded_resource().size()`.

Strong guarantee.

Calls to allocate may throw.

Return Value

An iterator to the first element inserted, or `before` if `init.size() == 0`.

Parameters

Name	Description
before	An iterator before which the list is inserted. This may be equal to `end()`.
init	The list of segments to insert.

Insert segments

Synopsis

Declared in <include/boost/url/segments_ref.hpp>


template<class FwdIt>
iterator
insert(
    iterator before,
    FwdIt first,
    FwdIt last);

Description

This function inserts the segments in a range before the specified position. Reserved characters in the list are automatically escaped.

All iterators that are equal to `before` or come after are invalidated.

NOTE

None of the character buffers referenced by the range may overlap the character buffer of the underlying url, or else the behavior is undefined.


std::is_convertible< std::iterator_traits< FwdIt >::reference_type, core::string_view >::value == true

Linear in `std::distance( first, last ) + this->url().encoded_resource().size()`.

Strong guarantee.

Calls to allocate may throw.

Return Value

An iterator to the first segment inserted, or `before` if `init.empty()`.

Parameters

Name	Description
before	An iterator before which the range is inserted. This may be equal to `end()`.
first,	last The range of segments to insert.

Erase segments

Synopsis

Declared in <include/boost/url/segments_ref.hpp>


iterator
erase(iterator pos) noexcept;

» more...


iterator
erase(
    iterator first,
    iterator last) noexcept;

» more...

Description

This function removes a segment.

All iterators that are equal to `pos` or come after are invalidated.

Linear in `this->url().encoded_resource().size()`.

Throws nothing.

Return Value

An iterator to one past the removed segment.

Parameters

Name	Description
pos	An iterator to the segment.
first,	last The range of segments to erase.

Erase segments

Synopsis

Declared in <include/boost/url/segments_ref.hpp>


iterator
erase(iterator pos) noexcept;

Description

This function removes a segment.

All iterators that are equal to `pos` or come after are invalidated.

Linear in `this->url().encoded_resource().size()`.

Throws nothing.

Return Value

An iterator to one past the removed segment.

Parameters

Name	Description
pos	An iterator to the segment.

Erase segments

Synopsis

Declared in <include/boost/url/segments_ref.hpp>


iterator
erase(
    iterator first,
    iterator last) noexcept;

Description

This function removes a range of segments.

All iterators that are equal to `first` or come after are invalidated.

Linear in `this->url().encoded_resource().size()`.

Throws nothing.

Return Value

An iterator to one past the removed range.

Parameters

Name	Description
first,	last The range of segments to erase.

Replace segments

Synopsis

Declared in <include/boost/url/segments_ref.hpp>


iterator
replace(
    iterator pos,
    core::string_view s);

» more...


iterator
replace(
    iterator from,
    iterator to,
    core::string_view s);

» more...


iterator
replace(
    iterator from,
    iterator to,
    std::initializer_list<core::string_view> init);

» more...


template<class FwdIt>
iterator
replace(
    iterator from,
    iterator to,
    FwdIt first,
    FwdIt last);

» more...

Description

This function replaces the segment at the specified position. Reserved characters in the string are automatically escaped.

All iterators that are equal to `pos` or come after are invalidated.

Linear in `s.size() + this->url().encoded_resouce().size()`.

Strong guarantee.

Calls to allocate may throw.

Return Value

An iterator to the replaced segment.

Parameters

Name	Description
pos	An iterator to the segment.
s	The string to assign.
from,	to The range of segments to replace.
init	The list of segments to assign.
first,	last The range of segments to assign.

Replace segments

Synopsis

Declared in <include/boost/url/segments_ref.hpp>


iterator
replace(
    iterator pos,
    core::string_view s);

Description

This function replaces the segment at the specified position. Reserved characters in the string are automatically escaped.

All iterators that are equal to `pos` or come after are invalidated.

Linear in `s.size() + this->url().encoded_resouce().size()`.

Strong guarantee.

Calls to allocate may throw.

Return Value

An iterator to the replaced segment.

Parameters

Name	Description
pos	An iterator to the segment.
s	The string to assign.

Replace segments

Synopsis

Declared in <include/boost/url/segments_ref.hpp>


iterator
replace(
    iterator from,
    iterator to,
    core::string_view s);

Description

This function replaces a range of segments with one segment. Reserved characters in the string are automatically escaped.

All iterators that are equal to `from` or come after are invalidated.

Linear in `s.size() + this->url().encoded_resouce().size()`.

Strong guarantee.

Calls to allocate may throw.

Return Value

An iterator to the new segment.

Parameters

Name	Description
from,	to The range of segments to replace.
s	The string to assign.

Replace segments

Synopsis

Declared in <include/boost/url/segments_ref.hpp>


iterator
replace(
    iterator from,
    iterator to,
    std::initializer_list<core::string_view> init);

Description

This function replaces a range of segments with a list of segments in an initializer list. Reserved characters in the list are automatically escaped.

All iterators that are equal to `from` or come after are invalidated.

None of the character buffers referenced

by the list may overlap the character buffer of the underlying url, or else the behavior is undefined.

Linear in `init.size() + this->url().encoded_resouce().size()`.

Strong guarantee.

Calls to allocate may throw.

Return Value

An iterator to the first segment inserted, or one past `to` if `init.size() == 0`.

Parameters

Name	Description
from,	to The range of segments to replace.
init	The list of segments to assign.

Replace segments

Synopsis

Declared in <include/boost/url/segments_ref.hpp>


template<class FwdIt>
iterator
replace(
    iterator from,
    iterator to,
    FwdIt first,
    FwdIt last);

Description

This function replaces a range of segments with annother range of segments. Reserved characters in the new range are automatically escaped.

All iterators that are equal to `from` or come after are invalidated.

None of the character buffers referenced

by the new range may overlap the character buffer of the underlying url, or else the behavior is undefined.

Linear in `std::distance( first, last ) + this->url().encoded_resouce().size()`.

Strong guarantee.

Calls to allocate may throw.

Return Value

An iterator to the first segment inserted, or one past `to` if `init.size() == 0`.

Parameters

Name	Description
from,	to The range of segments to replace.
first,	last The range of segments to assign.

Append a segment

Synopsis

Declared in <include/boost/url/segments_ref.hpp>


void
push_back(core::string_view s);

Description

This function appends a segment to the end of the path. Reserved characters in the string are automatically escaped.

All end iterators are invalidated.


this->back() == s

Strong guarantee.

Calls to allocate may throw.

Parameters

Name	Description
s	The segment to append.

Remove the last segment

Synopsis

Declared in <include/boost/url/segments_ref.hpp>


void
pop_back() noexcept;

Description

This function removes the last segment from the container.

Iterators to the last segment as well as all end iterators are invalidated.


not this->empty()

Throws nothing.

Parse a string and return an encoded segment view

Synopsis

Declared in <include/boost/url/segments_encoded_view.hpp>


system::result<segments_encoded_view>
parse_path(core::string_view s) noexcept;

Description

This function parses the string and returns the corresponding path object if the string is valid, otherwise returns an error.


path          = [ "/" ] segment *( "/" segment )

No-throw guarantee.

3.3. Path (rfc3986)

Parse a string and return an encoded segment view

This function parses the string and returns the corresponding path object if the string is valid, otherwise returns an error.


path          = [ "/" ] segment *( "/" segment )

No-throw guarantee.

3.3. Path (rfc3986)

Return Value

A valid view on success, otherwise an error code.

Parameters

Name	Description
s	The string to parse
s	The string to parse

Synopsis

Declared in <include/boost/url/url_view_base.hpp>


class url_view_base;

Member Functions

Name	Description
`authority`	Return the authority
`buffer`	Return the url string
`compare`	Return the result of comparing this with another url
`data`	Return a pointer to the url's character buffer
`empty`	Return true if the url is empty
`encoded_authority`	Return the authority.
`encoded_fragment`	Return the fragment
`encoded_host`	Return the host
`encoded_host_address`	Return the host
`encoded_host_and_port`	Return the host and port
`encoded_host_name`	Return the host name
`encoded_origin`	Return the origin
`encoded_params`	Return the query as a container of parameters
`encoded_password`	Return the password
`encoded_path`	Return the path
`encoded_query`	Return the query
`encoded_resource`	Return the resource
`encoded_segments`	Return the path as a container of segments
`encoded_target`	Return the target
`encoded_user`	Return the user
`encoded_userinfo`	Return the userinfo
`encoded_zone_id`	Return the IPv6 Zone ID
`fragment`	Return the fragment
`has_authority`	Return true if an authority is present
`has_fragment`	Return true if a fragment is present
`has_password`	Return true if a password is present
`has_port`	Return true if a port is present
`has_query`	Return true if a query is present
`has_scheme`	Return true a scheme is present
`has_userinfo`	Return true if a userinfo is present
`host`	Return the host
`host_address`	Return the host
`host_ipv4_address`	Return the host IPv4 address
`host_ipv6_address`	Return the host IPv6 address
`host_ipvfuture`	Return the host IPvFuture address
`host_name`	Return the host name
`host_type`	Return the host type
`is_path_absolute`	Return true if the path is absolute
`operator core::string_view`	Return the URL as a core::string_view
`params`	Return the query as a container of parameters
`password`	Return the password
`path`	Return the path
`persist`	Return a shared, persistent copy of the url
`port`	Return the port
`port_number`	Return the port
`query`	Return the query
`scheme`	Return the scheme
`scheme_id`	Return the scheme
`segments`	Return the path as a container of segments
`size`	Return the number of characters in the url
`user`	Return the user
`userinfo`	Return the userinfo
`zone_id`	Return the IPv6 Zone ID

Static Member Functions

Name	Description
`max_size`	Return the maximum number of characters possible

Friends

Name	Description
`operator!=`	Return the result of comparing two URLs
`operator<`	Return the result of comparing two URLs
`operator<<`	Format the url to the output stream
`operator<=`	Return the result of comparing two URLs
`operator==`	Return the result of comparing two URLs
`operator>`	Return the result of comparing two URLs
`operator>=`	Return the result of comparing two URLs

Description

This base class is used by the library to provide common member functions for containers. This cannot be instantiated directly; Instead, use one of the containers or functions:

Return the maximum number of characters possible

Synopsis

Declared in <include/boost/url/url_view_base.hpp>


constexpr
static
std::size_t
max_size() noexcept;

Description

This represents the largest number of characters that are theoretically possible to represent in a url, not including any null terminator. In practice the actual possible size may be lower than this number.

Constant.

Throws nothing.

Return the number of characters in the url

Synopsis

Declared in <include/boost/url/url_view_base.hpp>


std::size_t
size() const noexcept;

Description

This function returns the number of characters in the url's encoded string, not including any null terminator, if present.


assert( url_view( "file:///Program%20Files" ).size() == 23 );

Constant.

Throws nothing.

Return true if the url is empty

Synopsis

Declared in <include/boost/url/url_view_base.hpp>


bool
empty() const noexcept;

Description

The empty string matches the relative-ref grammar.


assert( url_view( "" ).empty() );

Constant.

Throws nothing.


relative-ref  = relative-part [ "?" query ] [ "#" fragment ]

relative-part = "//" authority path-abempty
              / path-absolute
              / path-noscheme
              / path-empty

4.2. Relative Reference (rfc3986)

Return a pointer to the url's character buffer

Synopsis

Declared in <include/boost/url/url_view_base.hpp>


char const*
data() const noexcept;

Description

This function returns a pointer to the first character of the url, which is not guaranteed to be null-terminated.

Constant.

Throws nothing.

Return the url string

Synopsis

Declared in <include/boost/url/url_view_base.hpp>


core::string_view
buffer() const noexcept;

Description

This function returns the entire url, which may contain percent escapes.


assert( url_view( "http://www.example.com" ).buffer() == "http://www.example.com" );

Constant.

Throws nothing.

Return the URL as a core::string_view

Synopsis

Declared in <include/boost/url/url_view_base.hpp>


operator core::string_view() const noexcept;

Description

Constant.

Throws nothing.

Return a shared, persistent copy of the url

Synopsis

Declared in <include/boost/url/url_view_base.hpp>


std::shared_ptr<url_view const>
persist() const;

Description

This function returns a read-only copy of the url, with shared lifetime. The returned value owns (persists) the underlying string. The algorithm used to create the value minimizes the number of individual memory allocations, making it more efficient than when using direct standard library functions.


std::shared_ptr< url_view const > sp;
{
    std::string s( "http://example.com" );
    url_view u( s );                        // u references characters in s

    assert( u.data() == s.data() );         // same buffer

    sp = u.persist();

    assert( sp->data() != s.data() );       // different buffer
    assert( sp->buffer() == s);             // same contents

    // s is destroyed and thus u
    // becomes invalid, but sp remains valid.
}

Linear in `this->size()`.

Calls to allocate may throw.

Return true a scheme is present

Synopsis

Declared in <include/boost/url/url_view_base.hpp>


bool
has_scheme() const noexcept;

Description

This function returns true if this contains a scheme.


assert( url_view( "http://www.example.com" ).has_scheme() );

Constant.

Throws nothing.


URI             = scheme ":" hier-part [ "?" query ] [ "#" fragment ]

absolute-URI    = scheme ":" hier-part [ "?" query ]

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

3.1. Scheme (rfc3986)

Synopsis

Declared in <include/boost/url/url_view_base.hpp>


core::string_view
scheme() const noexcept;

Description

This function returns the scheme if it exists, without a trailing colon (':'). Otherwise it returns an empty string. Note that schemes are case-insensitive, and the canonical form is lowercased.


assert( url_view( "http://www.example.com" ).scheme() == "http" );

Throws nothing.


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

URI             = scheme ":" hier-part [ "?" query ] [ "#" fragment ]

absolute-URI    = scheme ":" hier-part [ "?" query ]

3.1. Scheme (rfc3986)

Synopsis

Declared in <include/boost/url/url_view_base.hpp>


urls::scheme
scheme_id() const noexcept;

Description

This function returns a value which depends on the scheme in the url:

If the scheme is a well-known scheme, corresponding value from the enumeration urls::scheme is returned.

If a scheme is present but is not a well-known scheme, the value returned is urls::scheme::unknown .

Otherwise, if the scheme is absent the value returned is urls::scheme::none .


assert( url_view( "wss://www.example.com/crypto.cgi" ).scheme_id() == scheme::wss );

Constant.

Throws nothing.


URI             = scheme ":" hier-part [ "?" query ] [ "#" fragment ]

absolute-URI    = scheme ":" hier-part [ "?" query ]

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

3.1. Scheme (rfc3986)

Synopsis

Declared in <include/boost/url/url_view_base.hpp>


bool
has_authority() const noexcept;

Description

This function returns true if the url contains an authority. The presence of an authority is denoted by a double slash ("//") at the beginning or after the scheme.


assert( url_view( "http://www.example.com/index.htm" ).has_authority() );

Constant.

Throws nothing.


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

URI             = scheme ":" hier-part [ "?" query ] [ "#" fragment ]

absolute-URI    = scheme ":" hier-part [ "?" query ]

URI-reference   = URI / relative-ref

relative-ref    = relative-part [ "?" query ] [ "#" fragment ]

hier-part       = "//" authority path-abempty
                ; (more...)

relative-part   = "//" authority path-abempty
                ; (more...)

3.2. Authority (rfc3986)

Synopsis

Declared in <include/boost/url/url_view_base.hpp>


authority_view
authority() const noexcept;

Description

This function returns the authority as an authority_view .


authority_view a = url_view( "https://www.example.com:8080/index.htm" ).authority();

Constant.

Throws nothing.


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

3.2. Authority (rfc3986)

Synopsis

Declared in <include/boost/url/url_view_base.hpp>


pct_string_view
encoded_authority() const noexcept;

Description

If present, this function returns a string representing the authority (which may be empty). Otherwise it returns an empty string. The returned string may contain percent escapes.


assert( url_view( "file://Network%20Drive/My%2DFiles" ).encoded_authority() == "Network%20Drive" );

Constant.

Throws nothing.


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

3.2. Authority (rfc3986)

Synopsis

Declared in <include/boost/url/url_view_base.hpp>


bool
has_userinfo() const noexcept;

Description

This function returns true if this contains a userinfo.


assert( url_view( "http://jane%2Ddoe:pass@example.com" ).has_userinfo() );

Constant.

Throws nothing.


userinfo    = user [ ":" [ password ] ]

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

3.2.1. User Information (rfc3986)

Synopsis

Declared in <include/boost/url/url_view_base.hpp>


bool
has_password() const noexcept;

Description

This function returns true if the userinfo is present and contains a password.


assert( url_view( "http://jane%2Ddoe:pass@example.com" ).has_password() );

Constant.

Throws nothing.


userinfo    = user [ ":" [ password ] ]

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

3.2.1. User Information (rfc3986)

Synopsis

Declared in <include/boost/url/url_view_base.hpp>


template<class StringToken = string_token::return_string>
StringToken::result_type
userinfo(StringToken&& token) const;

Description

If present, this function returns a string representing the userinfo (which may be empty). Otherwise it returns an empty string. Any percent-escapes in the string are decoded first.

NOTE

This function uses the string token return type customization. Depending on the token passed, the return type and behavior of the function can be different. See string_token::return_string for more information.


assert( url_view( "http://jane%2Ddoe:pass@example.com" ).userinfo() == "jane-doe:pass" );

Linear in `this->userinfo().size()`.

Calls to allocate may throw.


userinfo    = user [ ":" [ password ] ]

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

3.2.1. User Information (rfc3986)

Return Value

When called with no arguments, a value of type `std::string` is returned. Otherwise, the return type and meaning depends on the string token passed to the function.

Synopsis

Declared in <include/boost/url/url_view_base.hpp>


pct_string_view
encoded_userinfo() const noexcept;

Description

If present, this function returns a string representing the userinfo (which may be empty). Otherwise it returns an empty string. The returned string may contain percent escapes.


assert( url_view( "http://jane%2Ddoe:pass@example.com" ).encoded_userinfo() == "jane%2Ddoe:pass" );

Constant.

Throws nothing


userinfo    = user [ ":" [ password ] ]

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

3.2.1. User Information (rfc3986)

Synopsis

Declared in <include/boost/url/url_view_base.hpp>


template<class StringToken = string_token::return_string>
StringToken::result_type
user(StringToken&& token) const;

Description

If present, this function returns a string representing the user (which may be empty). Otherwise it returns an empty string. Any percent-escapes in the string are decoded first.


assert( url_view( "http://jane%2Ddoe:pass@example.com" ).user() == "jane-doe" );

Linear in `this->user().size()`.

Calls to allocate may throw.


userinfo    = user [ ":" [ password ] ]

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

3.2.1. User Information (rfc3986)

Synopsis

Declared in <include/boost/url/url_view_base.hpp>


pct_string_view
encoded_user() const noexcept;

Description

If present, this function returns a string representing the user (which may be empty). Otherwise it returns an empty string. The returned string may contain percent escapes.


assert( url_view( "http://jane%2Ddoe:pass@example.com" ).encoded_user() == "jane%2Ddoe" );

Constant.

Throws nothing.


userinfo    = user [ ":" [ password ] ]

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

3.2.1. User Information (rfc3986)

Synopsis

Declared in <include/boost/url/url_view_base.hpp>


template<class StringToken = string_token::return_string>
StringToken::result_type
password(StringToken&& token) const;

Description

If present, this function returns a string representing the password (which may be an empty string). Otherwise it returns an empty string. Any percent-escapes in the string are decoded first.


assert( url_view( "http://jane%2Ddoe:pass@example.com" ).password() == "pass" );

Linear in `this->password().size()`.

Calls to allocate may throw.


userinfo    = user [ ":" [ password ] ]

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

3.2.1. User Information (rfc3986)

Synopsis

Declared in <include/boost/url/url_view_base.hpp>


pct_string_view
encoded_password() const noexcept;

Description

This function returns the password portion of the userinfo as a percent-encoded string.


assert( url_view( "http://jane%2Ddoe:pass@example.com" ).encoded_password() == "pass" );

Constant.

Throws nothing.


userinfo    = user [ ":" [ password ] ]

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

3.2.1. User Information (rfc3986)

Synopsis

Declared in <include/boost/url/url_view_base.hpp>


urls::host_type
host_type() const noexcept;

Description

This function returns one of the following constants representing the type of host present.

When has_authority is false, the host type is host_type::none .


assert( url_view( "https://192.168.0.1/local.htm" ).host_type() == host_type::ipv4 );

Constant.

Throws nothing.

3.2.2. Host (rfc3986)

Return the host

Synopsis

Declared in <include/boost/url/url_view_base.hpp>


template<class StringToken = string_token::return_string>
StringToken::result_type
host(StringToken&& token) const;

Description

This function returns the host portion of the authority as a string, or the empty string if there is no authority. Any percent-escapes in the string are decoded first.


assert( url_view( "https://www%2droot.example.com/" ).host() == "www-root.example.com" );

Linear in `this->host().size()`.

Calls to allocate may throw.


host        = IP-literal / IPv4address / reg-name

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

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

3.2.2. Host (rfc3986)

Return the host

Synopsis

Declared in <include/boost/url/url_view_base.hpp>


pct_string_view
encoded_host() const noexcept;

Description

This function returns the host portion of the authority as a string, or the empty string if there is no authority. The returned string may contain percent escapes.


assert( url_view( "https://www%2droot.example.com/" ).encoded_host() == "www%2droot.example.com" );

Constant.

Throws nothing.


host        = IP-literal / IPv4address / reg-name

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

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

3.2.2. Host (rfc3986)

Return the host

Synopsis

Declared in <include/boost/url/url_view_base.hpp>


template<class StringToken = string_token::return_string>
StringToken::result_type
host_address(StringToken&& token) const;

Description

The value returned by this function depends on the type of host returned from the function host_type .

If the type is host_type::ipv4 , then the IPv4 address string is returned.

If the type is host_type::ipv6 , then the IPv6 address string is returned, without any enclosing brackets.

If the type is host_type::ipvfuture , then the IPvFuture address string is returned, without any enclosing brackets.

If the type is host_type::name , then the host name string is returned. Any percent-escapes in the string are decoded first.

If the type is host_type::none , then an empty string is returned.


assert( url_view( "https://[1::6:c0a8:1]/" ).host_address() == "1::6:c0a8:1" );

Linear in `this->host_address().size()`.

Calls to allocate may throw.


host        = IP-literal / IPv4address / reg-name

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

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

3.2.2. Host (rfc3986)

Return the host

Synopsis

Declared in <include/boost/url/url_view_base.hpp>


pct_string_view
encoded_host_address() const noexcept;

Description

The value returned by this function depends on the type of host returned from the function host_type .

If the type is host_type::ipv4 , then the IPv4 address string is returned.

If the type is host_type::ipv6 , then the IPv6 address string is returned, without any enclosing brackets.

If the type is host_type::ipvfuture , then the IPvFuture address string is returned, without any enclosing brackets.

If the type is host_type::name , then the host name string is returned. Any percent-escapes in the string are decoded first.

If the type is host_type::none , then an empty string is returned. The returned string may contain percent escapes.


assert( url_view( "https://www%2droot.example.com/" ).encoded_host_address() == "www%2droot.example.com" );

Constant.

Throws nothing.


host        = IP-literal / IPv4address / reg-name

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

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

3.2.2. Host (rfc3986)

Return the host IPv4 address

Synopsis

Declared in <include/boost/url/url_view_base.hpp>


ipv4_address
host_ipv4_address() const noexcept;

Description


assert( url_view( "http://127.0.0.1/index.htm?user=win95" ).host_ipv4_address() == ipv4_address( "127.0.0.1" ) );

Constant.

Throws nothing.


IPv4address = dec-octet "." dec-octet "." dec-octet "." dec-octet

dec-octet   = DIGIT                 ; 0-9
            / %x31-39 DIGIT         ; 10-99
            / "1" 2DIGIT            ; 100-199
            / "2" %x30-34 DIGIT     ; 200-249
            / "25" %x30-35          ; 250-255

3.2.2. Host (rfc3986)

Return the host IPv6 address

Synopsis

Declared in <include/boost/url/url_view_base.hpp>


ipv6_address
host_ipv6_address() const noexcept;

Description


assert( url_view( "ftp://[::1]/" ).host_ipv6_address() == ipv6_address( "::1" ) );

Constant.

Throws nothing.


IPv6address =                            6( h16 ":" ) ls32
            /                       "::" 5( h16 ":" ) ls32
            / [               h16 ] "::" 4( h16 ":" ) ls32
            / [ *1( h16 ":" ) h16 ] "::" 3( h16 ":" ) ls32
            / [ *2( h16 ":" ) h16 ] "::" 2( h16 ":" ) ls32
            / [ *3( h16 ":" ) h16 ] "::"    h16 ":"   ls32
            / [ *4( h16 ":" ) h16 ] "::"              ls32
            / [ *5( h16 ":" ) h16 ] "::"              h16
            / [ *6( h16 ":" ) h16 ] "::"

ls32        = ( h16 ":" h16 ) / IPv4address
            ; least-significant 32 bits of address

h16         = 1*4HEXDIG
            ; 16 bits of address represented in hexadecimal

3.2.2. Host (rfc3986)

Return the host IPvFuture address

Synopsis

Declared in <include/boost/url/url_view_base.hpp>


core::string_view
host_ipvfuture() const noexcept;

Description

If the host type is host_type::ipvfuture , this function returns the address as a string. Otherwise, if the host type is not an IPvFuture address, it returns an empty string.


assert( url_view( "http://[v1fe.d:9]/index.htm" ).host_ipvfuture() == "v1fe.d:9" );

Constant.

Throws nothing.


IPvFuture  = "v" 1*HEXDIG "." 1*( unreserved / sub-delims / ":" )

3.2.2. Host (rfc3986)

Return the host name

Synopsis

Declared in <include/boost/url/url_view_base.hpp>


template<class StringToken = string_token::return_string>
StringToken::result_type
host_name(StringToken&& token) const;

Description

If the host type is host_type::name , this function returns the name as a string. Otherwise an empty string is returned. Any percent-escapes in the string are decoded first.


assert( url_view( "https://www%2droot.example.com/" ).host_name() == "www-root.example.com" );

Linear in `this->host_name().size()`.

Calls to allocate may throw.


host        = IP-literal / IPv4address / reg-name

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

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

3.2.2. Host (rfc3986)

Return the host name

Synopsis

Declared in <include/boost/url/url_view_base.hpp>


pct_string_view
encoded_host_name() const noexcept;

Description


assert( url_view( "https://www%2droot.example.com/" ).encoded_host_name() == "www%2droot.example.com" );

Constant.

Throws nothing.


host        = IP-literal / IPv4address / reg-name

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

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

3.2.2. Host (rfc3986)

Return the IPv6 Zone ID

Synopsis

Declared in <include/boost/url/url_view_base.hpp>


template<class StringToken = string_token::return_string>
StringToken::result_type
zone_id(StringToken&& token) const;

Description

If the host type is host_type::ipv6 , this function returns the Zone ID as a string. Otherwise an empty string is returned. Any percent-escapes in the string are decoded first.


assert( url_view( "http://[fe80::1%25eth0]/" ).zone_id() == "eth0" );

Linear in `this->encoded_zone_id().size()`.

Calls to allocate may throw.


host        = IP-literal / IPv4address / reg-name

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

ZoneID = 1*( unreserved / pct-encoded )

IPv6addrz = IPv6address "%25" ZoneID

Representing IPv6 Zone Identifiers in Address Literals and Uniform Resource Identifiers

Return the IPv6 Zone ID

Synopsis

Declared in <include/boost/url/url_view_base.hpp>


pct_string_view
encoded_zone_id() const noexcept;

Description

If the host type is host_type::ipv6 , this function returns the Zone ID as a string. Otherwise an empty string is returned. The returned string may contain percent escapes.


assert( url_view( "http://[fe80::1%25eth0]/" ).encoded_zone_id() == "eth0" );

Constant.

Throws nothing.


host        = IP-literal / IPv4address / reg-name

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

ZoneID = 1*( unreserved / pct-encoded )

IPv6addrz = IPv6address "%25" ZoneID

Representing IPv6 Zone Identifiers in Address Literals and Uniform Resource Identifiers

Return true if a port is present

Synopsis

Declared in <include/boost/url/url_view_base.hpp>


bool
has_port() const noexcept;

Description

This function returns true if an authority is present and contains a port.


assert( url_view( "wss://www.example.com:443" ).has_port() );

Constant.

Throws nothing.


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

port        = *DIGIT

3.2.3. Port (rfc3986)

Synopsis

Declared in <include/boost/url/url_view_base.hpp>


core::string_view
port() const noexcept;

Description

If present, this function returns a string representing the port (which may be empty). Otherwise it returns an empty string.


assert( url_view( "http://localhost.com:8080" ).port() == "8080" );

Constant.

Throws nothing.


port        = *DIGIT

3.2.3. Port (rfc3986)

Synopsis

Declared in <include/boost/url/url_view_base.hpp>


std::uint16_t
port_number() const noexcept;

Description

If a port is present and the numerical value is representable, it is returned as an unsigned integer. Otherwise, the number zero is returned.


assert( url_view( "http://localhost.com:8080" ).port_number() == 8080 );

Constant.

Throws nothing.


port        = *DIGIT

3.2.3. Port (rfc3986)

Synopsis

Declared in <include/boost/url/url_view_base.hpp>


bool
is_path_absolute() const noexcept;

Description

This function returns true if the path begins with a forward slash ('/').


assert( url_view( "/path/to/file.txt" ).is_path_absolute() );

Constant.

Throws nothing.


path          = path-abempty    ; begins with "/" or is empty
              / path-absolute   ; begins with "/" but not "//"
              / path-noscheme   ; begins with a non-colon segment
              / path-rootless   ; begins with a segment
              / path-empty      ; zero characters

path-abempty  = *( "/" segment )
path-absolute = "/" [ segment-nz *( "/" segment ) ]
path-noscheme = segment-nz-nc *( "/" segment )
path-rootless = segment-nz *( "/" segment )
path-empty    = 0

3.3. Path (rfc3986)

Synopsis

Declared in <include/boost/url/url_view_base.hpp>


template<class StringToken = string_token::return_string>
StringToken::result_type
path(StringToken&& token) const;

Description

This function returns the path as a string. The path may be empty. Any percent-escapes in the string are decoded first.


assert( url_view( "file:///Program%20Files/Games/config.ini" ).path() == "/Program Files/Games/config.ini" );

Linear in `this->path().size()`.

Calls to allocate may throw.


path          = path-abempty    ; begins with "/" or is empty
              / path-absolute   ; begins with "/" but not "//"
              / path-noscheme   ; begins with a non-colon segment
              / path-rootless   ; begins with a segment
              / path-empty      ; zero characters

path-abempty  = *( "/" segment )
path-absolute = "/" [ segment-nz *( "/" segment ) ]
path-noscheme = segment-nz-nc *( "/" segment )
path-rootless = segment-nz *( "/" segment )
path-empty    = 0

3.3. Path (rfc3986)

Synopsis

Declared in <include/boost/url/url_view_base.hpp>


pct_string_view
encoded_path() const noexcept;

Description

This function returns the path as a string. The path may be empty. Any percent-escapes in the string are decoded first.


assert( url_view( "file:///Program%20Files/Games/config.ini" ).encoded_path() == "/Program%20Files/Games/config.ini" );

Constant.

Throws nothing.


path          = path-abempty    ; begins with "/" or is empty
              / path-absolute   ; begins with "/" but not "//"
              / path-noscheme   ; begins with a non-colon segment
              / path-rootless   ; begins with a segment
              / path-empty      ; zero characters

path-abempty  = *( "/" segment )
path-absolute = "/" [ segment-nz *( "/" segment ) ]
path-noscheme = segment-nz-nc *( "/" segment )
path-rootless = segment-nz *( "/" segment )
path-empty    = 0

3.3. Path (rfc3986)

Synopsis

Declared in <include/boost/url/url_view_base.hpp>


segments_view
segments() const noexcept;

Description


segments_view sv = url_view( "/path/to/file.txt" ).segments();

Constant.

Throws nothing.


path          = [ "/" ] segment *( "/" segment )

3.3. Path (rfc3986)

Synopsis

Declared in <include/boost/url/url_view_base.hpp>


segments_encoded_view
encoded_segments() const noexcept;

Description


segments_encoded_view sv = url_view( "/path/to/file.txt" ).encoded_segments();

Constant.

Throws nothing.


path          = path-abempty    ; begins with "/" or is empty
              / path-absolute   ; begins with "/" but not "//"
              / path-noscheme   ; begins with a non-colon segment
              / path-rootless   ; begins with a segment
              / path-empty      ; zero characters

path-abempty  = *( "/" segment )
path-absolute = "/" [ segment-nz *( "/" segment ) ]
path-noscheme = segment-nz-nc *( "/" segment )
path-rootless = segment-nz *( "/" segment )
path-empty    = 0

3.3. Path (rfc3986)

Synopsis

Declared in <include/boost/url/url_view_base.hpp>


bool
has_query() const noexcept;

Description

This function returns true if this contains a query. An empty query is distinct from having no query.


assert( url_view( "/sql?id=42&col=name&page-size=20" ).has_query() );

Constant.

Throws nothing.


query           = *( pchar / "/" / "?" )

query-param     = key [ "=" value ]
query-params    = [ query-param ] *( "&" query-param )

://en.wikipedia.org/wiki/Query_string" >Query string (Wikipedia)

Synopsis

Declared in <include/boost/url/url_view_base.hpp>


template<class StringToken = string_token::return_string>
StringToken::result_type
query(StringToken&& token) const;

Description

If this contains a query, it is returned as a string (which may be empty). Otherwise, an empty string is returned. Any percent-escapes in the string are decoded first. When plus signs appear in the query portion of the url, they are converted to spaces automatically upon decoding. This behavior can be changed by setting decode options.


assert( url_view( "/sql?id=42&name=jane%2Ddoe&page+size=20" ).query() == "id=42&name=jane-doe&page size=20" );

Linear in `this->query().size()`.

Calls to allocate may throw.


query           = *( pchar / "/" / "?" )

query-param     = key [ "=" value ]
query-params    = [ query-param ] *( "&" query-param )

://en.wikipedia.org/wiki/Query_string" >Query string (Wikipedia)

Synopsis

Declared in <include/boost/url/url_view_base.hpp>


pct_string_view
encoded_query() const noexcept;

Description

If this contains a query, it is returned as a string (which may be empty). Otherwise, an empty string is returned. The returned string may contain percent escapes.


assert( url_view( "/sql?id=42&name=jane%2Ddoe&page+size=20" ).encoded_query() == "id=42&name=jane%2Ddoe&page+size=20" );

Constant.

Throws nothing.


query           = *( pchar / "/" / "?" )

query-param     = key [ "=" value ]
query-params    = [ query-param ] *( "&" query-param )

://en.wikipedia.org/wiki/Query_string" >Query string (Wikipedia)

Synopsis

Declared in <include/boost/url/url_view_base.hpp>


params_view
params() const noexcept;

» more...


params_view
params(encoding_opts opt) const noexcept;

» more...

Description


params_view pv = url_view( "/sql?id=42&name=jane%2Ddoe&page+size=20" ).params();

Constant.

Throws nothing.


query           = *( pchar / "/" / "?" )

query-param     = key [ "=" value ]
query-params    = [ query-param ] *( "&" query-param )

://en.wikipedia.org/wiki/Query_string" >Query string (Wikipedia)

Synopsis

Declared in <include/boost/url/url_view_base.hpp>


params_view
params() const noexcept;

Description


params_view pv = url_view( "/sql?id=42&name=jane%2Ddoe&page+size=20" ).params();

Constant.

Throws nothing.


query           = *( pchar / "/" / "?" )

query-param     = key [ "=" value ]
query-params    = [ query-param ] *( "&" query-param )

://en.wikipedia.org/wiki/Query_string" >Query string (Wikipedia)

Synopsis

Declared in <include/boost/url/url_view_base.hpp>


params_view
params(encoding_opts opt) const noexcept;

Return the query as a container of parameters

Synopsis

Declared in <include/boost/url/url_view_base.hpp>


params_encoded_view
encoded_params() const noexcept;

Description

This function returns a bidirectional view of key/value pairs over the query. The returned view references the same underlying character buffer; ownership is not transferred. Strings returned when iterating the range may contain percent escapes.


params_encoded_view pv = url_view( "/sql?id=42&name=jane%2Ddoe&page+size=20" ).encoded_params();

Constant.

Throws nothing.

3.4. Query (rfc3986)


query           = *( pchar / "/" / "?" )

query-param     = key [ "=" value ]
query-params    = [ query-param ] *( "&" query-param )

://en.wikipedia.org/wiki/Query_string" >Query string (Wikipedia)

Synopsis

Declared in <include/boost/url/url_view_base.hpp>


bool
has_fragment() const noexcept;

Description

This function returns true if the url contains a fragment. An empty fragment is distinct from no fragment.


assert( url_view( "http://www.example.com/index.htm#anchor" ).has_fragment() );

Constant.

Throws nothing.


URI           = scheme ":" hier-part [ "?" query ] [ "#" fragment ]

relative-ref  = relative-part [ "?" query ] [ "#" fragment ]

3.5. Fragment (rfc3986)

Synopsis

Declared in <include/boost/url/url_view_base.hpp>


template<class StringToken = string_token::return_string>
StringToken::result_type
fragment(StringToken&& token) const;

Description

This function calculates the fragment of the url, with percent escapes decoded and without the leading pound sign ('#') whose presence indicates that the url contains a fragment.

This function accepts an optional StringToken parameter which controls the return type and behavior of the function:

When called with no arguments, the return type of the function is `std::string`. Otherwise

When called with a string token, the behavior and return type of the function depends on the type of string token being passed.


assert( url_view( "http://www.example.com/index.htm#a%2D1" ).fragment() == "a-1" );

Linear in `this->fragment().size()`.

Calls to allocate may throw.

String tokens may throw exceptions.


fragment        = *( pchar / "/" / "?" )

fragment-part   = [ "#" fragment ]

3.5. Fragment (rfc3986)

Parameters

Name	Description
token	An optional string token to use. If this parameter is omitted, the function returns a new `std::string`.

Synopsis

Declared in <include/boost/url/url_view_base.hpp>


pct_string_view
encoded_fragment() const noexcept;

Description

This function returns the fragment as a string with percent-escapes. Ownership is not transferred; the string returned references the underlying character buffer, which must remain valid or else undefined behavior occurs.


assert( url_view( "http://www.example.com/index.htm#a%2D1" ).encoded_fragment() == "a%2D1" );

Constant.

Throws nothing.


fragment        = *( pchar / "/" / "?" )

pchar           = unreserved / pct-encoded / sub-delims / ":" / "@"

3.5. Fragment (rfc3986)

Synopsis

Declared in <include/boost/url/url_view_base.hpp>


pct_string_view
encoded_host_and_port() const noexcept;

Description

If an authority is present, this function returns the host and optional port as a string, which may be empty. Otherwise it returns an empty string. The returned string may contain percent escapes.


assert( url_view( "http://www.example.com:8080/index.htm" ).encoded_host_and_port() == "www.example.com:8080" );

Constant.

Throws nothing.


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

3.2.2. Host (rfc3986)

3.2.3. Port (rfc3986)

Synopsis

Declared in <include/boost/url/url_view_base.hpp>


pct_string_view
encoded_origin() const noexcept;

Description

If an authority is present, this function returns the scheme and authority portion of the url. Otherwise, an empty string is returned. The returned string may contain percent escapes.


assert( url_view( "http://www.example.com:8080/index.htm?text=none#h1" ).encoded_origin() == "http://www.example.com:8080" );

Constant.

Throws nothing.

Synopsis

Declared in <include/boost/url/url_view_base.hpp>


pct_string_view
encoded_resource() const noexcept;

Description

This function returns the resource, which is the portion of the url that includes only the path, query, and fragment. The returned string may contain percent escapes.


assert( url_view( "http://www.example.com/index.html?query#frag" ).encoded_resource() == "/index.html?query#frag" );

Constant.

Throws nothing.

3.3. Path (rfc3986)

3.4. Query (rfc3986)

Synopsis

Declared in <include/boost/url/url_view_base.hpp>


pct_string_view
encoded_target() const noexcept;

Description

This function returns the target, which is the portion of the url that includes only the path and query. The returned string may contain percent escapes.


assert( url_view( "http://www.example.com/index.html?query#frag" ).encoded_target() == "/index.html?query" );

Constant.

Throws nothing.

3.3. Path (rfc3986)

3.4. Query (rfc3986)

Synopsis

Declared in <include/boost/url/url_view_base.hpp>


int
compare(url_view_base const& other) const noexcept;

Description

This function compares two URLs according to Syntax-Based comparison algorithm.

Linear in `min( u0.size(), u1.size() )`

Throws nothing.

6.2.2 Syntax-Based Normalization (rfc3986)

Return Value

-1 if `*this < other`, 0 if `this == other`, and 1 if `this > other`.

Return the result of comparing two URLs

Synopsis

Declared in <include/boost/url/url_view_base.hpp>


friend
bool
operator==(
    url_view_base const& u0,
    url_view_base const& u1) noexcept;

Description

The URLs are compared component by component as if they were first normalized.


url_view u0( "http://www.a.com/index.htm" );
url_view u1( "http://www.a.com/index.htm" );
assert( u0 == u1 );


url a(u0);
a.normalize();
url b(u1);
b.normalize();
return a.buffer() == b.buffer();

Linear in `min( u0.size(), u1.size() )`

Throws nothing

6.2.2 Syntax-Based Normalization (rfc3986)

Return Value

`true` if `u0 == u1`

Return the result of comparing two URLs

Synopsis

Declared in <include/boost/url/url_view_base.hpp>


friend
bool
operator!=(
    url_view_base const& u0,
    url_view_base const& u1) noexcept;

Description

The URLs are compared component by component as if they were first normalized.


url_view u0( "http://www.a.com/index.htm" );
url_view u1( "http://www.b.com/index.htm" );
assert( u0 != u1 );


url a(u0);
a.normalize();
url b(u1);
b.normalize();
return a.buffer() != b.buffer();

Linear in `min( u0.size(), u1.size() )`

Throws nothing

6.2.2 Syntax-Based Normalization (rfc3986)

Return Value

`true` if `u0 != u1`

Return the result of comparing two URLs

Synopsis

Declared in <include/boost/url/url_view_base.hpp>


friend
bool
operator<(
    url_view_base const& u0,
    url_view_base const& u1) noexcept;

Description

The URLs are compared component by component as if they were first normalized.


url_view u0( "http://www.a.com/index.htm" );
url_view u1( "http://www.b.com/index.htm" );
assert( u0 < u1 );


url a(u0);
a.normalize();
url b(u1);
b.normalize();
return a.buffer() < b.buffer();

Linear in `min( u0.size(), u1.size() )`

Throws nothing

6.2.2 Syntax-Based Normalization (rfc3986)

Return Value

`true` if `u0 < u1`

Return the result of comparing two URLs

Synopsis

Declared in <include/boost/url/url_view_base.hpp>


friend
bool
operator<=(
    url_view_base const& u0,
    url_view_base const& u1) noexcept;

Description

The URLs are compared component by component as if they were first normalized.


url_view u0( "http://www.b.com/index.htm" );
url_view u1( "http://www.b.com/index.htm" );
assert( u0 <= u1 );


url a(u0);
a.normalize();
url b(u1);
b.normalize();
return a.buffer() <= b.buffer();

Linear in `min( u0.size(), u1.size() )`

Throws nothing

6.2.2 Syntax-Based Normalization (rfc3986)

Return Value

`true` if `u0 <= u1`

Return the result of comparing two URLs

Synopsis

Declared in <include/boost/url/url_view_base.hpp>


friend
bool
operator>(
    url_view_base const& u0,
    url_view_base const& u1) noexcept;

Description

The URLs are compared component by component as if they were first normalized.


url_view u0( "http://www.b.com/index.htm" );
url_view u1( "http://www.a.com/index.htm" );
assert( u0 > u1 );


url a(u0);
a.normalize();
url b(u1);
b.normalize();
return a.buffer() > b.buffer();

Linear in `min( u0.size(), u1.size() )`

Throws nothing

6.2.2 Syntax-Based Normalization (rfc3986)

Return Value

`true` if `u0 > u1`

Return the result of comparing two URLs

Synopsis

Declared in <include/boost/url/url_view_base.hpp>


friend
bool
operator>=(
    url_view_base const& u0,
    url_view_base const& u1) noexcept;

Description

The URLs are compared component by component as if they were first normalized.


url_view u0( "http://www.a.com/index.htm" );
url_view u1( "http://www.a.com/index.htm" );
assert( u0 >= u1 );


url a(u0);
a.normalize();
url b(u1);
b.normalize();
return a.buffer() >= b.buffer();

Linear in `min( u0.size(), u1.size() )`

Throws nothing

6.2.2 Syntax-Based Normalization (rfc3986)

Return Value

`true` if `u0 >= u1`

Format the url to the output stream

Synopsis

Declared in <include/boost/url/url_view_base.hpp>


friend
std::ostream&
operator<<(
    std::ostream& os,
    url_view_base const& u);

Description

This function serializes the url to the specified output stream. Any percent-escapes are emitted as-is; no decoding is performed.


url_view u( "http://www.example.com/index.htm" );
std::stringstream ss;
ss << u;
assert( ss.str() == "http://www.example.com/index.htm" );


return os << u.buffer();

Linear in `u.buffer().size()`

Basic guarantee.

Return Value

A reference to the output stream, for chaining

Parameters

Name	Description
os	The output stream to write to.
u	The url to write.

Resolve a URL reference against a base URL

Synopsis

Declared in <include/boost/url/url_base.hpp>


system::result<void>
resolve(
    url_view_base const& base,
    url_view_base const& ref,
    url_base& dest);

Description

This function attempts to resolve a URL reference `ref` against the base URL `base` in a manner similar to that of a web browser resolving an anchor tag.

The base URL must satisfy the URI grammar. In other words, it must contain a scheme.

The resolution process works as if the relative reference is appended to the base URI and the result is normalized.

Given the input base URL, this function resolves the relative reference as if performing the following steps:

Ensure the base URI has at least a scheme

Normalizing the reference path

Merge base and reference paths

Normalize the merged path

This function places the result of the resolution into `dest`, which can be any of the url containers that inherit from url_base .

If an error occurs, the contents of `dest` is unspecified and `ec` is set.

NOTE

Abnormal hrefs where the number of ".." segments exceeds the number of segments in the base path are handled by including the unmatched ".." segments in the result, as described in Errata 4547 .


url dest;
system::error_code ec;

resolve("/one/two/three", "four", dest, ec);
assert( dest.str() == "/one/two/four" );

resolve("http://example.com/", "/one", dest, ec);
assert( dest.str() == "http://example.com/one" );

resolve("http://example.com/one", "/two", dest, ec);
assert( dest.str() == "http://example.com/two" );

resolve("http://a/b/c/d;p?q", "g#s", dest, ec);
assert( dest.str() == "http://a/b/c/g#s" );


absolute-URI  = scheme ":" hier-part [ "?" query ]

Basic guarantee.

Calls to allocate may throw.

5. Reference Resolution (rfc3986)

Resolve a URL reference against a base URL

This function attempts to resolve a URL reference `ref` against the base URL `base` in a manner similar to that of a web browser resolving an anchor tag.

The base URL must satisfy the URI grammar. In other words, it must contain a scheme.

The resolution process works as if the relative reference is appended to the base URI and the result is normalized.

Given the input base URL, this function resolves the relative reference as if performing the following steps:

Ensure the base URI has at least a scheme

Normalizing the reference path

Merge base and reference paths

Normalize the merged path

This function places the result of the resolution into `dest`, which can be any of the url containers that inherit from url_base .

If an error occurs, the contents of `dest` is unspecified and `ec` is set.

NOTE

Abnormal hrefs where the number of ".." segments exceeds the number of segments in the base path are handled by including the unmatched ".." segments in the result, as described in Errata 4547 .


url dest;
system::error_code ec;

resolve("/one/two/three", "four", dest, ec);
assert( dest.str() == "/one/two/four" );

resolve("http://example.com/", "/one", dest, ec);
assert( dest.str() == "http://example.com/one" );

resolve("http://example.com/one", "/two", dest, ec);
assert( dest.str() == "http://example.com/two" );

resolve("http://a/b/c/d;p?q", "g#s", dest, ec);
assert( dest.str() == "http://a/b/c/g#s" );


absolute-URI  = scheme ":" hier-part [ "?" query ]

Basic guarantee.

Calls to allocate may throw.

5. Reference Resolution (rfc3986)

Return Value

An empty result upon success, otherwise an error code if `!base.has_scheme()`.

Parameters

Name	Description
base	The base URL to resolve against.
ref	The URL reference to resolve.
dest	The container where the result is written, upon success.
base	The base URL to resolve against.
ref	The URL reference to resolve.
dest	The container where the result is written, upon success.

Synopsis

Declared in <include/boost/url/url.hpp>


class url
    : public url_base;

Member Functions

Name	Description
`authority`	Return the authority
`buffer`	Return the url string
`c_str`	Return the url as a null-terminated string
`capacity`	Return the number of characters that can be stored without reallocating
`clear`	Clear the contents while preserving the capacity
`compare`	Return the result of comparing this with another url
`data`	Return a pointer to the url's character buffer
`empty`	Return true if the url is empty
`encoded_authority`	Return the authority.
`encoded_fragment`	Return the fragment
`encoded_host`	Return the host
`encoded_host_address`	Return the host
`encoded_host_and_port`	Return the host and port
`encoded_host_name`	Return the host name
`encoded_origin`	Return the origin
`encoded_params`	Return the query as a container of parameters
`encoded_password`	Return the password
`encoded_path`	Return the path
`encoded_query`	Return the query
`encoded_resource`	Return the resource
`encoded_segments`	Return the path as a container of segments
`encoded_target`	Return the target
`encoded_user`	Return the user
`encoded_userinfo`	Return the userinfo
`encoded_zone_id`	Return the IPv6 Zone ID
`fragment`	Return the fragment
`has_authority`	Return true if an authority is present
`has_fragment`	Return true if a fragment is present
`has_password`	Return true if a password is present
`has_port`	Return true if a port is present
`has_query`	Return true if a query is present
`has_scheme`	Return true a scheme is present
`has_userinfo`	Return true if a userinfo is present
`host`	Return the host
`host_address`	Return the host
`host_ipv4_address`	Return the host IPv4 address
`host_ipv6_address`	Return the host IPv6 address
`host_ipvfuture`	Return the host IPvFuture address
`host_name`	Return the host name
`host_type`	Return the host type
`is_path_absolute`	Return true if the path is absolute
`normalize`	Normalize the URL components
`normalize_authority`	Normalize the URL authority
`normalize_fragment`	Normalize the URL fragment
`normalize_path`	Normalize the URL path
`normalize_query`	Normalize the URL query
`normalize_scheme`	Normalize the URL scheme
`operator core::string_view`	Return the URL as a core::string_view
`operator=`	Assignment
`params`	url_view_base::params Return the query as a container of parameters
`password`	Return the password
`path`	Return the path
`persist`	Return a shared, persistent copy of the url
`port`	Return the port
`port_number`	Return the port
`query`	Return the query
`remove_authority`	Remove the authority
`remove_fragment`	Remove the fragment
`remove_origin`	Remove the origin component
`remove_password`	Remove the password
`remove_port`	Remove the port
`remove_query`	Remove the query
`remove_scheme`	Remove the scheme
`remove_userinfo`	Remove the userinfo
`reserve`	Adjust the capacity without changing the size
`resolve`	Resolve a URL reference against this base URL
`scheme`	Return the scheme
`scheme_id`	Return the scheme
`segments`	Return the path as a container of segments
`set_encoded_authority`	Set the authority
`set_encoded_fragment`	Set the fragment.
`set_encoded_host`	Set the host
`set_encoded_host_address`	Set the host to an address
`set_encoded_host_name`	Set the host to a name
`set_encoded_params`	Set the query params
`set_encoded_password`	Set the password.
`set_encoded_path`	Set the path.
`set_encoded_query`	Set the query
`set_encoded_user`	Set the user
`set_encoded_userinfo`	Set the userinfo.
`set_fragment`	Set the fragment.
`set_host`	Set the host
`set_host_address`	Set the host to an address
`set_host_ipv4`	Set the host to an address
`set_host_ipv6`	Set the host to an address
`set_host_ipvfuture`	Set the host to an address
`set_host_name`	Set the host to a name
`set_params`	Set the query params
`set_password`	Set the password.
`set_path`	Set the path.
`set_path_absolute`	Set if the path is absolute
`set_port`	Set the port
`set_port_number`	Set the port
`set_query`	Set the query
`set_scheme`	Set the scheme
`set_scheme_id`	Set the scheme
`set_user`	Set the user
`set_userinfo`	Set the userinfo
`size`	Return the number of characters in the url
`swap`	Swap the contents.
`url` [constructor]	Constructor
`user`	Return the user
`userinfo`	Return the userinfo
`zone_id`	Return the IPv6 Zone ID
`~url` [destructor]	Destructor

Static Member Functions

Name	Description
`max_size`	Return the maximum number of characters possible

Friends

Name	Description
`operator!=`	Return the result of comparing two URLs
`operator<`	Return the result of comparing two URLs
`operator<<`	Format the url to the output stream
`operator<=`	Return the result of comparing two URLs
`operator==`	Return the result of comparing two URLs
`operator>`	Return the result of comparing two URLs
`operator>=`	Return the result of comparing two URLs
`resolve`	Resolve a URL reference against a base URL
`swap`	Swap

Description

This container owns a url, represented by a null-terminated character buffer which is managed by performing dymamic memory allocations as needed. The contents may be inspected and modified, and the implementation maintains a useful invariant: changes to the url always leave it in a valid state.

Functions marked `noexcept` provide the no-throw guarantee, otherwise:

Functions which throw offer the strong exception safety guarantee.


URI-reference = URI / relative-ref

URI           = scheme ":" hier-part [ "?" query ] [ "#" fragment ]

relative-ref  = relative-part [ "?" query ] [ "#" fragment ]

absolute-URI  = scheme ":" hier-part [ "?" query ]

Uniform Resource Identifier (URI): Generic Syntax (rfc3986)

Synopsis

Declared in <include/boost/url/url.hpp>


virtual
~url();

Description

Any params, segments, iterators, or views which reference this object are invalidated. The underlying character buffer is destroyed, invalidating all references to it.

Constructor

Synopsis

Declared in <include/boost/url/url.hpp>


url() noexcept;

» more...


explicit
url(core::string_view s);

» more...


url(url&& u) noexcept;

» more...


url(url_view_base const& u);

» more...


url(url const& u);

» more...

Description

Default constructed urls contain a zero-length string. This matches the grammar for a relative-ref with an empty path and no query or fragment.


url u;


this->empty() == true

Constant.

Throws nothing.


relative-ref  = relative-part [ "?" query ] [ "#" fragment ]

4.2. Relative Reference (rfc3986)

Exceptions

Name	Thrown on
`[object Object]`	input does not contain a valid url.
`[object Object]`	> max_size()`.

Parameters

Name	Description
s	The string to parse.
u	The url to move from.

Constructor

Synopsis

Declared in <include/boost/url/url.hpp>


url() noexcept;

Description

Default constructed urls contain a zero-length string. This matches the grammar for a relative-ref with an empty path and no query or fragment.


url u;


this->empty() == true

Constant.

Throws nothing.


relative-ref  = relative-part [ "?" query ] [ "#" fragment ]

4.2. Relative Reference (rfc3986)

Constructor

Synopsis

Declared in <include/boost/url/url.hpp>


explicit
url(core::string_view s);

Description

This function constructs a URL from the string `s`, which must contain a valid URI or relative-ref or else an exception is thrown. The new url retains ownership by allocating a copy of the passed string.


url u( "https://www.example.com" );


return url( parse_uri_reference( s ).value() );


this->buffer().data() != s.data()

Linear in `s.size()`.

Calls to allocate may throw.

Exceptions thrown on invalid input.


URI           = scheme ":" hier-part [ "?" query ] [ "#" fragment ]

relative-ref  = relative-part [ "?" query ] [ "#" fragment ]

4.1. URI Reference

Exceptions

Name	Thrown on
`The`	input does not contain a valid url.

Parameters

Name	Description
s	The string to parse.

Constructor

Synopsis

Declared in <include/boost/url/url.hpp>


url(url&& u) noexcept;

Description

The contents of `u` are transferred to the newly constructed object, which includes the underlying character buffer. After construction, the moved-from object is as if default constructed.


u.empty() == true

Constant.

Throws nothing.

Parameters

Name	Description
u	The url to move from.

Constructor

Synopsis

Declared in <include/boost/url/url.hpp>


url(url_view_base const& u);

Description

The newly constructed object contains a copy of `u`.


this->buffer() == u.buffer() && this->buffer().data() != u.buffer().data()

Linear in `u.size()`.

Strong guarantee.

Calls to allocate may throw.

Exceptions

Name	Thrown on
`u.size()	> max_size()`.

Parameters

Name	Description
u	The url to copy.

Constructor

Synopsis

Declared in <include/boost/url/url.hpp>


url(url const& u);

Description

The newly constructed object contains a copy of `u`.


this->buffer() == u.buffer() && this->buffer().data() != u.buffer().data()

Linear in `u.size()`.

Strong guarantee.

Calls to allocate may throw.

Exceptions

Name	Thrown on
`u.size()	> max_size()`.

Parameters

Name	Description
u	The url to copy.

Assignment

Synopsis

Declared in <include/boost/url/url.hpp>


url&
operator=(url&& u) noexcept;

» more...


url&
operator=(url_view_base const& u);

» more...


url&
operator=(url const& u);

» more...

Description

The contents of `u` are transferred to `this`, including the underlying character buffer. The previous contents of `this` are destroyed. After assignment, the moved-from object is as if default constructed.


u.empty() == true

Constant.

Throws nothing.

Exceptions

Name	Thrown on
`[object Object]`	> max_size()`.

Parameters

Name	Description
u	The url to assign from.

Assignment

Synopsis

Declared in <include/boost/url/url.hpp>


url&
operator=(url&& u) noexcept;

Description


u.empty() == true

Constant.

Throws nothing.

Parameters

Name	Description
u	The url to assign from.

Assignment

Synopsis

Declared in <include/boost/url/url.hpp>


url&
operator=(url_view_base const& u);

Description

The contents of `u` are copied and the previous contents of `this` are destroyed. Capacity is preserved, or increases.


this->buffer() == u.buffer() && this->buffer().data() != u.buffer().data()

Linear in `u.size()`.

Strong guarantee.

Calls to allocate may throw.

Exceptions

Name	Thrown on
`u.size()	> max_size()`.

Parameters

Name	Description
u	The url to copy.

Assignment

Synopsis

Declared in <include/boost/url/url.hpp>


url&
operator=(url const& u);

Description

The contents of `u` are copied and the previous contents of `this` are destroyed. Capacity is preserved, or increases.


this->buffer() == u.buffer() && this->buffer().data() != u.buffer().data()

Linear in `u.size()`.

Strong guarantee.

Calls to allocate may throw.

Parameters

Name	Description
u	The url to copy.

Swap the contents.

Synopsis

Declared in <include/boost/url/url.hpp>


void
swap(url& other) noexcept;

Description

Exchanges the contents of this url with another url. All views, iterators and references remain valid.

If `this == &other`, this function call has no effect.


url u1( "https://www.example.com" );
url u2( "https://www.boost.org" );
u1.swap(u2);
assert(u1 == "https://www.boost.org" );
assert(u2 == "https://www.example.com" );

Constant

Throws nothing.

Parameters

Name	Description
other	The object to swap with

Swap

Synopsis

Declared in <include/boost/url/url.hpp>


friend
void
swap(
    url& v0,
    url& v1) noexcept;

Description

Exchanges the contents of `v0` with another `v1`. All views, iterators and references remain valid.

If `&v0 ==&v1`, this function call has no effect.


url u1( "https://www.example.com" );
url u2( "https://www.boost.org" );
std::swap(u1, u2);
assert(u1 == "https://www.boost.org" );
assert(u2 == "https://www.example.com" );


v0.swap( v1 );

Constant

Throws nothing

Parameters

Name	Description
v0,	v1 The objects to swap

Synopsis

Declared in <include/boost/url/url.hpp>


url&
set_scheme(core::string_view s);

Description

The scheme is set to the specified string, which must contain a valid scheme without any trailing colon (':'). Note that schemes are case-insensitive, and the canonical form is lowercased.


assert( url( "http://www.example.com" ).set_scheme( "https" ).scheme_id() == scheme::https );

Linear in `this->size() + s.size()`.

Strong guarantee.

Calls to allocate may throw. Exceptions thrown on invalid input.


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

3.1. Scheme (rfc3986)

Exceptions

Name	Thrown on
`s`	contains an invalid scheme.

Parameters

Name	Description
s	The scheme to set.

Synopsis

Declared in <include/boost/url/url.hpp>


url&
set_scheme_id(urls::scheme id);

Description


assert( url( "http://example.com/echo.cgi" ).set_scheme_id( scheme::wss ).buffer() == "wss://example.com/echo.cgi" );

Linear in `this->size()`.

Strong guarantee.

Calls to allocate may throw. Exceptions thrown on invalid input.

3.1. Scheme (rfc3986)

Exceptions

Name	Thrown on
`The`	scheme is invalid.

Parameters

Name	Description
id	The scheme to set.

Remove the scheme

Synopsis

Declared in <include/boost/url/url.hpp>


url&
remove_scheme();

Description

This function removes the scheme if it is present.


assert( url("http://www.example.com/index.htm" ).remove_scheme().buffer() == "//www.example.com/index.htm" );


this->has_scheme() == false && this->scheme_id() == scheme::none

Linear in `this->size()`.

Throws nothing.


URI           = scheme ":" hier-part [ "?" query ] [ "#" fragment ]

3.1. Scheme (rfc3986)

Synopsis

Declared in <include/boost/url/url.hpp>


url&
set_encoded_authority(pct_string_view s);

Description

This function sets the authority to the specified string. The string may contain percent-escapes.


assert( url().set_encoded_authority( "My%20Computer" ).has_authority() );

Strong guarantee.

Calls to allocate may throw. Exceptions thrown on invalid input.


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

userinfo      = *( unreserved / pct-encoded / sub-delims / ":" )
host          = IP-literal / IPv4address / reg-name
port          = *DIGIT

3.2. Authority (rfc3986)

Exceptions

Name	Thrown on
`The`	string contains an invalid percent-encoding.

Parameters

Name	Description
s	The authority string to set.

Synopsis

Declared in <include/boost/url/url.hpp>


url&
remove_authority();

Description

This function removes the authority, which includes the userinfo, host, and a port if present.


assert( url( "http://example.com/echo.cgi" ).remove_authority().buffer() == "http:/echo.cgi" );


this->has_authority() == false && this->has_userinfo() == false && this->has_port() == false

Linear in `this->size()`.

Throws nothing.


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

userinfo      = *( unreserved / pct-encoded / sub-delims / ":" )
host          = IP-literal / IPv4address / reg-name
port          = *DIGIT

3.2. Authority (rfc3986)

Synopsis

Declared in <include/boost/url/url.hpp>


url&
set_userinfo(core::string_view s);

Description

If an unescaped colon exists, the characters up to the colon become the user and the rest of the characters after the colon become the password. In this case has_password returns true. Otherwise,

If there is no colon, the user is set to the string. The function has_password returns false.

NOTE

The interpretation of the userinfo as individual user and password components is scheme-dependent. Transmitting passwords in URLs is deprecated.


assert( url( "http://example.com" ).set_userinfo( "user:pass" ).encoded_user() == "user" );

Linear in `this->size() + s.size()`.

Strong guarantee.

Calls to allocate may throw.


userinfo      = [ [ user ] [ ':' password ] ]

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

3.2.1. User Information (rfc3986)

Parameters

Name	Description
s	The string to set.

Synopsis

Declared in <include/boost/url/url.hpp>


url&
set_encoded_userinfo(pct_string_view s);

Description

If an unescaped colon exists, the characters up to the colon become the user and the rest of the characters after the colon become the password. In this case has_password returns true. Otherwise,

If there is no colon, the user is set to the string. The function has_password returns false.

NOTE

The interpretation of the userinfo as individual user and password components is scheme-dependent. Transmitting passwords in URLs is deprecated.


assert( url( "http://example.com" ).set_encoded_userinfo( "john%20doe" ).user() == "john doe" );

Linear in `this->size() + s.size()`.

Strong guarantee.

Calls to allocate may throw. Exceptions thrown on invalid input.


userinfo      = [ [ user ] [ ':' password ] ]

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

3.2.1. User Information (rfc3986)

Exceptions

Name	Thrown on
`s`	contains an invalid percent-encoding.

Parameters

Name	Description
s	The string to set.

Synopsis

Declared in <include/boost/url/url.hpp>


url&
remove_userinfo() noexcept;

Description

This function removes the userinfo if present, without removing any authority.


assert( url( "http://user@example.com" ).remove_userinfo().has_userinfo() == false );


this->has_userinfo() == false && this->encoded_userinfo().empty == true

Linear in `this->size()`.

Throws nothing.


userinfo      = [ [ user ] [ ':' password ] ]

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

3.2.1. User Information (rfc3986)

Synopsis

Declared in <include/boost/url/url.hpp>


url&
set_user(core::string_view s);

Description

This function sets the user part of the userinfo to the string. Any special or reserved characters in the string are automatically percent-encoded.


assert( url().set_user("john doe").encoded_userinfo() == "john%20doe" );


this->has_authority() == true && this->has_userinfo() == true

Linear in `this->size() + s.size()`.

Strong guarantee.

Calls to allocate may throw.


userinfo      = [ [ user ] [ ':' password ] ]

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

3.2.1. User Information (rfc3986)

Parameters

Name	Description
s	The string to set.

Synopsis

Declared in <include/boost/url/url.hpp>


url&
set_encoded_user(pct_string_view s);

Description


assert( url().set_encoded_user("john%20doe").userinfo() == "john doe" );


this->has_authority() == true && this->has_userinfo() == true

Linear in `this->size() + s.size()`.

Strong guarantee.

Calls to allocate may throw.


userinfo      = [ [ user ] [ ':' password ] ]

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

3.2.1. User Information (rfc3986)

Exceptions

Name	Thrown on
`s`	contains an invalid percent-encoding.

Parameters

Name	Description
s	The string to set.

Synopsis

Declared in <include/boost/url/url.hpp>


url&
set_password(core::string_view s);

Description

This function sets the password in the userinfo to the string. Reserved characters in the string are percent-escaped in the result.

NOTE

The interpretation of the userinfo as individual user and password components is scheme-dependent. Transmitting passwords in URLs is deprecated.


assert( url("http://user@example.com").set_password( "pass" ).encoded_userinfo() == "user:pass" );


this->has_password() == true && this->password() == s

Strong guarantee.

Calls to allocate may throw.


userinfo      = [ [ user ] [ ':' password ] ]

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

3.2.1. User Information (rfc3986)

Parameters

Name	Description
s	The string to set. This string may contain any characters, including nulls.

Synopsis

Declared in <include/boost/url/url.hpp>


url&
set_encoded_password(pct_string_view s);

Description

NOTE

The interpretation of the userinfo as individual user and password components is scheme-dependent. Transmitting passwords in URLs is deprecated.


assert( url("http://user@example.com").set_encoded_password( "pass" ).encoded_userinfo() == "user:pass" );


this->has_password() == true

Strong guarantee.

Calls to allocate may throw.


userinfo      = [ [ user ] [ ':' password ] ]

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

3.2.1. User Information (rfc3986)

Exceptions

Name	Thrown on
`s`	contains an invalid percent-encoding.

Parameters

Name	Description
s	The string to set. This string may contain any characters, including nulls.

Synopsis

Declared in <include/boost/url/url.hpp>


url&
remove_password() noexcept;

Description

This function removes the password from the userinfo if a password exists. If there is no userinfo or no authority, the call has no effect.

NOTE

The interpretation of the userinfo as individual user and password components is scheme-dependent. Transmitting passwords in URLs is deprecated.


assert( url( "http://user:pass@example.com" ).remove_password().authority().buffer() == "user@example.com" );


this->has_password() == false && this->encoded_password().empty() == true

Linear in `this->size()`.

Throws nothing.


userinfo      = [ [ user ] [ ':' password ] ]

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

3.2.1. User Information (rfc3986)

Synopsis

Declared in <include/boost/url/url.hpp>


url&
set_host(core::string_view s);

Description

Depending on the contents of the passed string, this function sets the host:

If the string is a valid IPv4 address, then the host is set to the address. The host type is host_type::ipv4 .

If the string is a valid IPv6 address enclosed in square brackets, then the host is set to that address. The host type is host_type::ipv6 .

If the string is a valid IPvFuture address enclosed in square brackets, then the host is set to that address. The host type is host_type::ipvfuture .

Otherwise, the host name is set to the string, which may be empty. Reserved characters in the string are percent-escaped in the result. The host type is host_type::name .

In all cases, when this function returns, the URL contains an authority.


assert( url( "http://www.example.com" ).set_host( "127.0.0.1" ).buffer() == "http://127.0.0.1" );


this->has_authority() == true

Linear in `this->size() + s.size()`.

Strong guarantee.

Calls to allocate may throw.


host        = IP-literal / IPv4address / reg-name

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

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

IPv4 (Wikipedia)

IP Version 6 Addressing Architecture (rfc4291)

3.2.2. Host (rfc3986)

Parameters

Name	Description
s	The string to set.

Synopsis

Declared in <include/boost/url/url.hpp>


url&
set_encoded_host(pct_string_view s);

Description

Depending on the contents of the passed string, this function sets the host:

If the string is a valid IPv4 address, then the host is set to the address. The host type is host_type::ipv4 .

If the string is a valid IPv6 address enclosed in square brackets, then the host is set to that address. The host type is host_type::ipv6 .

If the string is a valid IPvFuture address enclosed in square brackets, then the host is set to that address. The host type is host_type::ipvfuture .

In all cases, when this function returns, the URL contains an authority.


assert( url( "http://www.example.com" ).set_host( "127.0.0.1" ).buffer() == "http://127.0.0.1" );


this->has_authority() == true

Linear in `this->size() + s.size()`.

Strong guarantee.

Calls to allocate may throw. Exceptions thrown on invalid input.


host        = IP-literal / IPv4address / reg-name

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

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

IPv4 (Wikipedia)

IP Version 6 Addressing Architecture (rfc4291)

3.2.2. Host (rfc3986)

Exceptions

Name	Thrown on
`s`	contains an invalid percent-encoding.

Parameters

Name	Description
s	The string to set.

Synopsis

Declared in <include/boost/url/url.hpp>


url&
set_host_address(core::string_view s);

Description

Depending on the contents of the passed string, this function sets the host:

If the string is a valid IPv4 address, then the host is set to the address. The host type is host_type::ipv4 .

If the string is a valid IPv6 address, then the host is set to that address. The host type is host_type::ipv6 .

If the string is a valid IPvFuture, then the host is set to that address. The host type is host_type::ipvfuture .

Otherwise, the host name is set to the string, which may be empty. Reserved characters in the string are percent-escaped in the result. The host type is host_type::name .

In all cases, when this function returns, the URL contains an authority.


assert( url( "http://www.example.com" ).set_host_address( "127.0.0.1" ).buffer() == "http://127.0.0.1" );


this->has_authority() == true

Linear in `s.size()`.

Strong guarantee.

Calls to allocate may throw.


IPv4address = dec-octet "." dec-octet "." dec-octet "." dec-octet

dec-octet   = DIGIT                 ; 0-9
            / %x31-39 DIGIT         ; 10-99
            / "1" 2DIGIT            ; 100-199
            / "2" %x30-34 DIGIT     ; 200-249
            / "25" %x30-35          ; 250-255

IPv6address =                            6( h16 ":" ) ls32
            /                       "::" 5( h16 ":" ) ls32
            / [               h16 ] "::" 4( h16 ":" ) ls32
            / [ *1( h16 ":" ) h16 ] "::" 3( h16 ":" ) ls32
            / [ *2( h16 ":" ) h16 ] "::" 2( h16 ":" ) ls32
            / [ *3( h16 ":" ) h16 ] "::"    h16 ":"   ls32
            / [ *4( h16 ":" ) h16 ] "::"              ls32
            / [ *5( h16 ":" ) h16 ] "::"              h16
            / [ *6( h16 ":" ) h16 ] "::"

ls32        = ( h16 ":" h16 ) / IPv4address
            ; least-significant 32 bits of address

h16         = 1*4HEXDIG
            ; 16 bits of address represented in hexadecimal

IPvFuture     = "v" 1*HEXDIG "." 1*( unreserved / sub-delims / ":" )

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

IPv4 (Wikipedia)

IP Version 6 Addressing Architecture (rfc4291)

3.2.2. Host (rfc3986)

Parameters

Name	Description
s	The string to set.

Synopsis

Declared in <include/boost/url/url.hpp>


url&
set_encoded_host_address(pct_string_view s);

Description

Depending on the contents of the passed string, this function sets the host:

If the string is a valid IPv4 address, then the host is set to the address. The host type is host_type::ipv4 .

If the string is a valid IPv6 address, then the host is set to that address. The host type is host_type::ipv6 .

If the string is a valid IPvFuture, then the host is set to that address. The host type is host_type::ipvfuture .

In all cases, when this function returns, the URL contains an authority.


assert( url( "http://www.example.com" ).set_host( "127.0.0.1" ).buffer() == "http://127.0.0.1" );


this->has_authority() == true

Linear in `this->size() + s.size()`.

Strong guarantee.

Calls to allocate may throw. Exceptions thrown on invalid input.


IPv4address = dec-octet "." dec-octet "." dec-octet "." dec-octet

dec-octet   = DIGIT                 ; 0-9
            / %x31-39 DIGIT         ; 10-99
            / "1" 2DIGIT            ; 100-199
            / "2" %x30-34 DIGIT     ; 200-249
            / "25" %x30-35          ; 250-255

IPv6address =                            6( h16 ":" ) ls32
            /                       "::" 5( h16 ":" ) ls32
            / [               h16 ] "::" 4( h16 ":" ) ls32
            / [ *1( h16 ":" ) h16 ] "::" 3( h16 ":" ) ls32
            / [ *2( h16 ":" ) h16 ] "::" 2( h16 ":" ) ls32
            / [ *3( h16 ":" ) h16 ] "::"    h16 ":"   ls32
            / [ *4( h16 ":" ) h16 ] "::"              ls32
            / [ *5( h16 ":" ) h16 ] "::"              h16
            / [ *6( h16 ":" ) h16 ] "::"

ls32        = ( h16 ":" h16 ) / IPv4address
            ; least-significant 32 bits of address

h16         = 1*4HEXDIG
            ; 16 bits of address represented in hexadecimal

IPvFuture     = "v" 1*HEXDIG "." 1*( unreserved / sub-delims / ":" )

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

IPv4 (Wikipedia)

IP Version 6 Addressing Architecture (rfc4291)

3.2.2. Host (rfc3986)

Exceptions

Name	Thrown on
`s`	contains an invalid percent-encoding.

Parameters

Name	Description
s	The string to set.

Synopsis

Declared in <include/boost/url/url.hpp>


url&
set_host_ipv4(ipv4_address const& addr);

Description

The host is set to the specified IPv4 address. The host type is host_type::ipv4 .


assert( url("http://www.example.com").set_host_ipv4( ipv4_address( "127.0.0.1" ) ).buffer() == "http://127.0.0.1" );

Linear in `this->size()`.


this->has_authority() == true && this->host_ipv4_address() == addr && this->host_type() == host_type::ipv4

Strong guarantee.

Calls to allocate may throw.


IPv4address = dec-octet "." dec-octet "." dec-octet "." dec-octet

dec-octet   = DIGIT                 ; 0-9
            / %x31-39 DIGIT         ; 10-99
            / "1" 2DIGIT            ; 100-199
            / "2" %x30-34 DIGIT     ; 200-249
            / "25" %x30-35          ; 250-255

IPv4 (Wikipedia)

3.2.2. Host (rfc3986)

Parameters

Name	Description
addr	The address to set.

Synopsis

Declared in <include/boost/url/url.hpp>


url&
set_host_ipv6(ipv6_address const& addr);

Description

The host is set to the specified IPv6 address. The host type is host_type::ipv6 .


assert( url().set_host_ipv6( ipv6_address( "1::6:c0a8:1" ) ).authority().buffer() == "[1::6:c0a8:1]" );


this->has_authority() == true && this->host_ipv6_address() == addr && this->host_type() == host_type::ipv6

Linear in `this->size()`.

Strong guarantee.

Calls to allocate may throw.


IPv6address =                            6( h16 ":" ) ls32
            /                       "::" 5( h16 ":" ) ls32
            / [               h16 ] "::" 4( h16 ":" ) ls32
            / [ *1( h16 ":" ) h16 ] "::" 3( h16 ":" ) ls32
            / [ *2( h16 ":" ) h16 ] "::" 2( h16 ":" ) ls32
            / [ *3( h16 ":" ) h16 ] "::"    h16 ":"   ls32
            / [ *4( h16 ":" ) h16 ] "::"              ls32
            / [ *5( h16 ":" ) h16 ] "::"              h16
            / [ *6( h16 ":" ) h16 ] "::"

ls32        = ( h16 ":" h16 ) / IPv4address
            ; least-significant 32 bits of address

h16         = 1*4HEXDIG
            ; 16 bits of address represented in hexadecimal

IP Version 6 Addressing Architecture (rfc4291)

3.2.2. Host (rfc3986)

Parameters

Name	Description
addr	The address to set.

Synopsis

Declared in <include/boost/url/url.hpp>


url&
set_host_ipvfuture(core::string_view s);

Description

The host is set to the specified IPvFuture string. The host type is host_type::ipvfuture .


assert( url().set_host_ipvfuture( "v42.bis" ).buffer() == "//[v42.bis]" );

Linear in `this->size() + s.size()`.


this->has_authority() == true && this->host_ipvfuture) == s && this->host_type() == host_type::ipvfuture

Strong guarantee.

Calls to allocate may throw. Exceptions thrown on invalid input.


IPvFuture     = "v" 1*HEXDIG "." 1*( unreserved / sub-delims / ":" )

3.2.2. Host (rfc3986)

Exceptions

Name	Thrown on
`s`	contains an invalid percent-encoding.

Parameters

Name	Description
s	The string to set.

Synopsis

Declared in <include/boost/url/url.hpp>


url&
set_host_name(core::string_view s);

Description

The host is set to the specified string, which may be empty. Reserved characters in the string are percent-escaped in the result. The host type is host_type::name .


assert( url( "http://www.example.com/index.htm").set_host_name( "localhost" ).host_address() == "localhost" );


this->has_authority() == true && this->host_ipv6_address() == addr && this->host_type() == host_type::name

Strong guarantee.

Calls to allocate may throw.


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

3.2.2. Host (rfc3986)

Parameters

Name	Description
s	The string to set.

Synopsis

Declared in <include/boost/url/url.hpp>


url&
set_encoded_host_name(pct_string_view s);

Description


assert( url( "http://www.example.com/index.htm").set_encoded_host_name( "localhost" ).host_address() == "localhost" );


this->has_authority() == true && this->host_ipv6_address() == addr && this->host_type() == host_type::name

Strong guarantee.

Calls to allocate may throw. Exceptions thrown on invalid input.


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

3.2.2. Host (rfc3986)

Exceptions

Name	Thrown on
`s`	contains an invalid percent-encoding.

Parameters

Name	Description
s	The string to set.

Synopsis

Declared in <include/boost/url/url.hpp>


url&
set_port_number(std::uint16_t n);

Description

The port is set to the specified integer.


assert( url( "http://www.example.com" ).set_port_number( 8080 ).authority().buffer() == "www.example.com:8080" );


this->has_authority() == true && this->has_port() == true && this->port_number() == n

Linear in `this->size()`.

Strong guarantee.

Calls to allocate may throw.


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

port          = *DIGIT

3.2.3. Port (rfc3986)

Parameters

Name	Description
n	The port number to set.

Synopsis

Declared in <include/boost/url/url.hpp>


url&
set_port(core::string_view s);

Description

This port is set to the string, which must contain only digits or be empty. An empty port string is distinct from having no port.


assert( url( "http://www.example.com" ).set_port( "8080" ).authority().buffer() == "www.example.com:8080" );


this->has_port() == true && this->port_number() == n && this->port() == std::to_string(n)

Strong guarantee.

Calls to allocate may throw. Exceptions thrown on invalid input.


port          = *DIGIT

3.2.3. Port (rfc3986)

Exceptions

Name	Thrown on
`s`	does not contain a valid port.

Parameters

Name	Description
s	The port string to set.

Synopsis

Declared in <include/boost/url/url.hpp>


url&
remove_port() noexcept;

Description

If a port exists, it is removed. The rest of the authority is unchanged.


assert( url( "http://www.example.com:80" ).remove_port().authority().buffer() == "www.example.com" );


this->has_port() == false && this->port_number() == 0 && this->port() == ""

Linear in `this->size()`.

Throws nothing.


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

port          = *DIGIT

3.2.3. Port (rfc3986)

Synopsis

Declared in <include/boost/url/url.hpp>


url&
set_path(core::string_view s);

Description

This function sets the path to the string, which may be empty. Reserved characters in the string are percent-escaped in the result.

NOTE

The library may adjust the final result to ensure that no other parts of the url is semantically affected.

NOTE


url u( "http://www.example.com" );

u.set_path( "path/to/file.txt" );

assert( u.path() == "/path/to/file.txt" );

Linear in `this->size() + s.size()`.

Strong guarantee.

Calls to allocate may throw.


path          = path-abempty    ; begins with "/" or is empty
              / path-absolute   ; begins with "/" but not "//"
              / path-noscheme   ; begins with a non-colon segment
              / path-rootless   ; begins with a segment
              / path-empty      ; zero characters

path-abempty  = *( "/" segment )
path-absolute = "/" [ segment-nz *( "/" segment ) ]
path-noscheme = segment-nz-nc *( "/" segment )
path-rootless = segment-nz *( "/" segment )
path-empty    = 0

3.3. Path (rfc3986)

Parameters

Name	Description
s	The string to set.

Synopsis

Declared in <include/boost/url/url.hpp>


url&
set_encoded_path(pct_string_view s);

Description

NOTE

The library may adjust the final result to ensure that no other parts of the url is semantically affected.


url u( "http://www.example.com" );

u.set_encoded_path( "path/to/file.txt" );

assert( u.encoded_path() == "/path/to/file.txt" );

Linear in `this->size() + s.size()`.

Strong guarantee.

Calls to allocate may throw. Exceptions thrown on invalid input.


path          = path-abempty    ; begins with "/" or is empty
              / path-absolute   ; begins with "/" but not "//"
              / path-noscheme   ; begins with a non-colon segment
              / path-rootless   ; begins with a segment
              / path-empty      ; zero characters

path-abempty  = *( "/" segment )
path-absolute = "/" [ segment-nz *( "/" segment ) ]
path-noscheme = segment-nz-nc *( "/" segment )
path-rootless = segment-nz *( "/" segment )
path-empty    = 0

3.3. Path (rfc3986)

Exceptions

Name	Thrown on
`s`	contains an invalid percent-encoding.

Parameters

Name	Description
s	The string to set.

Synopsis

Declared in <include/boost/url/url.hpp>


url&
set_query(core::string_view s);

Description

This sets the query to the string, which can be empty. An empty query is distinct from having no query. Reserved characters in the string are percent-escaped in the result.


assert( url( "http://example.com" ).set_query( "id=42" ).query() == "id=42" );


this->has_query() == true && this->query() == s

Strong guarantee.

Calls to allocate may throw.


query           = *( pchar / "/" / "?" )

query-param     = key [ "=" value ]
query-params    = [ query-param ] *( "&" query-param )

3.4. Query (rfc3986)

Query string (Wikipedia)

Parameters

Name	Description
s	The string to set.

Synopsis

Declared in <include/boost/url/url.hpp>


url&
set_encoded_query(pct_string_view s);

Description


assert( url( "http://example.com" ).set_encoded_query( "id=42" ).encoded_query() == "id=42" );


this->has_query() == true && this->query() == decode_view( s );

Strong guarantee.

Calls to allocate may throw. Exceptions thrown on invalid input.


query           = *( pchar / "/" / "?" )

query-param     = key [ "=" value ]
query-params    = [ query-param ] *( "&" query-param )

3.4. Query (rfc3986)

Query string (Wikipedia)

Exceptions

Name	Thrown on
`s`	contains an invalid percent-encoding.

Parameters

Name	Description
s	The string to set.

Synopsis

Declared in <include/boost/url/url.hpp>


url&
set_params(
    std::initializer_list<param_view> ps,
    encoding_opts opts = = {});

Description

This sets the query params to the list of param_view, which can be empty.

An empty list of params is distinct from having no params.

Reserved characters in the string are percent-escaped in the result.


assert( url( "http://example.com" ).set_params( {"id", "42"} ).query() == "id=42" );


this->has_query() == true

Strong guarantee.

Calls to allocate may throw.

Linear.


query           = *( pchar / "/" / "?" )

query-param     = key [ "=" value ]
query-params    = [ query-param ] *( "&" query-param )

://en.wikipedia.org/wiki/Query_string" >Query string (Wikipedia)

Parameters

Name	Description
ps	The params to set.
opts	The options for encoding.

Synopsis

Declared in <include/boost/url/url.hpp>


url&
set_encoded_params(std::initializer_list<param_pct_view> ps);

Description

This sets the query params to the elements in the list, which may contain percent-escapes and can be empty.

An empty list of params is distinct from having no query.

Escapes in the string are preserved, and reserved characters in the string are percent-escaped in the result.


assert( url( "http://example.com" ).set_encoded_params( {"id", "42"} ).encoded_query() == "id=42" );


this->has_query() == true

Linear.

Strong guarantee.

Calls to allocate may throw. Exceptions thrown on invalid input.


query           = *( pchar / "/" / "?" )

query-param     = key [ "=" value ]
query-params    = [ query-param ] *( "&" query-param )

3.4. Query (rfc3986)

Query string (Wikipedia)

Exceptions

Name	Thrown on
`some`	element in `ps` contains an invalid percent-encoding.

Parameters

Name	Description
ps	The params to set.

Synopsis

Declared in <include/boost/url/url.hpp>


url&
remove_query() noexcept;

Description

If a query is present, it is removed. An empty query is distinct from having no query.


assert( url( "http://www.example.com?id=42" ).remove_query().buffer() == "http://www.example.com" );


this->has_query() == false && this->params().empty()

Throws nothing.


query           = *( pchar / "/" / "?" )

query-param     = key [ "=" value ]
query-params    = [ query-param ] *( "&" query-param )

3.4. Query (rfc3986)

Query string (Wikipedia)

Synopsis

Declared in <include/boost/url/url.hpp>


url&
remove_fragment() noexcept;

Description

This function removes the fragment. An empty fragment is distinct from having no fragment.


assert( url( "?first=john&last=doe#anchor" ).remove_fragment().buffer() == "?first=john&last=doe" );


this->has_fragment() == false && this->encoded_fragment() == ""

Constant.

Throws nothing.


fragment    = *( pchar / "/" / "?" )

3.5. Fragment

Synopsis

Declared in <include/boost/url/url.hpp>


url&
set_fragment(core::string_view s);

Description


assert( url("?first=john&last=doe" ).set_encoded_fragment( "john doe" ).encoded_fragment() == "john%20doe" );


this->has_fragment() == true && this->fragment() == s

Linear in `this->size() + s.size()`.

Strong guarantee.

Calls to allocate may throw.


fragment    = *( pchar / "/" / "?" )

3.5. Fragment

Parameters

Name	Description
s	The string to set.

Synopsis

Declared in <include/boost/url/url.hpp>


url&
set_encoded_fragment(pct_string_view s);

Description


assert( url("?first=john&last=doe" ).set_encoded_fragment( "john%2Ddoe" ).fragment() == "john-doe" );


this->has_fragment() == true && this->fragment() == decode_view( s )

Linear in `this->size() + s.size()`.

Strong guarantee.

Calls to allocate may throw. Exceptions thrown on invalid input.


fragment    = *( pchar / "/" / "?" )

3.5. Fragment

Exceptions

Name	Thrown on
`s`	contains an invalid percent-encoding.

Parameters

Name	Description
s	The string to set.

Synopsis

Declared in <include/boost/url/url.hpp>


url&
remove_origin();

Description

This function removes the origin, which consists of the scheme and authority.


assert( url( "http://www.example.com/index.htm" ).remove_origin().buffer() == "/index.htm" );


this->scheme_id() == scheme::none && this->has_authority() == false

Linear in `this->size()`.

Throws nothing.

Normalize the URL components

Synopsis

Declared in <include/boost/url/url.hpp>


url&
normalize();

Description

Applies Syntax-based normalization to all components of the URL.

Strong guarantee.

Calls to allocate may throw.

6.2.2 Syntax-Based Normalization (rfc3986)

Normalize the URL scheme

Synopsis

Declared in <include/boost/url/url.hpp>


url&
normalize_scheme();

Description

Applies Syntax-based normalization to the URL scheme.

The scheme is normalized to lowercase.

Strong guarantee.

Calls to allocate may throw.

6.2.2 Syntax-Based Normalization (rfc3986)

Normalize the URL authority

Synopsis

Declared in <include/boost/url/url.hpp>


url&
normalize_authority();

Description

Applies Syntax-based normalization to the URL authority.

Percent-encoding triplets are normalized to uppercase letters. Percent-encoded octets that correspond to unreserved characters are decoded.

Strong guarantee.

Calls to allocate may throw.

6.2.2 Syntax-Based Normalization (rfc3986)

Normalize the URL path

Synopsis

Declared in <include/boost/url/url.hpp>


url&
normalize_path();

Description

Applies Syntax-based normalization to the URL path.

Percent-encoding triplets are normalized to uppercase letters. Percent-encoded octets that correspond to unreserved characters are decoded. Redundant path-segments are removed.

Strong guarantee.

Calls to allocate may throw.

6.2.2 Syntax-Based Normalization (rfc3986)

Normalize the URL query

Synopsis

Declared in <include/boost/url/url.hpp>


url&
normalize_query();

Description

Applies Syntax-based normalization to the URL query.

Percent-encoding triplets are normalized to uppercase letters. Percent-encoded octets that correspond to unreserved characters are decoded.

Strong guarantee.

Calls to allocate may throw.

6.2.2 Syntax-Based Normalization (rfc3986)

Normalize the URL fragment

Synopsis

Declared in <include/boost/url/url.hpp>


url&
normalize_fragment();

Description

Applies Syntax-based normalization to the URL fragment.

Percent-encoding triplets are normalized to uppercase letters. Percent-encoded octets that correspond to unreserved characters are decoded.

Strong guarantee.

Calls to allocate may throw.

6.2.2 Syntax-Based Normalization (rfc3986)

Swap

Synopsis

Declared in <include/boost/url/url.hpp>


void
swap(
    url& v0,
    url& v1) noexcept;

Description

Exchanges the contents of `v0` with another `v1`. All views, iterators and references remain valid.

If `&v0 ==&v1`, this function call has no effect.


url u1( "https://www.example.com" );
url u2( "https://www.boost.org" );
std::swap(u1, u2);
assert(u1 == "https://www.boost.org" );
assert(u2 == "https://www.example.com" );


v0.swap( v1 );

Constant

Throws nothing

Parameters

Name	Description
v0,	v1 The objects to swap

Types

Name	Description
`format_arg`

Synopsis

Declared in <include/boost/url/detail/format_args.hpp>


using format_arg = detail::format_arg;

Format arguments into a URL

Synopsis

Declared in <include/boost/url/format.hpp>


template<class... Args>
url
format(
    core::string_view fmt,
    Args&&... args);

» more...


url
format(
    core::string_view fmt,
    std::initializer_list<    _see-below_> args);

» more...

Description

Format arguments according to the format URL string into a url .

The rules for a format URL string are the same as for a `std::format_string`, where replacement fields are delimited by curly braces.

The URL components to which replacement fields belong are identified before replacement is applied and any invalid characters for that formatted argument are percent-escaped.

Hence, the delimiters between URL components, such as `:`, `//`, `?`, and `#`, should be included in the URL format string. Likewise, a format string with a single `"{}"` is interpreted as a path and any replacement characters invalid in this component will be encoded to form a valid URL.


assert(format("{}", "Hello world!").buffer() == "Hello%20world%21");

All replacement fields must be valid and the

resulting URL should be valid after arguments are formatted into the URL.

Because any invalid characters for a URL component are encoded by this function, only replacements in the scheme and port components might be invalid, as these components do not allow percent-encoding of arbitrary characters.


replacement_field ::=  "{" [arg_id] [":" (format_spec | chrono_format_spec)] "}"
arg_id            ::=  integer | identifier
integer           ::=  digit+
digit             ::=  "0"..."9"
identifier        ::=  id_start id_continue*
id_start          ::=  "a"..."z" | "A"..."Z" | "_"
id_continue       ::=  id_start | digit

Format String Syntax

Exceptions

Name	Thrown on
`[object Object]`	contains an invalid format string and the result contains an invalid URL after replacements are applied.

Return Value

A URL holding the formatted result.

Parameters

Name	Description
fmt	The format URL string.
args	Arguments to be formatted.

Synopsis

Declared in <include/boost/url/format.hpp>


template<class... Args>
url
format(
    core::string_view fmt,
    Args&&... args);

Description

Format arguments according to the format URL string into a url .

The rules for a format URL string are the same as for a `std::format_string`, where replacement fields are delimited by curly braces.

The URL components to which replacement fields belong are identified before replacement is applied and any invalid characters for that formatted argument are percent-escaped.


assert(format("{}", "Hello world!").buffer() == "Hello%20world%21");

All replacement fields must be valid and the

resulting URL should be valid after arguments are formatted into the URL.


replacement_field ::=  "{" [arg_id] [":" (format_spec | chrono_format_spec)] "}"
arg_id            ::=  integer | identifier
integer           ::=  digit+
digit             ::=  "0"..."9"
identifier        ::=  id_start id_continue*
id_start          ::=  "a"..."z" | "A"..."Z" | "_"
id_continue       ::=  id_start | digit

Format String Syntax

Exceptions

Name	Thrown on
`fmt`	contains an invalid format string and the result contains an invalid URL after replacements are applied.

Return Value

A URL holding the formatted result.

Parameters

Name	Description
fmt	The format URL string.
args	Arguments to be formatted.

Synopsis

Declared in <include/boost/url/format.hpp>


url
format(
    core::string_view fmt,
    std::initializer_list<    _see-below_> args);

Description

Format arguments according to the format URL string into a url .

This overload allows type-erased arguments to be passed as an initializer_list, which is mostly convenient for named parameters.

All arguments must be convertible to a implementation defined type able to store a type-erased reference to any valid format argument.

The rules for a format URL string are the same as for a `std::format_string`, where replacement fields are delimited by curly braces.

The URL components to which replacement fields belong are identified before replacement is applied and any invalid characters for that formatted argument are percent-escaped.


assert(format("user/{id}", {{"id", 1}}).buffer() == "user/1");

All replacement fields must be valid and the

resulting URL should be valid after arguments are formatted into the URL.


replacement_field ::=  "{" [arg_id] [":" (format_spec | chrono_format_spec)] "}"
arg_id            ::=  integer | identifier
integer           ::=  digit+
digit             ::=  "0"..."9"
identifier        ::=  id_start id_continue*
id_start          ::=  "a"..."z" | "A"..."Z" | "_"
id_continue       ::=  id_start | digit

Format String Syntax

Exceptions

Name	Thrown on
`fmt`	contains an invalid format string and the result contains an invalid URL after replacements are applied.

Return Value

A URL holding the formatted result.

Parameters

Name	Description
fmt	The format URL string.
args	Arguments to be formatted.

Synopsis

Declared in <include/boost/url/format.hpp>


template<class... Args>
void
format_to(
    url_base& u,
    core::string_view fmt,
    Args&&... args);

» more...


void
format_to(
    url_base& u,
    core::string_view fmt,
    std::initializer_list<    _see-below_> args);

» more...

Description

Format arguments according to the format URL string into a url_base .

The rules for a format URL string are the same as for a `std::format_string`, where replacement fields are delimited by curly braces.

The URL components to which replacement fields belong are identified before replacement is applied and any invalid characters for that formatted argument are percent-escaped.


static_url<30> u;
format(u, "{}", "Hello world!");
assert(u.buffer() == "Hello%20world%21");

All replacement fields must be valid and the

resulting URL should be valid after arguments are formatted into the URL.

Strong guarantee.


replacement_field ::=  "{" [arg_id] [":" (format_spec | chrono_format_spec)] "}"
arg_id            ::=  integer | identifier
integer           ::=  digit+
digit             ::=  "0"..."9"
identifier        ::=  id_start id_continue*
id_start          ::=  "a"..."z" | "A"..."Z" | "_"
id_continue       ::=  id_start | digit

Format String Syntax

Exceptions

Name	Thrown on
`[object Object]`	contains an invalid format string and `u` contains an invalid URL after replacements are applied.

Parameters

Name	Description
u	An object that derives from url_base .
fmt	The format URL string.
args	Arguments to be formatted.

Synopsis

Declared in <include/boost/url/format.hpp>


template<class... Args>
void
format_to(
    url_base& u,
    core::string_view fmt,
    Args&&... args);

Description

Format arguments according to the format URL string into a url_base .

The rules for a format URL string are the same as for a `std::format_string`, where replacement fields are delimited by curly braces.

The URL components to which replacement fields belong are identified before replacement is applied and any invalid characters for that formatted argument are percent-escaped.


static_url<30> u;
format(u, "{}", "Hello world!");
assert(u.buffer() == "Hello%20world%21");

All replacement fields must be valid and the

resulting URL should be valid after arguments are formatted into the URL.

Strong guarantee.


replacement_field ::=  "{" [arg_id] [":" (format_spec | chrono_format_spec)] "}"
arg_id            ::=  integer | identifier
integer           ::=  digit+
digit             ::=  "0"..."9"
identifier        ::=  id_start id_continue*
id_start          ::=  "a"..."z" | "A"..."Z" | "_"
id_continue       ::=  id_start | digit

Format String Syntax

Exceptions

Name	Thrown on
`fmt`	contains an invalid format string and `u` contains an invalid URL after replacements are applied.

Parameters

Name	Description
u	An object that derives from url_base .
fmt	The format URL string.
args	Arguments to be formatted.

Synopsis

Declared in <include/boost/url/format.hpp>


void
format_to(
    url_base& u,
    core::string_view fmt,
    std::initializer_list<    _see-below_> args);

Description

Format arguments according to the format URL string into a url_base .

This overload allows type-erased arguments to be passed as an initializer_list, which is mostly convenient for named parameters.

All arguments must be convertible to a implementation defined type able to store a type-erased reference to any valid format argument.

The rules for a format URL string are the same as for a `std::format_string`, where replacement fields are delimited by curly braces.

The URL components to which replacement fields belong are identified before replacement is applied and any invalid characters for that formatted argument are percent-escaped.


static_url<30> u;
format_to(u, "user/{id}", {{"id", 1}})
assert(u.buffer() == "user/1");

All replacement fields must be valid and the

resulting URL should be valid after arguments are formatted into the URL.

Strong guarantee.


replacement_field ::=  "{" [arg_id] [":" (format_spec | chrono_format_spec)] "}"
arg_id            ::=  integer | identifier
integer           ::=  digit+
digit             ::=  "0"..."9"
identifier        ::=  id_start id_continue*
id_start          ::=  "a"..."z" | "A"..."Z" | "_"
id_continue       ::=  id_start | digit

Format String Syntax

Exceptions

Name	Thrown on
`fmt`	contains an invalid format string and `u` contains an invalid URL after replacements are applied.

Parameters

Name	Description
u	An object that derives from url_base .
fmt	The format URL string.
args	Arguments to be formatted.

Synopsis

Declared in <include/boost/url/format.hpp>


template<class T>
    _implementation-defined_
arg(
    core::string_view name,
    T const& arg);

Description

Construct a named argument for a format URL string that contains named replacement fields.

The function parameters should be convertible to an implementation defined type able to store the name and a reference to any type potentially used as a format argument.


assert(format("user/{id}", arg("id", 1)).buffer() == "user/1");

Return Value

An temporary object with reference semantics for a named argument

Parameters

Name	Description
name	The argument name
arg	The argument value

Synopsis

Declared in <include/boost/url/parse.hpp>


system::result<url_view>
parse_absolute_uri(core::string_view s);

Description

This function parses a string according to the grammar below and returns a view referencing the passed string upon success, else returns an error. Ownership of the string is not transferred; the caller is responsible for ensuring that the lifetime of the character buffer extends until the view is no longer being accessed.


system::result< url_view > rv = parse_absolute_uri( "http://example.com/index.htm?id=1" );


absolute-URI    = scheme ":" hier-part [ "?" query ]

hier-part       = "//" authority path-abempty
                / path-absolute
                / path-rootless
                / path-empty

4.3. Absolute URI (rfc3986)

Exceptions

Name	Thrown on
`s.size()	> url_view::max_size`

Return Value

A result containing a value or an error

Parameters

Name	Description
s	The string to parse

Synopsis

Declared in <include/boost/url/parse.hpp>


system::result<url_view>
parse_origin_form(core::string_view s);

Description


system::result< url_view > = parse_origin_form( "/index.htm?layout=mobile" );


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

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

5.3.1. origin-form (rfc7230)

Exceptions

Name	Thrown on
`s.size()	> url_view::max_size`

Return Value

A result containing a value or an error

Parameters

Name	Description
s	The string to parse

Synopsis

Declared in <include/boost/url/parse.hpp>


system::result<url_view>
parse_relative_ref(core::string_view s);

Description


system::result< url_view > = parse_relative_ref( "images/dot.gif?v=hide#a" );


relative-ref  = relative-part [ "?" query ] [ "#" fragment ]

relative-part = "//" authority path-abempty
              / path-absolute
              / path-noscheme
              / path-abempty
              / path-empty

4.2. Relative Reference (rfc3986)

Errata ID: 5428 (rfc3986)

Exceptions

Name	Thrown on
`s.size()	> url_view::max_size`

Return Value

A result containing a value or an error

Parameters

Name	Description
s	The string to parse

Synopsis

Declared in <include/boost/url/parse.hpp>


system::result<url_view>
parse_uri(core::string_view s);

Description


system::result< url_view > = parse_uri( "https://www.example.com/index.htm?id=guest#s1" );


URI           = scheme ":" hier-part [ "?" query ] [ "#" fragment ]

hier-part     = "//" authority path-abempty
              / path-absolute
              / path-rootless
              / path-empty

3. Syntax Components (rfc3986)

Exceptions

Name	Thrown on
`s.size()	> url_view::max_size`

Return Value

A result containing a value or an error

Parameters

Name	Description
s	The string to parse

Synopsis

Declared in <include/boost/url/parse.hpp>


system::result<url_view>
parse_uri_reference(core::string_view s);

Description


system::result< url_view > = parse_uri_reference( "ws://echo.example.com/?name=boost#demo" );


URI-reference = URI / relative-ref

URI           = scheme ":" hier-part [ "?" query ] [ "#" fragment ]

relative-ref  = relative-part [ "?" query ] [ "#" fragment ]

hier-part     = "//" authority path-abempty
              / path-absolute
              / path-rootless
              / path-empty

relative-part = "//" authority path-abempty
              / path-absolute
              / path-noscheme
              / path-abempty
              / path-empty

4.1. URI Reference (rfc3986)

Errata ID: 5428 (rfc3986)

Exceptions

Name	Thrown on
`s.size()	> url_view::max_size`

Return Value

A result containing a value or an error

Parameters

Name	Description
s	The string to parse

Synopsis

Declared in <include/boost/url/static_url.hpp>


template<std::size_t Capacity>
class static_url
    : public static_url_base;

Member Functions

Name	Description
`authority`	Return the authority
`buffer`	Return the url string
`c_str`	Return the url as a null-terminated string
`capacity`	Return the number of characters that can be stored without reallocating
`clear`	Clear the contents while preserving the capacity
`compare`	Return the result of comparing this with another url
`data`	Return a pointer to the url's character buffer
`empty`	Return true if the url is empty
`encoded_authority`	Return the authority.
`encoded_fragment`	Return the fragment
`encoded_host`	Return the host
`encoded_host_address`	Return the host
`encoded_host_and_port`	Return the host and port
`encoded_host_name`	Return the host name
`encoded_origin`	Return the origin
`encoded_params`	Return the query as a container of parameters
`encoded_password`	Return the password
`encoded_path`	Return the path
`encoded_query`	Return the query
`encoded_resource`	Return the resource
`encoded_segments`	Return the path as a container of segments
`encoded_target`	Return the target
`encoded_user`	Return the user
`encoded_userinfo`	Return the userinfo
`encoded_zone_id`	Return the IPv6 Zone ID
`fragment`	Return the fragment
`has_authority`	Return true if an authority is present
`has_fragment`	Return true if a fragment is present
`has_password`	Return true if a password is present
`has_port`	Return true if a port is present
`has_query`	Return true if a query is present
`has_scheme`	Return true a scheme is present
`has_userinfo`	Return true if a userinfo is present
`host`	Return the host
`host_address`	Return the host
`host_ipv4_address`	Return the host IPv4 address
`host_ipv6_address`	Return the host IPv6 address
`host_ipvfuture`	Return the host IPvFuture address
`host_name`	Return the host name
`host_type`	Return the host type
`is_path_absolute`	Return true if the path is absolute
`normalize`	Normalize the URL components
`normalize_authority`	Normalize the URL authority
`normalize_fragment`	Normalize the URL fragment
`normalize_path`	Normalize the URL path
`normalize_query`	Normalize the URL query
`normalize_scheme`	Normalize the URL scheme
`operator core::string_view`	Return the URL as a core::string_view
`operator=`	Assignment
`params`	url_view_base::params Return the query as a container of parameters
`password`	Return the password
`path`	Return the path
`persist`	Return a shared, persistent copy of the url
`port`	Return the port
`port_number`	Return the port
`query`	Return the query
`remove_authority`	Remove the authority
`remove_fragment`	Remove the fragment
`remove_origin`	Remove the origin component
`remove_password`	Remove the password
`remove_port`	Remove the port
`remove_query`	Remove the query
`remove_scheme`	Remove the scheme
`remove_userinfo`	Remove the userinfo
`reserve`	Adjust the capacity without changing the size
`resolve`	Resolve a URL reference against this base URL
`scheme`	Return the scheme
`scheme_id`	Return the scheme
`segments`	Return the path as a container of segments
`set_encoded_authority`	Set the authority
`set_encoded_fragment`	Set the fragment.
`set_encoded_host`	Set the host
`set_encoded_host_address`	Set the host to an address
`set_encoded_host_name`	Set the host to a name
`set_encoded_params`	Set the query params
`set_encoded_password`	Set the password.
`set_encoded_path`	Set the path.
`set_encoded_query`	Set the query
`set_encoded_user`	Set the user
`set_encoded_userinfo`	Set the userinfo.
`set_fragment`	Set the fragment.
`set_host`	Set the host
`set_host_address`	Set the host to an address
`set_host_ipv4`	Set the host to an address
`set_host_ipv6`	Set the host to an address
`set_host_ipvfuture`	Set the host to an address
`set_host_name`	Set the host to a name
`set_params`	Set the query params
`set_password`	Set the password.
`set_path`	Set the path.
`set_path_absolute`	Set if the path is absolute
`set_port`	Set the port
`set_port_number`	Set the port
`set_query`	Set the query
`set_scheme`	Set the scheme
`set_scheme_id`	Set the scheme
`set_user`	Set the user
`set_userinfo`	Set the userinfo
`size`	Return the number of characters in the url
`static_url` [constructor]	Constructor
`user`	Return the user
`userinfo`	Return the userinfo
`zone_id`	Return the IPv6 Zone ID
`~static_url` [destructor]	Destructor

Static Member Functions

Name	Description
`max_size`	Return the maximum number of characters possible

Friends

Name	Description
`operator!=`	Return the result of comparing two URLs
`operator<`	Return the result of comparing two URLs
`operator<<`	Format the url to the output stream
`operator<=`	Return the result of comparing two URLs
`operator==`	Return the result of comparing two URLs
`operator>`	Return the result of comparing two URLs
`operator>=`	Return the result of comparing two URLs
`resolve`	Resolve a URL reference against a base URL

Description

This container owns a url, represented by an inline, null-terminated character buffer with fixed capacity. The contents may be inspected and modified, and the implementation maintains a useful invariant: changes to the url always leave it in a valid state.


static_url< 1024 > u( "https://www.example.com" );


this->capacity() == Capacity + 1

Template Parameters

Name	Description
Capacity	The maximum capacity in characters, not including the null terminator.

Synopsis

Declared in <include/boost/url/static_url.hpp>


virtual
~static_url() = default;

Description

Any params, segments, iterators, or views which reference this object are invalidated. The underlying character buffer is destroyed, invalidating all references to it.

Constructor

Synopsis

Declared in <include/boost/url/static_url.hpp>


static_url() noexcept;

» more...


explicit
static_url(core::string_view s);

» more...


static_url(static_url const& u) noexcept;

» more...


static_url(url_view_base const& u);

» more...

Description

Default constructed urls contain a zero-length string. This matches the grammar for a relative-ref with an empty path and no query or fragment.


static_url< 1024 > u;


this->empty() == true

Constant.

Throws nothing.


relative-ref  = relative-part [ "?" query ] [ "#" fragment ]

4.2. Relative Reference (rfc3986)

Exceptions

Name	Thrown on
`[object Object]`	input does not contain a valid url.
`[object Object]`	would be exceeded.

Parameters

Name	Description
s	The string to parse.
u	The url to copy.

Constructor

Synopsis

Declared in <include/boost/url/static_url.hpp>


static_url() noexcept;

Description

Default constructed urls contain a zero-length string. This matches the grammar for a relative-ref with an empty path and no query or fragment.


static_url< 1024 > u;


this->empty() == true

Constant.

Throws nothing.


relative-ref  = relative-part [ "?" query ] [ "#" fragment ]

4.2. Relative Reference (rfc3986)

Constructor

Synopsis

Declared in <include/boost/url/static_url.hpp>


explicit
static_url(core::string_view s);

Description

This function constructs a url from the string `s`, which must contain a valid URI or relative-ref or else an exception is thrown. The new url retains ownership by making a copy of the passed string.


static_url< 1024 > u( "https://www.example.com" );


return static_url( parse_uri_reference( s ).value() );


this->buffer().data() != s.data()

Linear in `s.size()`.

Exceptions thrown on invalid input.


URI           = scheme ":" hier-part [ "?" query ] [ "#" fragment ]

relative-ref  = relative-part [ "?" query ] [ "#" fragment ]

4.1. URI Reference

Exceptions

Name	Thrown on
`The`	input does not contain a valid url.

Parameters

Name	Description
s	The string to parse.

Constructor

Synopsis

Declared in <include/boost/url/static_url.hpp>


static_url(static_url const& u) noexcept;

Description

The newly constructed object contains a copy of `u`.


this->buffer() == u.buffer() && this->buffer.data() != u.buffer().data()

Linear in `u.size()`.

Exception thrown if maximum size exceeded.

Parameters

Name	Description
u	The url to copy.

Constructor

Synopsis

Declared in <include/boost/url/static_url.hpp>


static_url(url_view_base const& u);

Description

The newly constructed object contains a copy of `u`.


this->buffer() == u.buffer() && this->buffer.data() != u.buffer().data()

Linear in `u.size()`.

Exception thrown if capacity exceeded.

Exceptions

Name	Thrown on
`Capacity`	would be exceeded.

Parameters

Name	Description
u	The url to copy.

Assignment

Synopsis

Declared in <include/boost/url/static_url.hpp>


static_url&
operator=(static_url const& u) noexcept;

» more...


static_url&
operator=(url_view_base const& u);

» more...

Description

The contents of `u` are copied and the previous contents of `this` are discarded. Capacity remains unchanged.


this->buffer() == u.buffer() && this->buffer().data() != u.buffer().data()

Linear in `u.size()`.

Throws nothing.

Exceptions

Name	Thrown on
`[object Object]`	would be exceeded.

Parameters

Name	Description
u	The url to copy.

Assignment

Synopsis

Declared in <include/boost/url/static_url.hpp>


static_url&
operator=(static_url const& u) noexcept;

Description

The contents of `u` are copied and the previous contents of `this` are discarded. Capacity remains unchanged.


this->buffer() == u.buffer() && this->buffer().data() != u.buffer().data()

Linear in `u.size()`.

Throws nothing.

Parameters

Name	Description
u	The url to copy.

Assignment

Synopsis

Declared in <include/boost/url/static_url.hpp>


static_url&
operator=(url_view_base const& u);

Description

The contents of `u` are copied and the previous contents of `this` are discarded.


this->buffer() == u.buffer() && this->buffer().data() != u.buffer().data()

Linear in `u.size()`.

Strong guarantee.

Exception thrown if capacity exceeded.

Exceptions

Name	Thrown on
`Capacity`	would be exceeded.

Parameters

Name	Description
u	The url to copy.

Set the scheme

Synopsis

Declared in <include/boost/url/static_url.hpp>


static_url&
set_scheme(core::string_view s);

Description

The scheme is set to the specified string, which must contain a valid scheme without any trailing colon (':'). Note that schemes are case-insensitive, and the canonical form is lowercased.


assert( url( "http://www.example.com" ).set_scheme( "https" ).scheme_id() == scheme::https );

Linear in `this->size() + s.size()`.

Strong guarantee.

Calls to allocate may throw. Exceptions thrown on invalid input.


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

3.1. Scheme (rfc3986)

Exceptions

Name	Thrown on
`s`	contains an invalid scheme.

Parameters

Name	Description
s	The scheme to set.

Synopsis

Declared in <include/boost/url/static_url.hpp>


static_url&
set_scheme_id(urls::scheme id);

Description


assert( url( "http://example.com/echo.cgi" ).set_scheme_id( scheme::wss ).buffer() == "wss://example.com/echo.cgi" );

Linear in `this->size()`.

Strong guarantee.

Calls to allocate may throw. Exceptions thrown on invalid input.

3.1. Scheme (rfc3986)

Exceptions

Name	Thrown on
`The`	scheme is invalid.

Parameters

Name	Description
id	The scheme to set.

Remove the scheme

Synopsis

Declared in <include/boost/url/static_url.hpp>


static_url&
remove_scheme();

Description

This function removes the scheme if it is present.


assert( url("http://www.example.com/index.htm" ).remove_scheme().buffer() == "//www.example.com/index.htm" );


this->has_scheme() == false && this->scheme_id() == scheme::none

Linear in `this->size()`.

Throws nothing.


URI           = scheme ":" hier-part [ "?" query ] [ "#" fragment ]

3.1. Scheme (rfc3986)

Synopsis

Declared in <include/boost/url/static_url.hpp>


static_url&
set_encoded_authority(pct_string_view s);

Description

This function sets the authority to the specified string. The string may contain percent-escapes.


assert( url().set_encoded_authority( "My%20Computer" ).has_authority() );

Strong guarantee.

Calls to allocate may throw. Exceptions thrown on invalid input.


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

userinfo      = *( unreserved / pct-encoded / sub-delims / ":" )
host          = IP-literal / IPv4address / reg-name
port          = *DIGIT

3.2. Authority (rfc3986)

Exceptions

Name	Thrown on
`The`	string contains an invalid percent-encoding.

Parameters

Name	Description
s	The authority string to set.

Synopsis

Declared in <include/boost/url/static_url.hpp>


static_url&
remove_authority();

Description

This function removes the authority, which includes the userinfo, host, and a port if present.


assert( url( "http://example.com/echo.cgi" ).remove_authority().buffer() == "http:/echo.cgi" );


this->has_authority() == false && this->has_userinfo() == false && this->has_port() == false

Linear in `this->size()`.

Throws nothing.


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

userinfo      = *( unreserved / pct-encoded / sub-delims / ":" )
host          = IP-literal / IPv4address / reg-name
port          = *DIGIT

3.2. Authority (rfc3986)

Synopsis

Declared in <include/boost/url/static_url.hpp>


static_url&
set_userinfo(core::string_view s);

Description

If an unescaped colon exists, the characters up to the colon become the user and the rest of the characters after the colon become the password. In this case has_password returns true. Otherwise,

If there is no colon, the user is set to the string. The function has_password returns false.

NOTE

The interpretation of the userinfo as individual user and password components is scheme-dependent. Transmitting passwords in URLs is deprecated.


assert( url( "http://example.com" ).set_userinfo( "user:pass" ).encoded_user() == "user" );

Linear in `this->size() + s.size()`.

Strong guarantee.

Calls to allocate may throw.


userinfo      = [ [ user ] [ ':' password ] ]

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

3.2.1. User Information (rfc3986)

Parameters

Name	Description
s	The string to set.

Synopsis

Declared in <include/boost/url/static_url.hpp>


static_url&
set_encoded_userinfo(pct_string_view s);

Description

If an unescaped colon exists, the characters up to the colon become the user and the rest of the characters after the colon become the password. In this case has_password returns true. Otherwise,

If there is no colon, the user is set to the string. The function has_password returns false.

NOTE

The interpretation of the userinfo as individual user and password components is scheme-dependent. Transmitting passwords in URLs is deprecated.


assert( url( "http://example.com" ).set_encoded_userinfo( "john%20doe" ).user() == "john doe" );

Linear in `this->size() + s.size()`.

Strong guarantee.

Calls to allocate may throw. Exceptions thrown on invalid input.


userinfo      = [ [ user ] [ ':' password ] ]

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

3.2.1. User Information (rfc3986)

Exceptions

Name	Thrown on
`s`	contains an invalid percent-encoding.

Parameters

Name	Description
s	The string to set.

Synopsis

Declared in <include/boost/url/static_url.hpp>


static_url&
remove_userinfo() noexcept;

Description

This function removes the userinfo if present, without removing any authority.


assert( url( "http://user@example.com" ).remove_userinfo().has_userinfo() == false );


this->has_userinfo() == false && this->encoded_userinfo().empty == true

Linear in `this->size()`.

Throws nothing.


userinfo      = [ [ user ] [ ':' password ] ]

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

3.2.1. User Information (rfc3986)

Synopsis

Declared in <include/boost/url/static_url.hpp>


static_url&
set_user(core::string_view s);

Description

This function sets the user part of the userinfo to the string. Any special or reserved characters in the string are automatically percent-encoded.


assert( url().set_user("john doe").encoded_userinfo() == "john%20doe" );


this->has_authority() == true && this->has_userinfo() == true

Linear in `this->size() + s.size()`.

Strong guarantee.

Calls to allocate may throw.


userinfo      = [ [ user ] [ ':' password ] ]

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

3.2.1. User Information (rfc3986)

Parameters

Name	Description
s	The string to set.

Synopsis

Declared in <include/boost/url/static_url.hpp>


static_url&
set_encoded_user(pct_string_view s);

Description


assert( url().set_encoded_user("john%20doe").userinfo() == "john doe" );


this->has_authority() == true && this->has_userinfo() == true

Linear in `this->size() + s.size()`.

Strong guarantee.

Calls to allocate may throw.


userinfo      = [ [ user ] [ ':' password ] ]

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

3.2.1. User Information (rfc3986)

Exceptions

Name	Thrown on
`s`	contains an invalid percent-encoding.

Parameters

Name	Description
s	The string to set.

Synopsis

Declared in <include/boost/url/static_url.hpp>


static_url&
set_password(core::string_view s);

Description

This function sets the password in the userinfo to the string. Reserved characters in the string are percent-escaped in the result.

NOTE

The interpretation of the userinfo as individual user and password components is scheme-dependent. Transmitting passwords in URLs is deprecated.


assert( url("http://user@example.com").set_password( "pass" ).encoded_userinfo() == "user:pass" );


this->has_password() == true && this->password() == s

Strong guarantee.

Calls to allocate may throw.


userinfo      = [ [ user ] [ ':' password ] ]

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

3.2.1. User Information (rfc3986)

Parameters

Name	Description
s	The string to set. This string may contain any characters, including nulls.

Synopsis

Declared in <include/boost/url/static_url.hpp>


static_url&
set_encoded_password(pct_string_view s);

Description

NOTE

The interpretation of the userinfo as individual user and password components is scheme-dependent. Transmitting passwords in URLs is deprecated.


assert( url("http://user@example.com").set_encoded_password( "pass" ).encoded_userinfo() == "user:pass" );


this->has_password() == true

Strong guarantee.

Calls to allocate may throw.


userinfo      = [ [ user ] [ ':' password ] ]

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

3.2.1. User Information (rfc3986)

Exceptions

Name	Thrown on
`s`	contains an invalid percent-encoding.

Parameters

Name	Description
s	The string to set. This string may contain any characters, including nulls.

Synopsis

Declared in <include/boost/url/static_url.hpp>


static_url&
remove_password() noexcept;

Description

This function removes the password from the userinfo if a password exists. If there is no userinfo or no authority, the call has no effect.

NOTE

The interpretation of the userinfo as individual user and password components is scheme-dependent. Transmitting passwords in URLs is deprecated.


assert( url( "http://user:pass@example.com" ).remove_password().authority().buffer() == "user@example.com" );


this->has_password() == false && this->encoded_password().empty() == true

Linear in `this->size()`.

Throws nothing.


userinfo      = [ [ user ] [ ':' password ] ]

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

3.2.1. User Information (rfc3986)

Synopsis

Declared in <include/boost/url/static_url.hpp>


static_url&
set_host(core::string_view s);

Description

Depending on the contents of the passed string, this function sets the host:

If the string is a valid IPv4 address, then the host is set to the address. The host type is host_type::ipv4 .

If the string is a valid IPv6 address enclosed in square brackets, then the host is set to that address. The host type is host_type::ipv6 .

If the string is a valid IPvFuture address enclosed in square brackets, then the host is set to that address. The host type is host_type::ipvfuture .

Otherwise, the host name is set to the string, which may be empty. Reserved characters in the string are percent-escaped in the result. The host type is host_type::name .

In all cases, when this function returns, the URL contains an authority.


assert( url( "http://www.example.com" ).set_host( "127.0.0.1" ).buffer() == "http://127.0.0.1" );


this->has_authority() == true

Linear in `this->size() + s.size()`.

Strong guarantee.

Calls to allocate may throw.


host        = IP-literal / IPv4address / reg-name

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

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

IPv4 (Wikipedia)

IP Version 6 Addressing Architecture (rfc4291)

3.2.2. Host (rfc3986)

Parameters

Name	Description
s	The string to set.

Synopsis

Declared in <include/boost/url/static_url.hpp>


static_url&
set_encoded_host(pct_string_view s);

Description

Depending on the contents of the passed string, this function sets the host:

If the string is a valid IPv4 address, then the host is set to the address. The host type is host_type::ipv4 .

If the string is a valid IPv6 address enclosed in square brackets, then the host is set to that address. The host type is host_type::ipv6 .

If the string is a valid IPvFuture address enclosed in square brackets, then the host is set to that address. The host type is host_type::ipvfuture .

In all cases, when this function returns, the URL contains an authority.


assert( url( "http://www.example.com" ).set_host( "127.0.0.1" ).buffer() == "http://127.0.0.1" );


this->has_authority() == true

Linear in `this->size() + s.size()`.

Strong guarantee.

Calls to allocate may throw. Exceptions thrown on invalid input.


host        = IP-literal / IPv4address / reg-name

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

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

IPv4 (Wikipedia)

IP Version 6 Addressing Architecture (rfc4291)

3.2.2. Host (rfc3986)

Exceptions

Name	Thrown on
`s`	contains an invalid percent-encoding.

Parameters

Name	Description
s	The string to set.

Synopsis

Declared in <include/boost/url/static_url.hpp>


static_url&
set_host_address(core::string_view s);

Description

Depending on the contents of the passed string, this function sets the host:

If the string is a valid IPv4 address, then the host is set to the address. The host type is host_type::ipv4 .

If the string is a valid IPv6 address, then the host is set to that address. The host type is host_type::ipv6 .

If the string is a valid IPvFuture, then the host is set to that address. The host type is host_type::ipvfuture .

Otherwise, the host name is set to the string, which may be empty. Reserved characters in the string are percent-escaped in the result. The host type is host_type::name .

In all cases, when this function returns, the URL contains an authority.


assert( url( "http://www.example.com" ).set_host_address( "127.0.0.1" ).buffer() == "http://127.0.0.1" );


this->has_authority() == true

Linear in `s.size()`.

Strong guarantee.

Calls to allocate may throw.


IPv4address = dec-octet "." dec-octet "." dec-octet "." dec-octet

dec-octet   = DIGIT                 ; 0-9
            / %x31-39 DIGIT         ; 10-99
            / "1" 2DIGIT            ; 100-199
            / "2" %x30-34 DIGIT     ; 200-249
            / "25" %x30-35          ; 250-255

IPv6address =                            6( h16 ":" ) ls32
            /                       "::" 5( h16 ":" ) ls32
            / [               h16 ] "::" 4( h16 ":" ) ls32
            / [ *1( h16 ":" ) h16 ] "::" 3( h16 ":" ) ls32
            / [ *2( h16 ":" ) h16 ] "::" 2( h16 ":" ) ls32
            / [ *3( h16 ":" ) h16 ] "::"    h16 ":"   ls32
            / [ *4( h16 ":" ) h16 ] "::"              ls32
            / [ *5( h16 ":" ) h16 ] "::"              h16
            / [ *6( h16 ":" ) h16 ] "::"

ls32        = ( h16 ":" h16 ) / IPv4address
            ; least-significant 32 bits of address

h16         = 1*4HEXDIG
            ; 16 bits of address represented in hexadecimal

IPvFuture     = "v" 1*HEXDIG "." 1*( unreserved / sub-delims / ":" )

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

IPv4 (Wikipedia)

IP Version 6 Addressing Architecture (rfc4291)

3.2.2. Host (rfc3986)

Parameters

Name	Description
s	The string to set.

Synopsis

Declared in <include/boost/url/static_url.hpp>


static_url&
set_encoded_host_address(pct_string_view s);

Description

Depending on the contents of the passed string, this function sets the host:

If the string is a valid IPv4 address, then the host is set to the address. The host type is host_type::ipv4 .

If the string is a valid IPv6 address, then the host is set to that address. The host type is host_type::ipv6 .

If the string is a valid IPvFuture, then the host is set to that address. The host type is host_type::ipvfuture .

In all cases, when this function returns, the URL contains an authority.


assert( url( "http://www.example.com" ).set_host( "127.0.0.1" ).buffer() == "http://127.0.0.1" );


this->has_authority() == true

Linear in `this->size() + s.size()`.

Strong guarantee.

Calls to allocate may throw. Exceptions thrown on invalid input.


IPv4address = dec-octet "." dec-octet "." dec-octet "." dec-octet

dec-octet   = DIGIT                 ; 0-9
            / %x31-39 DIGIT         ; 10-99
            / "1" 2DIGIT            ; 100-199
            / "2" %x30-34 DIGIT     ; 200-249
            / "25" %x30-35          ; 250-255

IPv6address =                            6( h16 ":" ) ls32
            /                       "::" 5( h16 ":" ) ls32
            / [               h16 ] "::" 4( h16 ":" ) ls32
            / [ *1( h16 ":" ) h16 ] "::" 3( h16 ":" ) ls32
            / [ *2( h16 ":" ) h16 ] "::" 2( h16 ":" ) ls32
            / [ *3( h16 ":" ) h16 ] "::"    h16 ":"   ls32
            / [ *4( h16 ":" ) h16 ] "::"              ls32
            / [ *5( h16 ":" ) h16 ] "::"              h16
            / [ *6( h16 ":" ) h16 ] "::"

ls32        = ( h16 ":" h16 ) / IPv4address
            ; least-significant 32 bits of address

h16         = 1*4HEXDIG
            ; 16 bits of address represented in hexadecimal

IPvFuture     = "v" 1*HEXDIG "." 1*( unreserved / sub-delims / ":" )

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

IPv4 (Wikipedia)

IP Version 6 Addressing Architecture (rfc4291)

3.2.2. Host (rfc3986)

Exceptions

Name	Thrown on
`s`	contains an invalid percent-encoding.

Parameters

Name	Description
s	The string to set.

Synopsis

Declared in <include/boost/url/static_url.hpp>


static_url&
set_host_ipv4(ipv4_address const& addr);

Description

The host is set to the specified IPv4 address. The host type is host_type::ipv4 .


assert( url("http://www.example.com").set_host_ipv4( ipv4_address( "127.0.0.1" ) ).buffer() == "http://127.0.0.1" );

Linear in `this->size()`.


this->has_authority() == true && this->host_ipv4_address() == addr && this->host_type() == host_type::ipv4

Strong guarantee.

Calls to allocate may throw.


IPv4address = dec-octet "." dec-octet "." dec-octet "." dec-octet

dec-octet   = DIGIT                 ; 0-9
            / %x31-39 DIGIT         ; 10-99
            / "1" 2DIGIT            ; 100-199
            / "2" %x30-34 DIGIT     ; 200-249
            / "25" %x30-35          ; 250-255

IPv4 (Wikipedia)

3.2.2. Host (rfc3986)

Parameters

Name	Description
addr	The address to set.

Synopsis

Declared in <include/boost/url/static_url.hpp>


static_url&
set_host_ipv6(ipv6_address const& addr);

Description

The host is set to the specified IPv6 address. The host type is host_type::ipv6 .


assert( url().set_host_ipv6( ipv6_address( "1::6:c0a8:1" ) ).authority().buffer() == "[1::6:c0a8:1]" );


this->has_authority() == true && this->host_ipv6_address() == addr && this->host_type() == host_type::ipv6

Linear in `this->size()`.

Strong guarantee.

Calls to allocate may throw.


IPv6address =                            6( h16 ":" ) ls32
            /                       "::" 5( h16 ":" ) ls32
            / [               h16 ] "::" 4( h16 ":" ) ls32
            / [ *1( h16 ":" ) h16 ] "::" 3( h16 ":" ) ls32
            / [ *2( h16 ":" ) h16 ] "::" 2( h16 ":" ) ls32
            / [ *3( h16 ":" ) h16 ] "::"    h16 ":"   ls32
            / [ *4( h16 ":" ) h16 ] "::"              ls32
            / [ *5( h16 ":" ) h16 ] "::"              h16
            / [ *6( h16 ":" ) h16 ] "::"

ls32        = ( h16 ":" h16 ) / IPv4address
            ; least-significant 32 bits of address

h16         = 1*4HEXDIG
            ; 16 bits of address represented in hexadecimal

IP Version 6 Addressing Architecture (rfc4291)

3.2.2. Host (rfc3986)

Parameters

Name	Description
addr	The address to set.

Synopsis

Declared in <include/boost/url/static_url.hpp>


static_url&
set_host_ipvfuture(core::string_view s);

Description

The host is set to the specified IPvFuture string. The host type is host_type::ipvfuture .


assert( url().set_host_ipvfuture( "v42.bis" ).buffer() == "//[v42.bis]" );

Linear in `this->size() + s.size()`.


this->has_authority() == true && this->host_ipvfuture) == s && this->host_type() == host_type::ipvfuture

Strong guarantee.

Calls to allocate may throw. Exceptions thrown on invalid input.


IPvFuture     = "v" 1*HEXDIG "." 1*( unreserved / sub-delims / ":" )

3.2.2. Host (rfc3986)

Exceptions

Name	Thrown on
`s`	contains an invalid percent-encoding.

Parameters

Name	Description
s	The string to set.

Synopsis

Declared in <include/boost/url/static_url.hpp>


static_url&
set_host_name(core::string_view s);

Description

The host is set to the specified string, which may be empty. Reserved characters in the string are percent-escaped in the result. The host type is host_type::name .


assert( url( "http://www.example.com/index.htm").set_host_name( "localhost" ).host_address() == "localhost" );


this->has_authority() == true && this->host_ipv6_address() == addr && this->host_type() == host_type::name

Strong guarantee.

Calls to allocate may throw.


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

3.2.2. Host (rfc3986)

Parameters

Name	Description
s	The string to set.

Synopsis

Declared in <include/boost/url/static_url.hpp>


static_url&
set_encoded_host_name(pct_string_view s);

Description


assert( url( "http://www.example.com/index.htm").set_encoded_host_name( "localhost" ).host_address() == "localhost" );


this->has_authority() == true && this->host_ipv6_address() == addr && this->host_type() == host_type::name

Strong guarantee.

Calls to allocate may throw. Exceptions thrown on invalid input.


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

3.2.2. Host (rfc3986)

Exceptions

Name	Thrown on
`s`	contains an invalid percent-encoding.

Parameters

Name	Description
s	The string to set.

Synopsis

Declared in <include/boost/url/static_url.hpp>


static_url&
set_port_number(std::uint16_t n);

Description

The port is set to the specified integer.


assert( url( "http://www.example.com" ).set_port_number( 8080 ).authority().buffer() == "www.example.com:8080" );


this->has_authority() == true && this->has_port() == true && this->port_number() == n

Linear in `this->size()`.

Strong guarantee.

Calls to allocate may throw.


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

port          = *DIGIT

3.2.3. Port (rfc3986)

Parameters

Name	Description
n	The port number to set.

Synopsis

Declared in <include/boost/url/static_url.hpp>


static_url&
set_port(core::string_view s);

Description

This port is set to the string, which must contain only digits or be empty. An empty port string is distinct from having no port.


assert( url( "http://www.example.com" ).set_port( "8080" ).authority().buffer() == "www.example.com:8080" );


this->has_port() == true && this->port_number() == n && this->port() == std::to_string(n)

Strong guarantee.

Calls to allocate may throw. Exceptions thrown on invalid input.


port          = *DIGIT

3.2.3. Port (rfc3986)

Exceptions

Name	Thrown on
`s`	does not contain a valid port.

Parameters

Name	Description
s	The port string to set.

Synopsis

Declared in <include/boost/url/static_url.hpp>


static_url&
remove_port() noexcept;

Description

If a port exists, it is removed. The rest of the authority is unchanged.


assert( url( "http://www.example.com:80" ).remove_port().authority().buffer() == "www.example.com" );


this->has_port() == false && this->port_number() == 0 && this->port() == ""

Linear in `this->size()`.

Throws nothing.


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

port          = *DIGIT

3.2.3. Port (rfc3986)

Synopsis

Declared in <include/boost/url/static_url.hpp>


static_url&
set_path(core::string_view s);

Description

This function sets the path to the string, which may be empty. Reserved characters in the string are percent-escaped in the result.

NOTE

The library may adjust the final result to ensure that no other parts of the url is semantically affected.

NOTE


url u( "http://www.example.com" );

u.set_path( "path/to/file.txt" );

assert( u.path() == "/path/to/file.txt" );

Linear in `this->size() + s.size()`.

Strong guarantee.

Calls to allocate may throw.


path          = path-abempty    ; begins with "/" or is empty
              / path-absolute   ; begins with "/" but not "//"
              / path-noscheme   ; begins with a non-colon segment
              / path-rootless   ; begins with a segment
              / path-empty      ; zero characters

path-abempty  = *( "/" segment )
path-absolute = "/" [ segment-nz *( "/" segment ) ]
path-noscheme = segment-nz-nc *( "/" segment )
path-rootless = segment-nz *( "/" segment )
path-empty    = 0

3.3. Path (rfc3986)

Parameters

Name	Description
s	The string to set.

Synopsis

Declared in <include/boost/url/static_url.hpp>


static_url&
set_encoded_path(pct_string_view s);

Description

NOTE

The library may adjust the final result to ensure that no other parts of the url is semantically affected.


url u( "http://www.example.com" );

u.set_encoded_path( "path/to/file.txt" );

assert( u.encoded_path() == "/path/to/file.txt" );

Linear in `this->size() + s.size()`.

Strong guarantee.

Calls to allocate may throw. Exceptions thrown on invalid input.


path          = path-abempty    ; begins with "/" or is empty
              / path-absolute   ; begins with "/" but not "//"
              / path-noscheme   ; begins with a non-colon segment
              / path-rootless   ; begins with a segment
              / path-empty      ; zero characters

path-abempty  = *( "/" segment )
path-absolute = "/" [ segment-nz *( "/" segment ) ]
path-noscheme = segment-nz-nc *( "/" segment )
path-rootless = segment-nz *( "/" segment )
path-empty    = 0

3.3. Path (rfc3986)

Exceptions

Name	Thrown on
`s`	contains an invalid percent-encoding.

Parameters

Name	Description
s	The string to set.

Synopsis

Declared in <include/boost/url/static_url.hpp>


static_url&
set_query(core::string_view s);

Description

This sets the query to the string, which can be empty. An empty query is distinct from having no query. Reserved characters in the string are percent-escaped in the result.


assert( url( "http://example.com" ).set_query( "id=42" ).query() == "id=42" );


this->has_query() == true && this->query() == s

Strong guarantee.

Calls to allocate may throw.


query           = *( pchar / "/" / "?" )

query-param     = key [ "=" value ]
query-params    = [ query-param ] *( "&" query-param )

3.4. Query (rfc3986)

Query string (Wikipedia)

Parameters

Name	Description
s	The string to set.

Synopsis

Declared in <include/boost/url/static_url.hpp>


static_url&
set_encoded_query(pct_string_view s);

Description


assert( url( "http://example.com" ).set_encoded_query( "id=42" ).encoded_query() == "id=42" );


this->has_query() == true && this->query() == decode_view( s );

Strong guarantee.

Calls to allocate may throw. Exceptions thrown on invalid input.


query           = *( pchar / "/" / "?" )

query-param     = key [ "=" value ]
query-params    = [ query-param ] *( "&" query-param )

3.4. Query (rfc3986)

Query string (Wikipedia)

Exceptions

Name	Thrown on
`s`	contains an invalid percent-encoding.

Parameters

Name	Description
s	The string to set.

Synopsis

Declared in <include/boost/url/static_url.hpp>


static_url&
set_params(
    std::initializer_list<param_view> ps,
    encoding_opts opts = = {});

Description

This sets the query params to the list of param_view, which can be empty.

An empty list of params is distinct from having no params.

Reserved characters in the string are percent-escaped in the result.


assert( url( "http://example.com" ).set_params( {"id", "42"} ).query() == "id=42" );


this->has_query() == true

Strong guarantee.

Calls to allocate may throw.

Linear.


query           = *( pchar / "/" / "?" )

query-param     = key [ "=" value ]
query-params    = [ query-param ] *( "&" query-param )

://en.wikipedia.org/wiki/Query_string" >Query string (Wikipedia)

Parameters

Name	Description
ps	The params to set.
opts	The options for encoding.

Synopsis

Declared in <include/boost/url/static_url.hpp>


static_url&
remove_query() noexcept;

Description

If a query is present, it is removed. An empty query is distinct from having no query.


assert( url( "http://www.example.com?id=42" ).remove_query().buffer() == "http://www.example.com" );


this->has_query() == false && this->params().empty()

Throws nothing.


query           = *( pchar / "/" / "?" )

query-param     = key [ "=" value ]
query-params    = [ query-param ] *( "&" query-param )

3.4. Query (rfc3986)

Query string (Wikipedia)

Synopsis

Declared in <include/boost/url/static_url.hpp>


static_url&
remove_fragment() noexcept;

Description

This function removes the fragment. An empty fragment is distinct from having no fragment.


assert( url( "?first=john&last=doe#anchor" ).remove_fragment().buffer() == "?first=john&last=doe" );


this->has_fragment() == false && this->encoded_fragment() == ""

Constant.

Throws nothing.


fragment    = *( pchar / "/" / "?" )

3.5. Fragment

Synopsis

Declared in <include/boost/url/static_url.hpp>


static_url&
set_fragment(core::string_view s);

Description


assert( url("?first=john&last=doe" ).set_encoded_fragment( "john doe" ).encoded_fragment() == "john%20doe" );


this->has_fragment() == true && this->fragment() == s

Linear in `this->size() + s.size()`.

Strong guarantee.

Calls to allocate may throw.


fragment    = *( pchar / "/" / "?" )

3.5. Fragment

Parameters

Name	Description
s	The string to set.

Synopsis

Declared in <include/boost/url/static_url.hpp>


static_url&
set_encoded_fragment(pct_string_view s);

Description


assert( url("?first=john&last=doe" ).set_encoded_fragment( "john%2Ddoe" ).fragment() == "john-doe" );


this->has_fragment() == true && this->fragment() == decode_view( s )

Linear in `this->size() + s.size()`.

Strong guarantee.

Calls to allocate may throw. Exceptions thrown on invalid input.


fragment    = *( pchar / "/" / "?" )

3.5. Fragment

Exceptions

Name	Thrown on
`s`	contains an invalid percent-encoding.

Parameters

Name	Description
s	The string to set.

Synopsis

Declared in <include/boost/url/static_url.hpp>


static_url&
remove_origin();

Description

This function removes the origin, which consists of the scheme and authority.


assert( url( "http://www.example.com/index.htm" ).remove_origin().buffer() == "/index.htm" );


this->scheme_id() == scheme::none && this->has_authority() == false

Linear in `this->size()`.

Throws nothing.

Normalize the URL components

Synopsis

Declared in <include/boost/url/static_url.hpp>


static_url&
normalize();

Description

Applies Syntax-based normalization to all components of the URL.

Strong guarantee.

Calls to allocate may throw.

6.2.2 Syntax-Based Normalization (rfc3986)

Normalize the URL scheme

Synopsis

Declared in <include/boost/url/static_url.hpp>


static_url&
normalize_scheme();

Description

Applies Syntax-based normalization to the URL scheme.

The scheme is normalized to lowercase.

Strong guarantee.

Calls to allocate may throw.

6.2.2 Syntax-Based Normalization (rfc3986)

Normalize the URL authority

Synopsis

Declared in <include/boost/url/static_url.hpp>


static_url&
normalize_authority();

Description

Applies Syntax-based normalization to the URL authority.

Percent-encoding triplets are normalized to uppercase letters. Percent-encoded octets that correspond to unreserved characters are decoded.

Strong guarantee.

Calls to allocate may throw.

6.2.2 Syntax-Based Normalization (rfc3986)

Normalize the URL path

Synopsis

Declared in <include/boost/url/static_url.hpp>


static_url&
normalize_path();

Description

Applies Syntax-based normalization to the URL path.

Percent-encoding triplets are normalized to uppercase letters. Percent-encoded octets that correspond to unreserved characters are decoded. Redundant path-segments are removed.

Strong guarantee.

Calls to allocate may throw.

6.2.2 Syntax-Based Normalization (rfc3986)

Normalize the URL query

Synopsis

Declared in <include/boost/url/static_url.hpp>


static_url&
normalize_query();

Description

Applies Syntax-based normalization to the URL query.

Percent-encoding triplets are normalized to uppercase letters. Percent-encoded octets that correspond to unreserved characters are decoded.

Strong guarantee.

Calls to allocate may throw.

6.2.2 Syntax-Based Normalization (rfc3986)

Normalize the URL fragment

Synopsis

Declared in <include/boost/url/static_url.hpp>


static_url&
normalize_fragment();

Description

Applies Syntax-based normalization to the URL fragment.

Percent-encoding triplets are normalized to uppercase letters. Percent-encoded octets that correspond to unreserved characters are decoded.

Strong guarantee.

Calls to allocate may throw.

6.2.2 Syntax-Based Normalization (rfc3986)

Common implementation for all static URLs

Synopsis

Declared in <include/boost/url/static_url.hpp>


class static_url_base
    : public url_base;

Member Functions

Name	Description
`authority`	Return the authority
`buffer`	Return the url string
`c_str`	Return the url as a null-terminated string
`capacity`	Return the number of characters that can be stored without reallocating
`clear`	Clear the contents while preserving the capacity
`compare`	Return the result of comparing this with another url
`data`	Return a pointer to the url's character buffer
`empty`	Return true if the url is empty
`encoded_authority`	Return the authority.
`encoded_fragment`	Return the fragment
`encoded_host`	Return the host
`encoded_host_address`	Return the host
`encoded_host_and_port`	Return the host and port
`encoded_host_name`	Return the host name
`encoded_origin`	Return the origin
`encoded_params`	Return the query as a container of parameters
`encoded_password`	Return the password
`encoded_path`	Return the path
`encoded_query`	Return the query
`encoded_resource`	Return the resource
`encoded_segments`	Return the path as a container of segments
`encoded_target`	Return the target
`encoded_user`	Return the user
`encoded_userinfo`	Return the userinfo
`encoded_zone_id`	Return the IPv6 Zone ID
`fragment`	Return the fragment
`has_authority`	Return true if an authority is present
`has_fragment`	Return true if a fragment is present
`has_password`	Return true if a password is present
`has_port`	Return true if a port is present
`has_query`	Return true if a query is present
`has_scheme`	Return true a scheme is present
`has_userinfo`	Return true if a userinfo is present
`host`	Return the host
`host_address`	Return the host
`host_ipv4_address`	Return the host IPv4 address
`host_ipv6_address`	Return the host IPv6 address
`host_ipvfuture`	Return the host IPvFuture address
`host_name`	Return the host name
`host_type`	Return the host type
`is_path_absolute`	Return true if the path is absolute
`normalize`	Normalize the URL components
`normalize_authority`	Normalize the URL authority
`normalize_fragment`	Normalize the URL fragment
`normalize_path`	Normalize the URL path
`normalize_query`	Normalize the URL query
`normalize_scheme`	Normalize the URL scheme
`operator core::string_view`	Return the URL as a core::string_view
`params`	url_view_base::params Return the query as a container of parameters
`password`	Return the password
`path`	Return the path
`persist`	Return a shared, persistent copy of the url
`port`	Return the port
`port_number`	Return the port
`query`	Return the query
`remove_authority`	Remove the authority
`remove_fragment`	Remove the fragment
`remove_origin`	Remove the origin component
`remove_password`	Remove the password
`remove_port`	Remove the port
`remove_query`	Remove the query
`remove_scheme`	Remove the scheme
`remove_userinfo`	Remove the userinfo
`reserve`	Adjust the capacity without changing the size
`resolve`	Resolve a URL reference against this base URL
`scheme`	Return the scheme
`scheme_id`	Return the scheme
`segments`	Return the path as a container of segments
`set_encoded_authority`	Set the authority
`set_encoded_fragment`	Set the fragment.
`set_encoded_host`	Set the host
`set_encoded_host_address`	Set the host to an address
`set_encoded_host_name`	Set the host to a name
`set_encoded_params`	Set the query params
`set_encoded_password`	Set the password.
`set_encoded_path`	Set the path.
`set_encoded_query`	Set the query
`set_encoded_user`	Set the user
`set_encoded_userinfo`	Set the userinfo.
`set_fragment`	Set the fragment.
`set_host`	Set the host
`set_host_address`	Set the host to an address
`set_host_ipv4`	Set the host to an address
`set_host_ipv6`	Set the host to an address
`set_host_ipvfuture`	Set the host to an address
`set_host_name`	Set the host to a name
`set_params`	Set the query params
`set_password`	Set the password.
`set_path`	Set the path.
`set_path_absolute`	Set if the path is absolute
`set_port`	Set the port
`set_port_number`	Set the port
`set_query`	Set the query
`set_scheme`	Set the scheme
`set_scheme_id`	Set the scheme
`set_user`	Set the user
`set_userinfo`	Set the userinfo
`size`	Return the number of characters in the url
`user`	Return the user
`userinfo`	Return the userinfo
`zone_id`	Return the IPv6 Zone ID

Static Member Functions

Name	Description
`max_size`	Return the maximum number of characters possible

Friends

Name	Description
`operator!=`	Return the result of comparing two URLs
`operator<`	Return the result of comparing two URLs
`operator<<`	Format the url to the output stream
`operator<=`	Return the result of comparing two URLs
`operator==`	Return the result of comparing two URLs
`operator>`	Return the result of comparing two URLs
`operator>=`	Return the result of comparing two URLs
`resolve`	Resolve a URL reference against a base URL

Description

This base class is used by the library to provide common functionality for static URLs. Users should not use this class directly. Instead, construct an instance of one of the containers or call a parsing function.

The type of string_view used by the library

Synopsis

Declared in <include/boost/url/string_view.hpp>


using string_view = boost::core::string_view;

Description

String views are used to pass character buffers into or out of functions. Ownership of the underlying character buffer is not transferred; the caller is responsible for ensuring that the lifetime of character buffer extends until it is no longer referenced.

WARNING

This alias is no longer supported and should not be used in new code. Please use `core::string_view` instead.

This alias is included for backwards compatibility with earlier versions of the library.

However, it will be removed in future releases, and using it in new code is not recommended.

Please use the updated version instead to ensure compatibility with future versions of the library.

Rule for absolute-URI

Synopsis

Declared in <include/boost/url/rfc/absolute_uri_rule.hpp>


constexpr
    _implementation-defined_ absolute_uri_rule = {};

Description


using value_type = url_view;

Rules are used with the function

grammar::parse .


system::result< url_view > rv = grammar::parse( "http://example.com/index.htm?id=1", absolute_uri_rule );


absolute-URI    = scheme ":" hier-part [ "?" query ]

hier-part       = "//" authority path-abempty
                / path-absolute
                / path-rootless
                / path-empty

4.3. Absolute URI (rfc3986)

Synopsis

Declared in <include/boost/url/rfc/authority_rule.hpp>


constexpr
    _implementation-defined_ authority_rule = {};

Description


using value_type = authority_view;

Rules are used with the function

grammar::parse .


system::result< authority_view > rv = grammar::parse( "user:pass@example.com:8080", authority_rule );


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

3.2. Authority (rfc3986)

Synopsis

Declared in <include/boost/url/rfc/gen_delim_chars.hpp>


constexpr
grammar::lut_chars const gen_delim_chars = ":/?#[]@";

Description

Character sets are used with rules and

the functions grammar::find_if and grammar::find_if_not .


system::result< decode_view > rv = grammar::parse( "Program%20Files", pct_encoded_rule( gen_delim_chars ) );


gen-delims    = ":" / "/" / "?" / "#" / "[" / "]" / "@"

2.2. Reserved Characters (rfc3986)

Synopsis

Declared in <include/boost/url/rfc/ipv4_address_rule.hpp>


constexpr
    _implementation-defined_ ipv4_address_rule = {};

Description


using value_type = ipv4_address;

Rules are used with the function

grammar::parse .


system::result< ipv4_address > rv = grammar::parse( "192.168.0.1", ipv4_address_rule );


IPv4address = dec-octet "." dec-octet "." dec-octet "." dec-octet

dec-octet   = DIGIT                 ; 0-9
            / %x31-39 DIGIT         ; 10-99
            / "1" 2DIGIT            ; 100-199
            / "2" %x30-34 DIGIT     ; 200-249
            / "25" %x30-35          ; 250-255

IPv4 (Wikipedia)

3.2.2. Host (rfc3986)

Synopsis

Declared in <include/boost/url/rfc/ipv6_address_rule.hpp>


constexpr
    _implementation-defined_ ipv6_address_rule = {};

Description


using value_type = ipv6_address;

Rules are used with the function

grammar::parse .


system::result< ipv6_address > rv = grammar::parse( "2001:0db8:85a3:0000:0000:8a2e:0370:7334", ipv6_address_rule );


IPv6address =                            6( h16 ":" ) ls32
            /                       "::" 5( h16 ":" ) ls32
            / [               h16 ] "::" 4( h16 ":" ) ls32
            / [ *1( h16 ":" ) h16 ] "::" 3( h16 ":" ) ls32
            / [ *2( h16 ":" ) h16 ] "::" 2( h16 ":" ) ls32
            / [ *3( h16 ":" ) h16 ] "::"    h16 ":"   ls32
            / [ *4( h16 ":" ) h16 ] "::"              ls32
            / [ *5( h16 ":" ) h16 ] "::"              h16
            / [ *6( h16 ":" ) h16 ] "::"

ls32        = ( h16 ":" h16 ) / IPv4address
            ; least-significant 32 bits of address

h16         = 1*4HEXDIG
            ; 16 bits of address represented in hexadecimal

IP Version 6 Addressing Architecture (rfc4291)

3.2.2. Host (rfc3986)

Synopsis

Declared in <include/boost/url/rfc/origin_form_rule.hpp>


constexpr
origin_form_rule_t const origin_form_rule = {};

Description

This appears in the HTTP/1 request-line grammar.


using value_type = url_view;

Rules are used with the function

grammar::parse .


system::result< url_view > rv = grammar::parse( "/index.htm?layout=mobile", origin_form_rule );


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

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

5.3.1. origin-form (rfc7230)

Synopsis

Declared in <include/boost/url/rfc/sub_delim_chars.hpp>


constexpr
grammar::lut_chars const sub_delim_chars = "!$&()*+,;=\x27";

Description

Character sets are used with rules and

the functions grammar::find_if and grammar::find_if_not .


system::result< decode_view > = grammar::parse( "Program%20Files", pct_encoded_rule( sub_delim_chars ) );


sub-delims    = "!" / "$" / "&" / "'" / "(" / ")"
              / "*" / "+" / "," / ";" / "="

2.2. Reserved Characters (rfc3986)

Synopsis

Declared in <include/boost/url/rfc/unreserved_chars.hpp>


constexpr
grammar::lut_chars const unreserved_chars = "ABCDEFGHIJKLMNOPQRSTUVWXYZ"
    "abcdefghijklmnopqrstuvwxyz"
    "0123456789"
    "-._~";

Description

Character sets are used with rules and

the functions grammar::find_if and grammar::find_if_not .


system::result< decode_view > rv = grammar::parse( "Program%20Files", pct_encoded_rule( unreserved_chars ) );


unreserved    = ALPHA / DIGIT / "-" / "." / "_" / "~"

2.3. Unreserved Characters (rfc3986)

Synopsis

Declared in <include/boost/url/rfc/pchars.hpp>


constexpr
auto const pchars = unreserved_chars + sub_delim_chars + ':' + '@';

Description

Character sets are used with rules and

the functions grammar::find_if and grammar::find_if_not .


system::result< decode_view > rv = grammar::parse( "Program%20Files", pchars );


pchar         = unreserved / pct-encoded / sub-delims / ":" / "@"

3.3. Path (rfc3986)

Synopsis

Declared in <include/boost/url/rfc/pct_encoded_rule.hpp>


template<class CharSet>
constexpr
    _implementation-defined_
pct_encoded_rule(CharSet const& cs) noexcept;

Description

This function returns a rule which matches a percent-encoded string, permitting characters in the string which are also in the specified character set to be used unescaped.


using value_type = pct_string_view;

Rules are used with the function

grammar::parse .


//  pchar         = unreserved / pct-encoded / sub-delims / ":" / "@"

system::result< pct_string_view > rv = grammar::parse( "Program%20Files", pct_encoded_rule( pchars ) );


pct-encoded   = "%" HEXDIG HEXDIG

2.1. Percent-Encoding (rfc3986)

Parameters

Name	Description
cs	The character set indicating which characters are allowed without escapes. Any character which is not in this set must be escaped, or else parsing returns an error.

Synopsis

Declared in <include/boost/url/rfc/query_rule.hpp>


constexpr
    _implementation-defined_ query_rule = {};

Description


using value_type = params_encoded_view;

Rules are used with the function

grammar::parse .


system::result< params_encoded_view > rv = grammar::parse( "format=web&id=42&compact", query_rule );


query           = *( pchar / "/" / "?" )

query-params    = [ query-param ] *( "&" query-param )
query-param     = key [ "=" value ]
key             = *qpchar
value           = *( qpchar / "=" )
qpchar          = unreserved
                / pct-encoded
                / "!" / "$" / "'" / "(" / ")"
                / "*" / "+" / "," / ";"
                / ":" / "@" / "/" / "?"

3.4. Query (rfc3986)

Synopsis

Declared in <include/boost/url/rfc/relative_ref_rule.hpp>


constexpr
    _implementation-defined_ relative_ref_rule = {};

Description


using value_type = url_view;

Rules are used with the function

grammar::parse .


system::result< url_view > rv = grammar::parse( "images/dot.gif?v=hide#a", relative_ref_rule );


relative-ref  = relative-part [ "?" query ] [ "#" fragment ]

4.2. Relative Reference (rfc3986)

Synopsis

Declared in <include/boost/url/rfc/reserved_chars.hpp>


constexpr
auto const reserved_chars = ~unreserved_chars;

Description

Character sets are used with rules and

the functions grammar::find_if and grammar::find_if_not .


system::result< decode_view > rv = grammar::parse( "Program%20Files", pct_encoded_rule( reserved_chars ) );

2.3. Unreserved Characters (rfc3986)

Synopsis

Declared in <include/boost/url/rfc/uri_rule.hpp>


constexpr
    _implementation-defined_ uri_rule = {};

Description


using value_type = url_view;

Rules are used with the function

grammar::parse .


system::result< url_view > rv = grammar::parse( "https://www.example.com/index.htm?id=guest#s1", uri_rule );


URI           = scheme ":" hier-part [ "?" query ] [ "#" fragment ]

3. Syntax Components (rfc3986)

Synopsis

Declared in <include/boost/url/rfc/uri_reference_rule.hpp>


constexpr
    _implementation-defined_ uri_reference_rule = {};

Description


using value_type = url_view;

Rules are used with the function

grammar::parse .


system::result< url_view > rv = grammar::parse( "ws://echo.example.com/?name=boost#demo", uri_reference_rule );


URI-reference = URI / relative-ref

URI           = scheme ":" hier-part [ "?" query ] [ "#" fragment ]
relative-ref  = relative-part [ "?" query ] [ "#" fragment ]

3. Syntax Components (rfc3986)

Synopsis

Declared in <include/boost/url/urls.hpp>


using urls::url;

Introduced Symbols

Name
url

Synopsis

Declared in <include/boost/url/urls.hpp>


using urls::url_view;

Introduced Symbols

Name
url_view