Reference

[#]

Global namespace

Namespaces

[#]

Namespace boost

Namespaces

Using Declarations

[#]

Namespace urls

Namespaces

Types

Types

Member Functions

Variables

Enums

[#]

Class make_void

Synopsis

            template
struct make_void;
        

Types

[#]

make_void:: type

Synopsis

            typedef void type;
        
[#]

void_t

Synopsis

            template
using void_t = make_void::type;
        
[#]

Class encoding_opts

Percent-encoding options

Synopsis

            struct encoding_opts;
        

Member Functions

Data Members

Description

These options are used to customize the behavior of algorithms which use percent escapes, such as encoding or decoding.

[#]

encoding_opts:: space_as_plus

True if spaces encode to and from plus signs

Synopsis

            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.

Specification

  • application/x-www-form-urlencoded (w3.org)
  • [#]

    encoding_opts:: lower_case

    True if hexadecimal digits are emitted as lower case

    Synopsis

                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.

    [#]

    encoding_opts:: disallow_null

    True if nulls are not allowed

    Synopsis

                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.

    [#]

    Function encoding_opts:: encoding_opts

    Synopsis

                encoding_opts(
        bool space_as_plus_ = false,
        bool lower_case_ = false,
        bool disallow_null_ = false) noexcept;
            
    [#]

    Namespace error_types

    Types

    Aliases

    Using Declarations

    [#]

    error_category

    The type of error category used by the library

    Synopsis

                using error_category = 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.

    [#]

    error_code

    The type of error code used by the library

    Synopsis

                using error_code = 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.

    [#]

    error_condition

    The type of error condition used by the library

    Synopsis

                using error_condition = 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.

    [#]

    system_error

    The type of system error thrown by the library

    Synopsis

                using system_error = 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.

    [#]

    Using Declaration: generic_category

    Synopsis

                using system::generic_category
    ;
            

    Introduced Symbols

    Name
    [#]

    Using Declaration: system_category

    Synopsis

                using system::system_category
    ;
            

    Introduced Symbols

    Name
    [#]

    errc

    Synopsis

                namespace errc = system::errc
    ;
            
    [#]

    result

    The type of result returned by library functions

    Synopsis

                template
    using result = system::result;
            

    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:

    Declaration

    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

    Usage

    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`
  • [#]

    Namespace string_token

    Types

    Member Functions

    [#]

    Class arg

    Base class for string tokens, and algorithm parameters

    Synopsis

                struct arg;
            

    Member Functions

    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.

    Example

    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.

    [#]

    Function arg:: prepare

    Return a modifiable character buffer

    Synopsis

                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.

    [#]

    Function arg:: ~arg

    Synopsis

                virtual
    ~arg() = default;
            

    Overload set arg:: arg

    Members

    constexpr
    arg() = default;
    » more...

    constexpr
    arg(arg&&) = default;
    » more...

    arg(arg const&) = delete;
    » more...

    Overload set arg:: operator=

    Members

    arg&
    operator=(arg&&) = delete;
    » more...

    arg&
    operator=(arg const&) = delete;
    » more...
    [#]

    Class is_token

    Synopsis

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

    Class is_token

    Synopsis

                template
    struct is_token().prepare(
                    std::declval())), decltype(std::declval().result())>>
        : std::integral_constant().result()), typename T::result_type>::value && std::is_same().prepare(0)), char *>::value && std::is_base_of::value && std::is_convertible::value>;
            
    [#]

    Class return_string

    Synopsis

                struct return_string
        : arg;
            

    Types

    Member Functions

    [#]

    return_string:: result_type

    Synopsis

                using result_type = std::string;
            
    [#]

    Function return_string:: prepare

    Synopsis

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

    Function return_string:: result

    Synopsis

                result_type
    result() noexcept;
            
    [#]

    Class append_to_t

    Synopsis

                template
    struct append_to_t
        : arg;
            

    Types

    Member Functions

    [#]

    append_to_t:: string_type

    Synopsis

                using string_type = std::basic_string, Alloc>;
            
    [#]

    append_to_t:: result_type

    Synopsis

                using result_type = string_type&;
            
    [#]

    Function append_to_t:: append_to_t

    Synopsis

                append_to_t(string_type& s) noexcept;
            
    [#]

    Function append_to_t:: prepare

    Synopsis

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

    Function append_to_t:: result

    Synopsis

                result_type
    result() noexcept;
            
    [#]

    Function append_to

    Synopsis

                template>
    append_to_t
    append_to(std::basic_string, Alloc>& s);
            
    [#]

    Class assign_to_t

    Synopsis

                template
    struct assign_to_t
        : arg;
            

    Types

    Member Functions

    [#]

    assign_to_t:: string_type

    Synopsis

                using string_type = std::basic_string, Alloc>;
            
    [#]

    assign_to_t:: result_type

    Synopsis

                using result_type = string_type&;
            
    [#]

    Function assign_to_t:: assign_to_t

    Synopsis

                assign_to_t(string_type& s) noexcept;
            
    [#]

    Function assign_to_t:: prepare

    Synopsis

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

    Function assign_to_t:: result

    Synopsis

                result_type
    result() noexcept;
            
    [#]

    Function assign_to

    Synopsis

                template>
    assign_to_t
    assign_to(std::basic_string, Alloc>& s);
            
    [#]

    Class preserve_size_t

    Synopsis

                template
    struct preserve_size_t
        : arg;
            

    Types

    Member Functions

    [#]

    preserve_size_t:: result_type

    Synopsis

                using result_type = core::string_view;
            
    [#]

    preserve_size_t:: string_type

    Synopsis

                using string_type = std::basic_string, Alloc>;
            
    [#]

    Function preserve_size_t:: preserve_size_t

    Synopsis

                preserve_size_t(string_type& s) noexcept;
            
    [#]

    Function preserve_size_t:: prepare

    Synopsis

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

    Function preserve_size_t:: result

    Synopsis

                result_type
    result() noexcept;
            
    [#]

    Function preserve_size

    Synopsis

                template>
    preserve_size_t
    preserve_size(std::basic_string, Alloc>& s);
            
    [#]

    Namespace grammar

    Types

    Types

    Member Functions

    Variables

    Enums

    Aliases

    [#]

    string_token

    Synopsis

                namespace string_token = string_token
    ;
            
    [#]

    Class string_view_base

    Common functionality for string views

    Synopsis

                class string_view_base;
            

    Types

    Member Functions

    Variables

    Friends

    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.

    [#]

    string_view_base:: traits_type

    The character traits

    Synopsis

                typedef std::char_traits traits_type;
            
    [#]

    string_view_base:: value_type

    The value type

    Synopsis

                typedef char value_type;
            
    [#]

    string_view_base:: pointer

    The pointer type

    Synopsis

                typedef char* pointer;
            
    [#]

    string_view_base:: const_pointer

    The const pointer type

    Synopsis

                typedef char const* const_pointer;
            
    [#]

    string_view_base:: reference

    The reference type

    Synopsis

                typedef char& reference;
            
    [#]

    string_view_base:: const_reference

    The const reference type

    Synopsis

                typedef char const& const_reference;
            
    [#]

    string_view_base:: const_iterator

    The const iterator type

    Synopsis

                typedef char const* const_iterator;
            
    [#]

    string_view_base:: iterator

    The iterator type

    Synopsis

                typedef const_iterator iterator;
            
    [#]

    string_view_base:: const_reverse_iterator

    The const reverse iterator type

    Synopsis

                typedef std::reverse_iterator const_reverse_iterator;
            
    [#]

    string_view_base:: reverse_iterator

    The reverse iterator type

    Synopsis

                typedef const_reverse_iterator reverse_iterator;
            
    [#]

    string_view_base:: size_type

    The size type

    Synopsis

                typedef std::size_t size_type;
            
    [#]

    string_view_base:: difference_type

    The difference type

    Synopsis

                typedef std::ptrdiff_t difference_type;
            
    [#]

    string_view_base:: npos

    A constant used to represent "no position"

    Synopsis

                constexpr
    static
    std::size_t const npos = core::string_view::npos;
            
    [#]

    Function string_view_base:: operator core::string_view

    Conversion

    Synopsis

                operator core::string_view() const noexcept;
            
    [#]

    Function string_view_base:: operator std::string

    Conversion

    Synopsis

                operator std::string() const noexcept;
            

    Description

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

    [#]

    Function string_view_base:: begin

    Return an iterator to the beginning

    Synopsis

                constexpr
    const_iterator
    begin() const noexcept;
            

    Description

    See `core::string_view::begin`

    [#]

    Function string_view_base:: end

    Return an iterator to the end

    Synopsis

                constexpr
    const_iterator
    end() const noexcept;
            

    Description

    See `core::string_view::end`

    [#]

    Function string_view_base:: cbegin

    Return an iterator to the beginning

    Synopsis

                constexpr
    const_iterator
    cbegin() const noexcept;
            

    Description

    See `core::string_view::cbegin`

    [#]

    Function string_view_base:: cend

    Return an iterator to the end

    Synopsis

                constexpr
    const_iterator
    cend() const noexcept;
            

    Description

    See `core::string_view::cend`

    [#]

    Function string_view_base:: rbegin

    Synopsis

                constexpr
    const_reverse_iterator
    rbegin() const noexcept;
            
    [#]

    Function string_view_base:: rend

    Synopsis

                constexpr
    const_reverse_iterator
    rend() const noexcept;
            
    [#]

    Function string_view_base:: crbegin

    Synopsis

                constexpr
    const_reverse_iterator
    crbegin() const noexcept;
            
    [#]

    Function string_view_base:: crend

    Synopsis

                constexpr
    const_reverse_iterator
    crend() const noexcept;
            
    [#]

    Function string_view_base:: size

    Return the size

    Synopsis

                constexpr
    size_type
    size() const noexcept;
            

    Description

    See `core::string_view::size`

    [#]

    Function string_view_base:: length

    Return the size

    Synopsis

                constexpr
    size_type
    length() const noexcept;
            

    Description

    See `core::string_view::length`

    [#]

    Function string_view_base:: max_size

    Return the maximum allowed size

    Synopsis

                constexpr
    size_type
    max_size() const noexcept;
            

    Description

    See `core::string_view::max_size`

    [#]

    Function string_view_base:: empty

    Return true if the string is empty

    Synopsis

                constexpr
    bool
    empty() const noexcept;
            

    Description

    See `core::string_view::size`

    [#]

    Function string_view_base:: operator[]

    Access a character

    Synopsis

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

    Description

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

    [#]

    Function string_view_base:: at

    Access a character

    Synopsis

                constexpr
    const_reference
    at(size_type pos) const;
            

    Description

    See `core::string_view::at`

    [#]

    Function string_view_base:: front

    Return the first character

    Synopsis

                constexpr
    const_reference
    front() const noexcept;
            

    Description

    See `core::string_view::front`

    [#]

    Function string_view_base:: back

    Return the last character

    Synopsis

                constexpr
    const_reference
    back() const noexcept;
            

    Description

    See `core::string_view::back`

    [#]

    Function string_view_base:: data

    Return a pointer to the character buffer

    Synopsis

                constexpr
    const_pointer
    data() const noexcept;
            

    Description

    See `core::string_view::data`

    [#]

    Function string_view_base:: copy

    Copy the characters to another buffer

    Synopsis

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

    Description

    See `core::string_view::copy`

    [#]

    Function string_view_base:: substr

    Return a view to part of the string

    Synopsis

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

    Description

    See `core::string_view::substr`

    Overload set string_view_base:: compare

    Members

    Return the result of comparing to another string

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

    Return the result of comparing to another string

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

    Return the result of comparing to another string

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

    Return the result of comparing to another string

    constexpr
    int
    compare(char const* s) const noexcept;
    » more...

    Return the result of comparing to another string

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

    Return the result of comparing to another string

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

    Overload set string_view_base:: starts_with

    Members

    Return true if a matching prefix exists

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

    Return true if a matching prefix exists

    constexpr
    bool
    starts_with(char x) const noexcept;
    » more...

    Return true if a matching prefix exists

    constexpr
    bool
    starts_with(char const* x) const noexcept;
    » more...

    Overload set string_view_base:: ends_with

    Members

    Return true if a matching suffix exists

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

    Return true if a matching suffix exists

    constexpr
    bool
    ends_with(char x) const noexcept;
    » more...

    Return true if a matching suffix exists

    constexpr
    bool
    ends_with(char const* x) const noexcept;
    » more...

    Overload set string_view_base:: find

    Members

    Return the position of matching characters

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

    Return the position of matching characters

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

    Return the position of matching characters

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

    Return the position of matching characters

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

    Overload set string_view_base:: rfind

    Members

    Return the position of matching characters

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

    Return the position of matching characters

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

    Return the position of matching characters

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

    Return the position of matching characters

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

    Overload set string_view_base:: find_first_of

    Members

    Return the position of the first match

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

    Return the position of the first match

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

    Return the position of the first match

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

    Return the position of the first match

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

    Overload set string_view_base:: find_last_of

    Members

    Return the position of the last match

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

    Return the position of the last match

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

    Return the position of the last match

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

    Return the position of the last match

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

    Overload set string_view_base:: find_first_not_of

    Members

    Return the position of the first non-match

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

    Return the position of the first non-match

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

    Return the position of the first non-match

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

    Return the position of the first non-match

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

    Overload set string_view_base:: find_last_not_of

    Members

    Return the position of the last non-match

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

    Return the position of the last non-match

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

    Return the position of the last non-match

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

    Return the position of the last non-match

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

    Overload set string_view_base:: contains

    Members

    Return true if matching characters are found

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

    Return true if matching characters are found

    constexpr
    bool
    contains(char c) const noexcept;
    » more...

    Return true if matching characters are found

    constexpr
    bool
    contains(char const* s) const noexcept;
    » more...
    [#]

    Friend operator==

    Synopsis

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

    Friend operator!=

    Synopsis

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

    Friend operator<

    Synopsis

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

    Friend operator<=

    Synopsis

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

    Friend operator>

    Synopsis

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

    Friend operator>=

    Synopsis

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

    Friend hash_value

    Return the hash of this value

    Synopsis

                friend
    std::size_t
    hash_value(string_view_base const& s) noexcept;
            
    [#]

    Friend operator<<

    Synopsis

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

    Function operator==

    Synopsis

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

    Function operator!=

    Synopsis

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

    Function operator<

    Synopsis

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

    Function operator<=

    Synopsis

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

    Function operator>

    Synopsis

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

    Function operator>=

    Synopsis

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

    Function hash_value

    Return the hash of this value

    Synopsis

                std::size_t
    hash_value(string_view_base const& s) noexcept;
            
    [#]

    Function operator<<

    Format a string to an output stream

    Synopsis

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

    Class is_rule

    Synopsis

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

    Class is_rule

    Synopsis

                template
    struct is_rule&>() =
                    std::declval().parse(
                        std::declval(),
                        std::declval()))>>
        : std::is_nothrow_copy_constructible;
            
    [#]

    Class hexdig_chars_t

    Synopsis

                struct hexdig_chars_t;
            

    Member Functions

    [#]

    Function hexdig_chars_t:: operator()

    Return true if c is in the character set.

    Synopsis

                constexpr
    bool
    operator()(char c) const noexcept;
            
    [#]

    Function hexdig_chars_t:: find_if

    Synopsis

                char const*
    find_if(
        char const* first,
        char const* last) const noexcept;
            
    [#]

    Function hexdig_chars_t:: find_if_not

    Synopsis

                char const*
    find_if_not(
        char const* first,
        char const* last) const noexcept;
            
    [#]

    hexdig_chars

    Synopsis

                constexpr
    hexdig_chars_t const hexdig_chars = {};
            
    [#]

    Function hexdig_value

    Return the decimal value of a hex character

    Synopsis

                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.

    BNF

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

    Class lut_chars

    A set of characters

    Synopsis

                class lut_chars;
            

    Member Functions

    Friends

    Description

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

    Example

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

    Overload set lut_chars:: lut_chars

    Members

    Constructor

    constexpr
    lut_chars(char ch) noexcept;
    » more...

    Constructor

    constexpr
    lut_chars(char const* s) noexcept;
    » more...

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

    Overload set lut_chars:: operator()

    Members

    Return true if ch is in the character set.

    constexpr
    bool
    operator()(unsigned char ch) const noexcept;
    » more...

    Return true if ch is in the character set.

    constexpr
    bool
    operator()(char ch) const noexcept;
    » more...
    [#]

    Friend operator+

    Return the union of two character sets.

    Synopsis

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

    Example

    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";

    Complexity

    Constant.

    [#]

    Friend operator-

    Return a new character set by subtracting

    Synopsis

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

    Example

    This statement declares a character set containing all the lowercase letters which are not vowels:

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

    Complexity

    Constant.

    [#]

    Function lut_chars:: operator~

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

    Synopsis

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

    Example

    This statement declares a character set containing everything but vowels:

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

    Complexity

    Constant.

    Exception Safety

    Throws nothing.

    [#]

    Function lut_chars:: find_if

    Synopsis

                char const*
    find_if(
        char const* first,
        char const* last) const noexcept;
            
    [#]

    Function lut_chars:: find_if_not

    Synopsis

                char const*
    find_if_not(
        char const* first,
        char const* last) const noexcept;
            
    [#]

    Function operator+

    Return the union of two character sets.

    Synopsis

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

    Example

    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";

    Complexity

    Constant.

    [#]

    Function operator-

    Return a new character set by subtracting

    Synopsis

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

    Example

    This statement declares a character set containing all the lowercase letters which are not vowels:

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

    Complexity

    Constant.

    [#]

    Class all_chars_t

    Synopsis

                struct all_chars_t;
            

    Member Functions

    [#]

    Function all_chars_t:: all_chars_t

    Synopsis

                constexpr
    all_chars_t() noexcept = default;
            
    [#]

    Function all_chars_t:: operator()

    Synopsis

                constexpr
    bool
    operator()(char) const noexcept;
            
    [#]

    Function all_chars_t:: find_if

    Synopsis

                char const*
    find_if(
        char const* first,
        char const* last) const noexcept;
            
    [#]

    Function all_chars_t:: find_if_not

    Synopsis

                char const*
    find_if_not(
        char const* first,
        char const* last) const noexcept;
            
    [#]

    all_chars

    A character set containing all characters.

    Synopsis

                constexpr
    all_chars_t const all_chars = {};
            
    [#]

    Class is_charset

    Synopsis

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

    Class is_charset

    Synopsis

                template
    struct is_charset() =
                    std::declval().operator()(
                        std::declval()))>>
        : std::true_type;
            
    [#]

    Function find_if

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

    Synopsis

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

    Description

    Exception Safety

    Throws nothing.

    [#]

    Function find_if_not

    Find the first character in the string that is not in CharSet

    Synopsis

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

    Description

    Exception Safety

    Throws nothing.

    Overload set ref

    Members

    template
    constexpr
    detail::charset_ref
    ref(CharSet const& cs) noexcept;
    » more...

    template
    constexpr
    detail::rule_ref
    ref(Rule const& r) noexcept;
    » more...

    constexpr
    void
    ref() = delete;
    » more...

    Overload set parse

    Members

    Parse a character buffer using a rule

    template
    system::result
    parse(
        char const*& it,
        char const* end,
        Rule const& r);
    » more...

    Parse a character buffer using a rule

    template
    system::result
    parse(
        core::string_view s,
        Rule const& r);
    » more...
    [#]

    Enum error

    Error codes returned when using rules

    Synopsis

                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.

    [#]

    Enumerator error:: need_more

    More input is needed to match the rule

    Synopsis

                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.

    [#]

    Enumerator error:: mismatch

    The rule did not match the input.

    Synopsis

                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.

    [#]

    Enumerator error:: end_of_range

    A rule reached the end of a range

    Synopsis

                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.

    [#]

    Enumerator error:: leftover

    Leftover input remaining after match.

    Synopsis

                leftover        
    [#]

    Enumerator error:: invalid

    A rule encountered unrecoverable invalid input.

    Synopsis

                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.

    [#]

    Enumerator error:: out_of_range

    An integer overflowed during parsing.

    Synopsis

                out_of_range        
    [#]

    Enumerator error:: syntax

    An unspecified syntax error was found.

    Synopsis

                syntax        
    [#]

    Enum condition

    Error conditions for errors received from rules

    Synopsis

                enum condition : int;
            

    Members

    Name Description
    fatal

    A fatal error in syntax was encountered.

    [#]

    Enumerator condition:: fatal

    A fatal error in syntax was encountered.

    Synopsis

                fatal = 1        

    Description

    This indicates that parsing cannot continue.

    [#]

    Function make_error_code

    Synopsis

                system::error_code
    make_error_code(error ev) noexcept;
            
    [#]

    Function make_error_condition

    Synopsis

                system::error_condition
    make_error_condition(condition c) noexcept;
            
    [#]

    Function to_lower

    Return c converted to lowercase

    Synopsis

                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.

    Example

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

    Exception Safety

    Throws nothing.

    [#]

    Function to_upper

    Return c converted to uppercase

    Synopsis

                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.

    Example

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

    Exception Safety

    Throws nothing.

    [#]

    Function ci_compare

    Return the case-insensitive comparison of s0 and s1

    Synopsis

                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.

    Example

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

    Exception Safety

    Throws nothing.

    [#]

    Function ci_digest

    Return the case-insensitive digest of a string

    Synopsis

                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.

    Overload set ci_is_equal

    Members

    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...
    [#]

    Function ci_is_less

    Return true if s0 is less than s1 using case-insensitive comparison

    Synopsis

                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.

    Example

    assert( ! ci_is_less( "Boost", "boost" ) );
    [#]

    Class ci_hash

    Synopsis

                struct ci_hash;
            

    Types

    Member Functions

    [#]

    ci_hash:: is_transparent

    Synopsis

                using is_transparent = void;
            
    [#]

    Function ci_hash:: operator()

    Synopsis

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

    Class ci_equal

    Synopsis

                struct ci_equal;
            

    Types

    Member Functions

    [#]

    ci_equal:: is_transparent

    Synopsis

                using is_transparent = void;
            
    [#]

    Function ci_equal:: operator()

    Synopsis

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

    Class ci_less

    Synopsis

                struct ci_less;
            

    Types

    Member Functions

    [#]

    ci_less:: is_transparent

    Synopsis

                using is_transparent = void;
            
    [#]

    Function ci_less:: operator()

    Synopsis

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

    Class variant_rule_t

    Synopsis

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

    Types

    Member Functions

    Friends

    [#]

    variant_rule_t:: value_type

    Synopsis

                using value_type = variant;
            
    [#]

    Function variant_rule_t:: parse

    Synopsis

                system::result
    parse(
        char const*& it,
        char const* end) const;
            
    [#]

    Friend variant_rule

    Synopsis

                template<
        class R0_,
        class... Rn_>
    friend
    constexpr
    variant_rule_t
    variant_rule(
        R0_ const& r0,
        Rn_ const&... rn) noexcept;
            

    Overload set variant_rule

    Members

    template<
        class R0_,
        class... Rn_>
    constexpr
    variant_rule_t
    variant_rule(
        R0_ const& r0,
        Rn_ const&... rn) noexcept;
    » more...

    template<
        class R0,
        class... Rn>
    constexpr
    variant_rule_t
    variant_rule(
        R0 const& r0,
        Rn const&... rn) noexcept;
    » more...
    [#]

    Class unsigned_rule

    Synopsis

                template
    struct unsigned_rule;
            

    Types

    Member Functions

    [#]

    unsigned_rule:: value_type

    Synopsis

                using value_type = Unsigned;
            
    [#]

    Function unsigned_rule:: parse

    Synopsis

                system::result
    parse(
        char const*& it,
        char const* end) const noexcept;
            
    [#]

    Class digit_chars_t

    Synopsis

                struct digit_chars_t;
            

    Member Functions

    [#]

    Function digit_chars_t:: operator()

    Synopsis

                constexpr
    bool
    operator()(char c) const noexcept;
            
    [#]

    Function digit_chars_t:: find_if

    Synopsis

                char const*
    find_if(
        char const* first,
        char const* last) const noexcept;
            
    [#]

    Function digit_chars_t:: find_if_not

    Synopsis

                char const*
    find_if_not(
        char const* first,
        char const* last) const noexcept;
            
    [#]

    digit_chars

    Synopsis

                constexpr
    digit_chars_t const digit_chars = {};
            
    [#]

    Class ch_delim_rule

    Synopsis

                struct ch_delim_rule;
            

    Types

    Member Functions

    [#]

    ch_delim_rule:: value_type

    Synopsis

                using value_type = core::string_view;
            
    [#]

    Function ch_delim_rule:: ch_delim_rule

    Synopsis

                constexpr
    ch_delim_rule(char ch) noexcept;
            
    [#]

    Function ch_delim_rule:: parse

    Synopsis

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

    Overload set delim_rule

    Members

    constexpr
    ch_delim_rule
    delim_rule(char ch) noexcept;
    » more...

    template
    constexpr
    cs_delim_rule
    delim_rule(CharSet const& cs) noexcept;
    » more...
    [#]

    Class cs_delim_rule

    Synopsis

                template
    struct cs_delim_rule;
            

    Types

    Member Functions

    [#]

    cs_delim_rule:: value_type

    Synopsis

                using value_type = core::string_view;
            
    [#]

    Function cs_delim_rule:: cs_delim_rule

    Synopsis

                constexpr
    cs_delim_rule(CharSet const& cs) noexcept;
            
    [#]

    Function cs_delim_rule:: parse

    Synopsis

                system::result
    parse(
        char const*& it,
        char const* end) const noexcept;
            
    [#]

    Class optional_rule_t

    Synopsis

                template
    struct optional_rule_t;
            

    Types

    Member Functions

    Friends

    [#]

    optional_rule_t:: value_type

    Synopsis

                using value_type = optional;
            
    [#]

    Function optional_rule_t:: parse

    Synopsis

                system::result
    parse(
        char const*& it,
        char const* end) const;
            
    [#]

    Friend optional_rule

    Synopsis

                template
    friend
    constexpr
    optional_rule_t
    optional_rule(R_ const& r);
            

    Overload set optional_rule

    Members

    template
    constexpr
    optional_rule_t
    optional_rule(R_ const& r);
    » more...

    template
    constexpr
    optional_rule_t
    optional_rule(Rule const& r);
    » more...
    [#]

    Class tuple_rule_t

    Synopsis

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

    Types

    Member Functions

    Friends

    [#]

    tuple_rule_t:: value_type

    Synopsis

                using value_type = mp11::mp_eval_if_c;
            
    [#]

    Friend tuple_rule

    Synopsis

                template<
        class R0_,
        class... Rn_>
    friend
    constexpr
    tuple_rule_t
    tuple_rule(
        R0_ const& r0,
        Rn_ const&... rn) noexcept;
            
    [#]

    Function tuple_rule_t:: parse

    Synopsis

                system::result
    parse(
        char const*& it,
        char const* end) const;
            

    Overload set tuple_rule

    Members

    template<
        class R0_,
        class... Rn_>
    constexpr
    tuple_rule_t
    tuple_rule(
        R0_ const& r0,
        Rn_ const&... rn) noexcept;
    » more...

    template<
        class R0,
        class... Rn>
    constexpr
    tuple_rule_t
    tuple_rule(
        R0 const& r0,
        Rn const&... rn) noexcept;
    » more...
    [#]

    Function squelch

    Synopsis

                template
    constexpr
    detail::squelch_rule_t
    squelch(Rule const& r) noexcept;
            
    [#]

    aligned_storage

    Synopsis

                template
    using aligned_storage = detail::aligned_storage_impl alignof(T)) ? alignof(::max_align_t) : alignof(T)>;
            
    [#]

    Class recycled

    A thread-safe collection of instances of T

    Synopsis

                template
    class recycled;
            

    Member Functions

    Description

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

    Example

    static recycled< std::string > bin; recycled_ptr< std::string > ps( bin ); // Put the string into a known state ps->clear();
    [#]

    Function recycled:: ~recycled

    Destructor

    Synopsis

                ~recycled();
            

    Description

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

    [#]

    Function recycled:: recycled

    Constructor

    Synopsis

                constexpr
    recycled() = default;
            
    [#]

    Class recycled_ptr

    A pointer to shared instance of T

    Synopsis

                template
    class recycled_ptr;
            

    Member Functions

    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.

    Example

    static recycled< std::string > bin; recycled_ptr< std::string > ps( bin ); // Put the string into a known state ps->clear();
    [#]

    Function recycled_ptr:: ~recycled_ptr

    Destructor

    Synopsis

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

    Effects

    this->release();

    Overload set recycled_ptr:: recycled_ptr

    Members

    Constructor

    recycled_ptr(recycled& bin);
    » more...

    Constructor

    recycled_ptr(
        recycled& bin,
        std::nullptr_t) noexcept;
    » more...

    Constructor

    recycled_ptr();
    » more...

    Constructor

    recycled_ptr(std::nullptr_t) noexcept;
    » more...

    Constructor

    recycled_ptr(recycled_ptr const& other) noexcept;
    » more...

    Constructor

    recycled_ptr(recycled_ptr&& other) noexcept;
    » more...

    Overload set recycled_ptr:: operator=

    Members

    Assignment

    recycled_ptr&
    operator=(recycled_ptr&& other) noexcept;
    » more...

    Assignment

    recycled_ptr&
    operator=(recycled_ptr const& other) noexcept;
    » more...
    [#]

    Function recycled_ptr:: empty

    Return true if this does not reference an object

    Synopsis

                bool
    empty() const noexcept;
            

    Description

    Exception Safety

    Throws nothing.

    [#]

    Function recycled_ptr:: operator bool

    Return true if this references an object

    Synopsis

                operator bool() const noexcept;
            

    Description

    Effects

    return ! this->empty();

    Exception Safety

    Throws nothing.

    [#]

    Function recycled_ptr:: bin

    Return the referenced recycle bin

    Synopsis

                recycled&
    bin() const noexcept;
            

    Description

    Exception Safety

    Throws nothing.

    [#]

    Function recycled_ptr:: get

    Return the referenced object

    Synopsis

                T*
    get() const noexcept;
            

    Description

    If this is empty, `nullptr` is returned.

    Exception Safety

    Throws nothing.

    [#]

    Function recycled_ptr:: operator->

    Return the referenced object

    Synopsis

                T*
    operator->() const noexcept;
            

    Description

    If this is empty, `nullptr` is returned.

    Exception Safety

    Throws nothing.

    [#]

    Function recycled_ptr:: operator*

    Return the referenced object

    Synopsis

                T&
    operator*() const noexcept;
            

    Description

    Preconditions

    not this->empty()
    [#]

    Function recycled_ptr:: acquire

    Return the referenced object

    Synopsis

                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.

    Postconditions

    not this->empty()
    [#]

    Function recycled_ptr:: release

    Release the referenced object

    Synopsis

                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.

    Postconditions

    this->empty()

    Exception Safety

    Throws nothing.

    [#]

    Class alpha_chars_t

    Synopsis

                struct alpha_chars_t;
            

    Member Functions

    [#]

    Function alpha_chars_t:: alpha_chars_t

    Synopsis

                constexpr
    alpha_chars_t() noexcept = default;
            
    [#]

    Function alpha_chars_t:: operator()

    Synopsis

                constexpr
    bool
    operator()(char c) const noexcept;
            
    [#]

    Function alpha_chars_t:: find_if

    Synopsis

                char const*
    find_if(
        char const* first,
        char const* last) const noexcept;
            
    [#]

    Function alpha_chars_t:: find_if_not

    Synopsis

                char const*
    find_if_not(
        char const* first,
        char const* last) const noexcept;
            
    [#]

    alpha_chars

    A character set containing the alphabetical characters.

    Synopsis

                constexpr
    alpha_chars_t const alpha_chars = {};
            
    [#]

    Class token_rule_t

    Synopsis

                template
    struct token_rule_t;
            

    Types

    Member Functions

    [#]

    token_rule_t:: value_type

    Synopsis

                using value_type = core::string_view;
            
    [#]

    Function token_rule_t:: parse

    Synopsis

                system::result
    parse(
        char const*& it,
        char const* end) const noexcept;
            
    [#]

    Function token_rule

    Synopsis

                template
    constexpr
    token_rule_t
    token_rule(CharSet const& cs) noexcept;
            
    [#]

    Class range

    A forward range of parsed elements

    Synopsis

                template
    class range;
            

    Types

    Types

    Member Functions

    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.

    [#]

    range:: value_type

    The type of each element of the range

    Synopsis

                using value_type = T;
            
    [#]

    range:: reference

    The type of each element of the range

    Synopsis

                using reference = T const&;
            
    [#]

    range:: const_reference

    The type of each element of the range

    Synopsis

                using const_reference = T const&;
            
    [#]

    range:: pointer

    Provided for compatibility, unused

    Synopsis

                using pointer = void const*;
            
    [#]

    range:: size_type

    The type used to represent unsigned integers

    Synopsis

                using size_type = std::size_t;
            
    [#]

    range:: difference_type

    The type used to represent signed integers

    Synopsis

                using difference_type = std::ptrdiff_t;
            
    [#]

    Class range:: iterator

    A constant, forward iterator to elements of the range

    Synopsis

                class iterator;
            

    Types

    Member Functions

    [#]

    range:: iterator:: value_type

    Synopsis

                using value_type = T;
            
    [#]

    range:: iterator:: reference

    Synopsis

                using reference = T const&;
            
    [#]

    range:: iterator:: pointer

    Synopsis

                using pointer = void const*;
            
    [#]

    range:: iterator:: difference_type

    Synopsis

                using difference_type = std::ptrdiff_t;
            
    [#]

    range:: iterator:: iterator_category

    Synopsis

                using iterator_category = std::forward_iterator_tag;
            

    Overload set range:: iterator:: iterator

    Members

    iterator() = default;
    » more...

    iterator(iterator const&) = default;
    » more...
    [#]

    Function range:: iterator:: operator=

    Synopsis

                iterator&
    operator=(iterator const&) = default;
            
    [#]

    Function range:: iterator:: operator*

    Synopsis

                reference
    operator*() const noexcept;
            
    [#]

    Function range:: iterator:: operator==

    Synopsis

                bool
    operator==(iterator const& other) const noexcept;
            
    [#]

    Function range:: iterator:: operator!=

    Synopsis

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

    Overload set range:: iterator:: operator++

    Members

    iterator&
    operator++() noexcept;
    » more...

    iterator
    operator++(int) noexcept;
    » more...
    [#]

    range:: const_iterator

    A constant, forward iterator to elements of the range

    Synopsis

                using const_iterator = iterator;
            
    [#]

    Function range:: ~range

    Destructor

    Synopsis

                ~range();
            

    Overload set range:: range

    Members

    Constructor

    range() noexcept;
    » more...

    Constructor

    range(range&& other) noexcept;
    » more...

    Constructor

    range(range const& other) noexcept;
    » more...

    Overload set range:: operator=

    Members

    Assignment

    range&
    operator=(range&& other) noexcept;
    » more...

    Assignment

    range&
    operator=(range const& other) noexcept;
    » more...
    [#]

    Function range:: begin

    Return an iterator to the beginning

    Synopsis

                iterator
    begin() const noexcept;
            
    [#]

    Function range:: end

    Return an iterator to the end

    Synopsis

                iterator
    end() const noexcept;
            
    [#]

    Function range:: empty

    Return true if the range is empty

    Synopsis

                bool
    empty() const noexcept;
            
    [#]

    Function range:: size

    Return the number of elements in the range

    Synopsis

                std::size_t
    size() const noexcept;
            
    [#]

    Function range:: string

    Return the matching part of the string

    Synopsis

                core::string_view
    string() const noexcept;
            
    [#]

    Class range_rule_t

    Synopsis

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

    Types

    Member Functions

    [#]

    range_rule_t:: value_type

    Synopsis

                using value_type = range;
            
    [#]

    Function range_rule_t:: parse

    Synopsis

                system::result
    parse(
        char const*& it,
        char const* end) const;
            
    [#]

    Class range_rule_t

    Synopsis

                template
    struct range_rule_t;
            

    Types

    Member Functions

    [#]

    range_rule_t:: value_type

    Synopsis

                using value_type = range;
            
    [#]

    Function range_rule_t:: parse

    Synopsis

                system::result
    parse(
        char const*& it,
        char const* end) const;
            

    Overload set range_rule

    Members

    template
    constexpr
    range_rule_t
    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
    range_rule_t
    range_rule(
        Rule1 const& first,
        Rule2 const& next,
        std::size_t N = 0,
        std::size_t M = std::size_t(-1)) noexcept;
    » more...
    [#]

    Class alnum_chars_t

    Synopsis

                struct alnum_chars_t;
            

    Member Functions

    [#]

    Function alnum_chars_t:: operator()

    Synopsis

                constexpr
    bool
    operator()(char c) const noexcept;
            
    [#]

    Function alnum_chars_t:: find_if

    Synopsis

                char const*
    find_if(
        char const* first,
        char const* last) const noexcept;
            
    [#]

    Function alnum_chars_t:: find_if_not

    Synopsis

                char const*
    find_if_not(
        char const* first,
        char const* last) const noexcept;
            
    [#]

    alnum_chars

    Synopsis

                constexpr
    alnum_chars_t const alnum_chars = {};
            
    [#]

    Class vchars_t

    Synopsis

                struct vchars_t;
            

    Member Functions

    [#]

    Function vchars_t:: operator()

    Synopsis

                constexpr
    bool
    operator()(char c) const noexcept;
            
    [#]

    Function vchars_t:: find_if

    Synopsis

                char const*
    find_if(
        char const* first,
        char const* last) const noexcept;
            
    [#]

    Function vchars_t:: find_if_not

    Synopsis

                char const*
    find_if_not(
        char const* first,
        char const* last) const noexcept;
            
    [#]

    vchars

    Synopsis

                constexpr
    vchars_t const vchars = {};
            
    [#]

    Class dec_octet_rule_t

    Synopsis

                struct dec_octet_rule_t;
            

    Types

    Member Functions

    [#]

    dec_octet_rule_t:: value_type

    Synopsis

                using value_type = unsigned char;
            
    [#]

    Function dec_octet_rule_t:: parse

    Synopsis

                system::result
    parse(
        char const*& it,
        char const* end) const noexcept;
            
    [#]

    dec_octet_rule

    Synopsis

                constexpr
    dec_octet_rule_t const dec_octet_rule = {};
            
    [#]

    Class literal_rule

    Synopsis

                class literal_rule;
            

    Types

    Member Functions

    [#]

    literal_rule:: value_type

    Synopsis

                using value_type = core::string_view;
            
    [#]

    Function literal_rule:: literal_rule

    Synopsis

                constexpr
    literal_rule(char const* s) noexcept;
            
    [#]

    Function literal_rule:: parse

    Synopsis

                system::result
    parse(
        char const*& it,
        char const* end) const noexcept;
            
    [#]

    Class not_empty_rule_t

    Synopsis

                template
    struct not_empty_rule_t;
            

    Types

    Member Functions

    Friends

    [#]

    not_empty_rule_t:: value_type

    Synopsis

                using value_type = R::value_type;
            
    [#]

    Function not_empty_rule_t:: parse

    Synopsis

                system::result
    parse(
        char const*& it,
        char const* end) const;
            
    [#]

    Friend not_empty_rule

    Synopsis

                template
    friend
    constexpr
    not_empty_rule_t
    not_empty_rule(R_ const& r);
            

    Overload set not_empty_rule

    Members

    template
    constexpr
    not_empty_rule_t
    not_empty_rule(R_ const& r);
    » more...

    template
    constexpr
    not_empty_rule_t
    not_empty_rule(Rule const& r);
    » more...
    [#]

    Class decode_view

    A reference to a valid, percent-encoded string

    Synopsis

                class decode_view;
            

    Types

    Types

    Member Functions

    Friends

    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.

    Operators

    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;
    [#]

    decode_view:: value_type

    The value type

    Synopsis

                using value_type = char;
            
    [#]

    decode_view:: reference

    The reference type

    Synopsis

                using reference = char;
            
    [#]

    decode_view:: const_reference

    The reference type

    Synopsis

                using const_reference = char;
            
    [#]

    decode_view:: size_type

    The unsigned integer type

    Synopsis

                using size_type = std::size_t;
            
    [#]

    decode_view:: difference_type

    The signed integer type

    Synopsis

                using difference_type = std::ptrdiff_t;
            
    [#]

    Class decode_view:: iterator

    Synopsis

                class iterator;
            

    Types

    Member Functions

    [#]

    decode_view:: iterator:: value_type

    Synopsis

                using value_type = char;
            
    [#]

    decode_view:: iterator:: reference

    Synopsis

                using reference = char;
            
    [#]

    decode_view:: iterator:: pointer

    Synopsis

                using pointer = void const*;
            
    [#]

    decode_view:: iterator:: const_reference

    Synopsis

                using const_reference = char;
            
    [#]

    decode_view:: iterator:: size_type

    Synopsis

                using size_type = std::size_t;
            
    [#]

    decode_view:: iterator:: difference_type

    Synopsis

                using difference_type = std::ptrdiff_t;
            
    [#]

    decode_view:: iterator:: iterator_category

    Synopsis

                using iterator_category = std::bidirectional_iterator_tag;
            

    Overload set decode_view:: iterator:: iterator

    Members

    constexpr
    iterator() = default;
    » more...

    constexpr
    iterator(iterator const&) = default;
    » more...
    [#]

    Function decode_view:: iterator:: operator=

    Synopsis

                constexpr
    iterator&
    operator=(iterator const&) = default;
            
    [#]

    Function decode_view:: iterator:: operator*

    Synopsis

                reference
    operator*() const noexcept;
            

    Overload set decode_view:: iterator:: operator++

    Members

    iterator&
    operator++() noexcept;
    » more...

    iterator
    operator++(int) noexcept;
    » more...

    Overload set decode_view:: iterator:: operator--

    Members

    iterator&
    operator--() noexcept;
    » more...

    iterator
    operator--(int) noexcept;
    » more...
    [#]

    Function decode_view:: iterator:: base

    Synopsis

                char const*
    base();
            
    [#]

    Function decode_view:: iterator:: operator==

    Synopsis

                bool
    operator==(iterator const& other) const noexcept;
            
    [#]

    Function decode_view:: iterator:: operator!=

    Synopsis

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

    decode_view:: const_iterator

    iterator

    Synopsis

                using const_iterator = iterator;
            

    Overload set decode_view:: decode_view

    Members

    Constructor

    constexpr
    decode_view() noexcept = default;
    » more...

    Constructor

    decode_view(
        pct_string_view s,
        encoding_opts opt = = {}) noexcept;
    » more...
    [#]

    Function decode_view:: empty

    Return true if the string is empty

    Synopsis

                bool
    empty() const noexcept;
            

    Description

    Example

    assert( decode_view( "" ).empty() );

    Complexity

    Constant.

    Exception Safety

    Throws nothing.

    [#]

    Function decode_view:: size

    Return the number of decoded characters

    Synopsis

                size_type
    size() const noexcept;
            

    Description

    Example

    assert( decode_view( "Program%20Files" ).size() == 13 );

    Effects

    return std::distance( this->begin(), this->end() );

    Complexity

    Constant.

    Exception Safety

    Throws nothing.

    [#]

    Function decode_view:: begin

    Return an iterator to the beginning

    Synopsis

                iterator
    begin() const noexcept;
            

    Description

    Example

    auto it = this->begin();

    Complexity

    Constant.

    Exception Safety

    Throws nothing.

    [#]

    Function decode_view:: end

    Return an iterator to the end

    Synopsis

                iterator
    end() const noexcept;
            

    Description

    Example

    auto it = this->end();

    Complexity

    Constant.

    Exception Safety

    Throws nothing.

    [#]

    Function decode_view:: front

    Return the first character

    Synopsis

                reference
    front() const noexcept;
            

    Description

    Example

    assert( decode_view( "Program%20Files" ).front() == 'P' );

    Preconditions

    not this->empty()

    Complexity

    Constant.

    Exception Safety

    Throws nothing.

    [#]

    Function decode_view:: back

    Return the last character

    Synopsis

                reference
    back() const noexcept;
            

    Description

    Example

    assert( decode_view( "Program%20Files" ).back() == 's' );

    Preconditions

    not this->empty()

    Complexity

    Constant.

    Exception Safety

    Throws nothing.

    Overload set decode_view:: starts_with

    Members

    Checks if the string begins with the given prefix

    bool
    starts_with(core::string_view s) const noexcept;
    » more...

    Checks if the string begins with the given prefix

    bool
    starts_with(char ch) const noexcept;
    » more...

    Overload set decode_view:: ends_with

    Members

    Checks if the string ends with the given prefix

    bool
    ends_with(core::string_view s) const noexcept;
    » more...

    Checks if the string ends with the given prefix

    bool
    ends_with(char ch) const noexcept;
    » more...
    [#]

    Function decode_view:: find

    Finds the first occurrence of character in this view

    Synopsis

                const_iterator
    find(char ch) const noexcept;
            

    Description

    Complexity

    Linear.

    Exception Safety

    Throws nothing.

    [#]

    Function decode_view:: rfind

    Finds the first occurrence of character in this view

    Synopsis

                const_iterator
    rfind(char ch) const noexcept;
            

    Description

    Complexity

    Linear.

    Exception Safety

    Throws nothing.

    [#]

    Function decode_view:: remove_prefix

    Remove the first characters

    Synopsis

                void
    remove_prefix(size_type n);
            

    Description

    Example

    decode_view d( "Program%20Files" ); d.remove_prefix( 8 ); assert( d == "Files" );

    Preconditions

    not this->empty()

    Complexity

    Linear.

    [#]

    Function decode_view:: remove_suffix

    Remove the last characters

    Synopsis

                void
    remove_suffix(size_type n);
            

    Description

    Example

    decode_view d( "Program%20Files" ); d.remove_prefix( 6 ); assert( d == "Program" );

    Preconditions

    not this->empty()

    Complexity

    Linear.

    [#]

    Function decode_view:: options

    Return the decoding options

    Synopsis

                encoding_opts
    options() const noexcept;
            

    Overload set decode_view:: compare

    Members

    Return the result of comparing to another string

    int
    compare(core::string_view other) const noexcept;
    » more...

    Return the result of comparing to another string

    int
    compare(decode_view other) const noexcept;
    » more...
    [#]

    Friend operator==

    Synopsis

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

    Friend operator!=

    Synopsis

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

    Friend operator<

    Synopsis

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

    Friend operator<=

    Synopsis

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

    Friend operator>

    Synopsis

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

    Friend operator>=

    Synopsis

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

    Friend operator<<

    Synopsis

                friend
    std::ostream&
    operator<<(
        std::ostream& os,
        decode_view const& s);
            
    [#]

    Class pct_string_view

    A reference to a valid percent-encoded string

    Synopsis

                class pct_string_view
        : public grammar::string_view_base;
            

    Types

    Member Functions

    Variables

    Friends

    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.

    Operators

    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;

    Overload set pct_string_view:: pct_string_view

    Members

    Constructor

    constexpr
    pct_string_view() = default;
    » more...

    Constructor

    constexpr
    pct_string_view(pct_string_view const& other) = default;
    » more...

    template<
        class String,
        class = void>
    pct_string_view(String const& s);
    » more...

    Constructor (deleted)

    pct_string_view(std::nullptr_t) = delete;
    » more...

    Constructor

    pct_string_view(
        char const* s,
        std::size_t len);
    » more...

    Constructor

    pct_string_view(core::string_view s);
    » more...
    [#]

    Function pct_string_view:: operator=

    Assignment

    Synopsis

                constexpr
    pct_string_view&
    operator=(pct_string_view const& other) = default;
            

    Description

    The copy references the same underlying character buffer. Ownership is not transferred.

    Postconditions

    this->data() == other.data()

    Complexity

    Constant.

    Exception Safety

    Throws nothing.

    other The string to copy.

    [#]

    Friend make_pct_string_view

    Synopsis

                friend
    system::result
    make_pct_string_view(core::string_view s) noexcept;
            
    [#]

    Function pct_string_view:: decoded_size

    Return the decoded size

    Synopsis

                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.

    Complexity

    Constant.

    Exception Safety

    Throws nothing.

    [#]

    Function pct_string_view:: operator*

    Return the string as a range of decoded characters

    Synopsis

                decode_view
    operator*() const noexcept;
            

    Description

    Complexity

    Constant.

    Exception Safety

    Throws nothing.

    [#]

    Function pct_string_view:: decode

    Return the string with percent-decoding

    Synopsis

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

    Example

    assert( pct_string_view( "Program%20Files" ).decode() == "Program Files" );

    Complexity

    Linear in `this->size()`.

    Exception Safety

    Calls to allocate may throw. String tokens may throw exceptions.

    [#]

    Function pct_string_view:: operator->

    Synopsis

                pct_string_view const*
    operator->() const noexcept;
            
    [#]

    Function pct_string_view:: swap

    Swap

    Synopsis

                void
    swap(pct_string_view& s) noexcept;
            
    [#]

    Function make_pct_string_view_unsafe

    Synopsis

                pct_string_view
    make_pct_string_view_unsafe(
        char const* data,
        std::size_t size,
        std::size_t decoded_size) noexcept;
            
    [#]

    Function make_pct_string_view

    Return a valid percent-encoded string

    Synopsis

                system::result
    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.

    Complexity

    Linear in `s.size()`.

    Exception Safety

    Throws nothing.

    Overload set operator==

    Members

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

    Return true if two addresses are equal

    bool
    operator==(
        ipv4_address const& a1,
        ipv4_address const& a2) noexcept;
    » more...

    Return true if two addresses are equal

    bool
    operator==(
        ipv6_address const& a1,
        ipv6_address const& a2) noexcept;
    » more...

    Return the result of comparing two authorities The authorities are compared component by component as if they were first normalized.

    bool
    operator==(
        authority_view const& a0,
        authority_view const& a1) noexcept;
    » more...

    bool
    operator==(
        iterator const& it0,
        iterator const& it1) noexcept;
    » more...

    Return the result of comparing two URLs

    bool
    operator==(
        url_view_base const& u0,
        url_view_base const& u1) noexcept;
    » more...

    Overload set operator!=

    Members

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

    Return true if two addresses are not equal

    bool
    operator!=(
        ipv4_address const& a1,
        ipv4_address const& a2) noexcept;
    » more...

    Return true if two addresses are not equal

    bool
    operator!=(
        ipv6_address const& a1,
        ipv6_address const& a2) noexcept;
    » more...

    Return the result of comparing two authorities The authorities are compared component by component as if they were first normalized.

    bool
    operator!=(
        authority_view const& a0,
        authority_view const& a1) noexcept;
    » more...

    bool
    operator!=(
        iterator const& it0,
        iterator const& it1) noexcept;
    » more...

    Return the result of comparing two URLs

    bool
    operator!=(
        url_view_base const& u0,
        url_view_base const& u1) noexcept;
    » more...

    Overload set operator<

    Members

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

    Return the result of comparing two authorities The authorities are compared component by component as if they were first normalized.

    bool
    operator<(
        authority_view const& a0,
        authority_view const& a1) noexcept;
    » more...

    Return the result of comparing two URLs

    bool
    operator<(
        url_view_base const& u0,
        url_view_base const& u1) noexcept;
    » more...

    Overload set operator<=

    Members

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

    Return the result of comparing two authorities The authorities are compared component by component as if they were first normalized.

    bool
    operator<=(
        authority_view const& a0,
        authority_view const& a1) noexcept;
    » more...

    Return the result of comparing two URLs

    bool
    operator<=(
        url_view_base const& u0,
        url_view_base const& u1) noexcept;
    » more...

    Overload set operator>

    Members

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

    Return the result of comparing two authorities The authorities are compared component by component as if they were first normalized.

    bool
    operator>(
        authority_view const& a0,
        authority_view const& a1) noexcept;
    » more...

    Return the result of comparing two URLs

    bool
    operator>(
        url_view_base const& u0,
        url_view_base const& u1) noexcept;
    » more...

    Overload set operator>=

    Members

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

    Return the result of comparing two authorities The authorities are compared component by component as if they were first normalized.

    bool
    operator>=(
        authority_view const& a0,
        authority_view const& a1) noexcept;
    » more...

    Return the result of comparing two URLs

    bool
    operator>=(
        url_view_base const& u0,
        url_view_base const& u1) noexcept;
    » more...

    Overload set operator<<

    Members

    Format the string with percent-decoding applied to the output stream

    std::ostream&
    operator<<(
        std::ostream& os,
        decode_view const& s);
    » more...

    Format the address to an output stream.

    std::ostream&
    operator<<(
        std::ostream& os,
        ipv4_address const& addr);
    » more...

    Format the address to an output stream

    std::ostream&
    operator<<(
        std::ostream& os,
        ipv6_address const& addr);
    » more...

    Format the encoded authority to the output stream

    std::ostream&
    operator<<(
        std::ostream& os,
        authority_view const& a);
    » more...

    Format to an output stream

    std::ostream&
    operator<<(
        std::ostream& os,
        segments_encoded_base const& ps);
    » more...

    Format to an output stream

    std::ostream&
    operator<<(
        std::ostream& os,
        segments_base const& ps);
    » more...

    Format to an output stream

    std::ostream&
    operator<<(
        std::ostream& os,
        params_encoded_base const& qp);
    » more...

    Format to an output stream

    std::ostream&
    operator<<(
        std::ostream& os,
        params_base const& qp);
    » more...

    Format the url to the output stream

    std::ostream&
    operator<<(
        std::ostream& os,
        url_view_base const& u);
    » more...
    [#]

    sub_delim_chars

    The sub-delims character set

    Synopsis

                constexpr
    grammar::lut_chars const sub_delim_chars = "!$&()*+,;=\x27";
            

    Description

    Example

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

    BNF

    sub-delims = "!" / "$" / "&" / "'" / "(" / ")" / "*" / "+" / "," / ";" / "="

    Specification

  • 2.2. Reserved Characters (rfc3986)
  • [#]

    unreserved_chars

    The unreserved character set

    Synopsis

                constexpr
    grammar::lut_chars const unreserved_chars = "ABCDEFGHIJKLMNOPQRSTUVWXYZ"
        "abcdefghijklmnopqrstuvwxyz"
        "0123456789"
        "-._~";
            

    Description

    Example

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

    BNF

    unreserved = ALPHA / DIGIT / "-" / "." / "_" / "~"

    Specification

  • 2.3. Unreserved Characters (rfc3986)
  • [#]

    pchars

    The path character set

    Synopsis

                constexpr
    lut_chars const pchars = unreserved_chars + sub_delim_chars + ':' + '@';
            

    Description

    Example

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

    BNF

    pchar = unreserved / pct-encoded / sub-delims / ":" / "@"

    Specification

  • 3.3. Path (rfc3986)
  • [#]

    Function encoded_size

    Return the buffer size needed for percent-encoding

    Synopsis

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

    Example

    assert( encoded_size( "My Stuff", pchars ) == 10 );

    Exception Safety

    Throws nothing.

    Specification

  • 2.1. Percent-Encoding (rfc3986)
  • Overload set encode

    Members

    Apply percent-encoding to a string

    template
    std::size_t
    encode(
        char* dest,
        std::size_t size,
        core::string_view s,
        CharSet const& unreserved,
        encoding_opts opt = = {});
    » more...

    Return a percent-encoded string

    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...
    [#]

    Function encode_unsafe

    Synopsis

                template
    std::size_t
    encode_unsafe(
        char* dest,
        std::size_t size,
        core::string_view s,
        CharSet const& unreserved,
        encoding_opts opt);
            
    [#]

    Class no_value_t

    The type of no_value

    Synopsis

                struct no_value_t;
            
    [#]

    Class param_pct_view

    A query parameter

    Synopsis

                struct param_pct_view;
            

    Member Functions

    Data Members

    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.

    BNF

    query-params = query-param *( "&" query-param ) query-param = key [ "=" value ] key = *qpchar value = *( qpchar / "=" )

    Specification

  • Query string (Wikipedia)
  • [#]

    param_pct_view:: key

    The key

    Synopsis

                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.

    [#]

    param_pct_view:: value

    The value

    Synopsis

                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.

    [#]

    param_pct_view:: has_value

    True if a value is present

    Synopsis

                bool has_value = false;
            

    Description

    The presence of a value is indicated by `has_value == true`. An empty value is distinct from no value.

    Overload set param_pct_view:: param_pct_view

    Members

    Constructor

    constexpr
    param_pct_view() = default;
    » more...

    Constructor

    param_pct_view(
        pct_string_view key,
        pct_string_view value) noexcept;
    » more...

    Constructor

    template
    param_pct_view(
        pct_string_view key,
        OptionalString const& value);
    » more...

    Construction

    param_pct_view(param_view const& p);
    » more...

    param_pct_view(
        pct_string_view key,
        pct_string_view value,
        bool has_value) noexcept;
    » more...
    [#]

    Function param_pct_view:: operator param

    Conversion

    Synopsis

                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.

    Complexity

    Linear in `this->key.size() + this->value.size()`.

    Exception Safety

    Calls to allocate may throw.

    [#]

    Function param_pct_view:: operator param_view

    Synopsis

                operator param_view() const noexcept;
            
    [#]

    Function param_pct_view:: operator->

    Synopsis

                param_pct_view const*
    operator->() const noexcept;
            
    [#]

    Class param_view

    A query parameter

    Synopsis

                struct param_view;
            

    Member Functions

    Data Members

    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.

    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.

    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.

    BNF

    query-params = query-param *( "&" query-param ) query-param = key [ "=" value ] key = *qpchar value = *( qpchar / "=" )

    Specification

  • Query string (Wikipedia)
  • [#]

    param_view:: key

    The key

    Synopsis

                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.

    [#]

    param_view:: value

    The value

    Synopsis

                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.

    [#]

    param_view:: has_value

    True if a value is present

    Synopsis

                bool has_value = false;
            

    Description

    The presence of a value is indicated by `has_value == true`. An empty value is distinct from no value.

    Overload set param_view:: param_view

    Members

    Constructor

    constexpr
    param_view() = default;
    » more...

    Constructor

    template
    param_view(
        core::string_view key,
        OptionalString const& value) noexcept;
    » more...

    Constructor

    param_view(param const& other) noexcept;
    » more...

    param_view(
        core::string_view key_,
        core::string_view value_,
        bool has_value_) noexcept;
    » more...
    [#]

    Function param_view:: operator param

    Conversion

    Synopsis

                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.

    Complexity

    Linear in `this->key.size() + this->value.size()`.

    Exception Safety

    Calls to allocate may throw.

    [#]

    Function param_view:: operator->

    Synopsis

                param_view const*
    operator->() const noexcept;
            
    [#]

    no_value

    Constant indicating no value in a param

    Synopsis

                constexpr
    no_value_t const no_value = {};
            
    [#]

    Class param

    A query parameter

    Synopsis

                struct param;
            

    Member Functions

    Data Members

    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.

    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.

    BNF

    query-params = query-param *( "&" query-param ) query-param = key [ "=" value ] key = *qpchar value = *( qpchar / "=" )

    Specification

  • Query string (Wikipedia)
  • [#]

    param:: key

    The key

    Synopsis

                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.

    [#]

    param:: value

    The value

    Synopsis

                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.

    [#]

    param:: has_value

    True if a value is present

    Synopsis

                bool has_value = false;
            

    Description

    The presence of a value is indicated by `has_value == true`. An empty value is distinct from no value.

    Overload set param:: param

    Members

    Constructor

    param() = default;
    » more...

    Constructor

    param(param&& other) noexcept;
    » more...

    Constructor

    param(param const& other) = default;
    » more...

    Constructor

    template
    param(
        core::string_view key,
        OptionalString const& value);
    » more...

    param(
        core::string_view key,
        core::string_view value,
        bool has_value) noexcept;
    » more...

    Overload set param:: operator=

    Members

    Assignment

    param&
    operator=(param&& other) noexcept;
    » more...

    Assignment

    param&
    operator=(param const&) = default;
    » more...

    Assignment

    param&
    operator=(param_view const& other);
    » more...

    Assignment

    param&
    operator=(param_pct_view const& other);
    » more...
    [#]

    Function param:: operator->

    Synopsis

                param const*
    operator->() const noexcept;
            
    [#]

    Enum host_type

    Identifies the type of host in a URL.

    Synopsis

                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.

    [#]

    Enumerator host_type:: none

    No host is specified.

    Synopsis

                none        
    [#]

    Enumerator host_type:: name

    A host is specified by reg-name.

    Synopsis

                name        
    [#]

    Enumerator host_type:: ipv4

    A host is specified by ipv4_address .

    Synopsis

                ipv4        
    [#]

    Enumerator host_type:: ipv6

    A host is specified by ipv6_address .

    Synopsis

                ipv6        
    [#]

    Enumerator host_type:: ipvfuture

    A host is specified by IPvFuture.

    Synopsis

                ipvfuture        
    [#]

    Enum error

    Error codes returned the library

    Synopsis

                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

    [#]

    Enumerator error:: success

    The operation completed successfully.

    Synopsis

                success = 0        
    [#]

    Enumerator error:: illegal_null

    Null encountered in pct-encoded.

    Synopsis

                illegal_null        
    [#]

    Enumerator error:: illegal_reserved_char

    Illegal reserved character in encoded string.

    Synopsis

                illegal_reserved_char        
    [#]

    Enumerator error:: non_canonical

    A grammar element was not in canonical form.

    Synopsis

                non_canonical        
    [#]

    Enumerator error:: bad_pct_hexdig

    Bad hexadecimal digit.

    Synopsis

                bad_pct_hexdig        

    Description

    This error condition is fatal.

    [#]

    Enumerator error:: incomplete_encoding

    The percent-encoded sequence is incomplete.

    Synopsis

                incomplete_encoding        

    Description

    This error condition is fatal.

    [#]

    Enumerator error:: missing_pct_hexdig

    Missing hexadecimal digit.

    Synopsis

                missing_pct_hexdig        

    Description

    This error condition is fatal.

    [#]

    Enumerator error:: no_space

    No space in output buffer

    Synopsis

                no_space        

    Description

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

    [#]

    Enumerator error:: not_a_base

    The URL is not a base URL

    Synopsis

                not_a_base        
    [#]

    Function make_error_code

    Synopsis

                constexpr
    system::error_code
    make_error_code(error ev) noexcept;
            
    [#]

    Class ipv4_address

    An IP version 4 style address.

    Synopsis

                class ipv4_address;
            

    Types

    Member Functions

    Variables

    Friends

    Description

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

    BNF

    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

    Specification

  • IPv4 (Wikipedia)
  • 3.2.2. Host (rfc3986)
  • [#]

    ipv4_address:: max_str_len

    The number of characters in the longest possible IPv4 string.

    Synopsis

                constexpr
    static
    std::size_t const max_str_len = 15;
            

    Description

    The longest ipv4 address string is "255.255.255.255".

    [#]

    ipv4_address:: uint_type

    The type used to represent an address as an unsigned integer

    Synopsis

                using uint_type = std::uint_least32_t;
            
    [#]

    ipv4_address:: bytes_type

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

    Synopsis

                using bytes_type = std::array;
            

    Overload set ipv4_address:: ipv4_address

    Members

    Constructor.

    constexpr
    ipv4_address() = default;
    » more...

    Constructor.

    constexpr
    ipv4_address(ipv4_address const&) = default;
    » more...

    Construct from an unsigned integer.

    ipv4_address(uint_type u) noexcept;
    » more...

    Construct from an array of bytes.

    ipv4_address(bytes_type const& bytes) noexcept;
    » more...

    Construct from a string.

    ipv4_address(core::string_view s);
    » more...
    [#]

    Function ipv4_address:: operator=

    Copy Assignment.

    Synopsis

                constexpr
    ipv4_address&
    operator=(ipv4_address const&) = default;
            
    [#]

    Function ipv4_address:: to_bytes

    Return the address as bytes, in network byte order.

    Synopsis

                bytes_type
    to_bytes() const noexcept;
            
    [#]

    Function ipv4_address:: to_uint

    Return the address as an unsigned integer.

    Synopsis

                uint_type
    to_uint() const noexcept;
            
    [#]

    Function ipv4_address:: to_string

    Return the address as a string in dotted decimal format

    Synopsis

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

    Example

    assert( ipv4_address(0x01020304).to_string() == "1.2.3.4" );

    Complexity

    Constant.

    Exception Safety

    Strong guarantee. Calls to allocate may throw. String tokens may throw exceptions.

    Specification

  • 2.2. Text Representation of Addresses (rfc4291)
  • [#]

    Function ipv4_address:: to_buffer

    Write a dotted decimal string representing the address to a buffer

    Synopsis

                core::string_view
    to_buffer(
        char* dest,
        std::size_t dest_size) const;
            

    Description

    The resulting buffer is not null-terminated.

    [#]

    Function ipv4_address:: is_loopback

    Return true if the address is a loopback address

    Synopsis

                bool
    is_loopback() const noexcept;
            
    [#]

    Function ipv4_address:: is_unspecified

    Return true if the address is unspecified

    Synopsis

                bool
    is_unspecified() const noexcept;
            
    [#]

    Function ipv4_address:: is_multicast

    Return true if the address is a multicast address

    Synopsis

                bool
    is_multicast() const noexcept;
            
    [#]

    Friend operator==

    Return true if two addresses are equal

    Synopsis

                friend
    bool
    operator==(
        ipv4_address const& a1,
        ipv4_address const& a2) noexcept;
            
    [#]

    Friend operator!=

    Return true if two addresses are not equal

    Synopsis

                friend
    bool
    operator!=(
        ipv4_address const& a1,
        ipv4_address const& a2) noexcept;
            
    [#]

    Function ipv4_address:: any

    Return an address object that represents any address

    Synopsis

                static
    ipv4_address
    any() noexcept;
            
    [#]

    Function ipv4_address:: loopback

    Return an address object that represents the loopback address

    Synopsis

                static
    ipv4_address
    loopback() noexcept;
            
    [#]

    Function ipv4_address:: broadcast

    Return an address object that represents the broadcast address

    Synopsis

                static
    ipv4_address
    broadcast() noexcept;
            
    [#]

    Friend operator<<

    Synopsis

                friend
    std::ostream&
    operator<<(
        std::ostream& os,
        ipv4_address const& addr);
            
    [#]

    Function parse_ipv4_address

    Return an IPv4 address from an IP address string in dotted decimal form

    Synopsis

                system::result
    parse_ipv4_address(core::string_view s) noexcept;
            
    [#]

    Class ipv6_address

    An IP version 6 style address.

    Synopsis

                class ipv6_address;
            

    Types

    Member Functions

    Variables

    Friends

    Description

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

    BNF

    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

    Specification

  • IP Version 6 Addressing Architecture (rfc4291)
  • 3.2.2. Host (rfc3986)
  • [#]

    ipv6_address:: max_str_len

    The number of characters in the longest possible IPv6 string.

    Synopsis

                constexpr
    static
    std::size_t const max_str_len = 49;
            

    Description

    The longest IPv6 address is:

    ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff
    [#]

    ipv6_address:: bytes_type

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

    Synopsis

                using bytes_type = std::array;
            

    Description

    Octets are stored in network byte order.

    Overload set ipv6_address:: ipv6_address

    Members

    Constructor.

    constexpr
    ipv6_address() = default;
    » more...

    Constructor.

    constexpr
    ipv6_address(ipv6_address const&) = default;
    » more...

    Construct from an array of bytes.

    ipv6_address(bytes_type const& bytes) noexcept;
    » more...

    Construct from an IPv4 address.

    ipv6_address(ipv4_address const& addr) noexcept;
    » more...

    Construct from a string.

    ipv6_address(core::string_view s);
    » more...
    [#]

    Function ipv6_address:: operator=

    Copy Assignment

    Synopsis

                constexpr
    ipv6_address&
    operator=(ipv6_address const&) = default;
            
    [#]

    Function ipv6_address:: to_bytes

    Return the address as bytes, in network byte order

    Synopsis

                bytes_type
    to_bytes() const noexcept;
            
    [#]

    Function ipv6_address:: to_string

    Return the address as a string.

    Synopsis

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

    Example

    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" );

    Complexity

    Constant.

    Exception Safety

    Strong guarantee. Calls to allocate may throw. String tokens may throw exceptions.

    Specification

  • 2.2. Text Representation of Addresses (rfc4291)
  • [#]

    Function ipv6_address:: to_buffer

    Write a dotted decimal string representing the address to a buffer

    Synopsis

                core::string_view
    to_buffer(
        char* dest,
        std::size_t dest_size) const;
            

    Description

    The resulting buffer is not null-terminated.

    [#]

    Function ipv6_address:: is_unspecified

    Return true if the address is unspecified

    Synopsis

                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.

    Specification

  • 2.5.2. The Unspecified Address (rfc4291)
  • [#]

    Function ipv6_address:: is_loopback

    Return true if the address is a loopback address

    Synopsis

                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.

    Specification

  • 2.5.3. The Loopback Address (rfc4291)
  • [#]

    Function ipv6_address:: is_v4_mapped

    Return true if the address is a mapped IPv4 address

    Synopsis

                bool
    is_v4_mapped() const noexcept;
            

    Description

    This address type is used to represent the addresses of IPv4 nodes as IPv6 addresses.

    Specification

  • 2.5.5.2. IPv4-Mapped IPv6 Address (rfc4291)
  • [#]

    Friend operator==

    Return true if two addresses are equal

    Synopsis

                friend
    bool
    operator==(
        ipv6_address const& a1,
        ipv6_address const& a2) noexcept;
            
    [#]

    Friend operator!=

    Return true if two addresses are not equal

    Synopsis

                friend
    bool
    operator!=(
        ipv6_address const& a1,
        ipv6_address const& a2) noexcept;
            
    [#]

    Function ipv6_address:: loopback

    Return an address object that represents the loopback address

    Synopsis

                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.

    Specification

  • 2.5.3. The Loopback Address (rfc4291)
  • [#]

    Friend operator<<

    Synopsis

                friend
    std::ostream&
    operator<<(
        std::ostream& os,
        ipv6_address const& addr);
            
    [#]

    Function parse_ipv6_address

    Parse a string containing an IPv6 address.

    Synopsis

                system::result
    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.

    Exception Safety

    Throws nothing.

    [#]

    Enum scheme

    Identifies a known URL scheme

    Synopsis

                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

    Specification

  • 3.1. Scheme (rfc3986)
  • [#]

    Enumerator scheme:: none

    Indicates that no scheme is present

    Synopsis

                none = 0        
    [#]

    Enumerator scheme:: unknown

    Indicates the scheme is not a well-known scheme

    Synopsis

                unknown        
    [#]

    Enumerator scheme:: ftp

    File Transfer Protocol (FTP)

    Synopsis

                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.

    Specification

  • The 'ftp' URI Scheme
  • [#]

    Enumerator scheme:: file

    File URI Scheme

    Synopsis

                file        

    Description

    The File URI Scheme is typically used to retrieve files from within one's own computer.

    Specification

  • The "file" URI Scheme (rfc8089)
  • [#]

    Enumerator scheme:: http

    The Hypertext Transfer Protocol URI Scheme

    Synopsis

                http        

    Description

    URLs of this type indicate a resource which is interacted with using the HTTP protocol.

    Specification

  • Hypertext Transfer Protocol (HTTP/1.1) (rfc7230)
  • [#]

    Enumerator scheme:: https

    The Secure Hypertext Transfer Protocol URI Scheme

    Synopsis

                https        

    Description

    URLs of this type indicate a resource which is interacted with using the Secure HTTP protocol.

    Specification

  • Hypertext Transfer Protocol (HTTP/1.1) (rfc7230)
  • [#]

    Enumerator scheme:: ws

    The WebSocket URI Scheme

    Synopsis

                ws        

    Description

    URLs of this type indicate a resource which is interacted with using the WebSocket protocol.

    Specification

  • The WebSocket Protocol (rfc6455)
  • [#]

    Enumerator scheme:: wss

    The Secure WebSocket URI Scheme

    Synopsis

                wss        

    Description

    URLs of this type indicate a resource which is interacted with using the Secure WebSocket protocol.

    Specification

  • The WebSocket Protocol (rfc6455)
  • [#]

    Function string_to_scheme

    Return the known scheme for a non-normalized string, if known

    Synopsis

                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.

    BNF

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

    Specification

  • 3.1. Scheme (rfc3986)
  • [#]

    Function to_string

    Return the normalized string for a known scheme

    Synopsis

                core::string_view
    to_string(scheme s) noexcept;
            
    [#]

    Function default_port

    Return the default port for a known scheme

    Synopsis

                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
  • [#]

    Class url_view

    A non-owning reference to a valid URL

    Synopsis

                class url_view
        : public url_view_base;
            

    Member Functions

    Friends

    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.

    Example 1

    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" );

    Example 2

    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" );

    BNF

    URI-reference = URI / relative-ref URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ] relative-ref = relative-part [ "?" query ] [ "#" fragment ]

    Specification

  • Uniform Resource Identifier (URI): Generic Syntax (rfc3986)
  • [#]

    Function url_view:: ~url_view

    Destructor

    Synopsis

                ~url_view() = default;
            

    Description

    Any params, segments, iterators, or other views which reference the same underlying character buffer remain valid.

    Overload set url_view:: url_view

    Members

    Constructor

    url_view() noexcept;
    » more...

    Constructor

    url_view(core::string_view s);
    » more...

    template<
        class String,
        class = void>
    url_view(String const& s);
    » more...

    Constructor

    url_view(url_view const& other) noexcept;
    » more...

    Constructor

    url_view(url_view_base const& other) noexcept;
    » more...

    Overload set url_view:: operator=

    Members

    Assignment

    url_view&
    operator=(url_view const& other) noexcept;
    » more...

    Assignment

    url_view&
    operator=(url_view_base const& other) noexcept;
    » more...
    [#]

    Function url_view:: max_size

    Return the maximum number of characters possible

    Synopsis

                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.

    Complexity

    Constant.

    Exception Safety

    Throws nothing.

    [#]

    Class authority_view

    A non-owning reference to a valid authority

    Synopsis

                class authority_view;
            

    Member Functions

    Friends

    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.

    Example 1

    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" );

    Example 2

    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" );

    BNF

    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

    Specification

  • 3.2. Authority (rfc3986)
  • [#]

    Function authority_view:: ~authority_view

    Destructor

    Synopsis

                virtual
    ~authority_view();
            

    Overload set authority_view:: authority_view

    Members

    Constructor

    authority_view() noexcept;
    » more...

    Construct from a string.

    authority_view(core::string_view s);
    » more...

    Constructor

    authority_view(authority_view const&) noexcept;
    » more...
    [#]

    Function authority_view:: operator=

    Assignment

    Synopsis

                authority_view&
    operator=(authority_view const&) noexcept;
            
    [#]

    Function authority_view:: size

    Return the number of characters in the authority

    Synopsis

                std::size_t
    size() const noexcept;
            

    Description

    This function returns the number of characters in the authority.

    Example

    assert( authority_view( "user:pass@www.example.com:8080" ).size() == 30 );

    Exception Safety

    Throws nothing.

    [#]

    Function authority_view:: empty

    Return true if the authority is empty

    Synopsis

                bool
    empty() const noexcept;
            

    Description

    An empty authority has an empty host, no userinfo, and no port.

    Example

    assert( authority_view( "" ).empty() );

    Exception Safety

    Throws nothing.

    [#]

    Function authority_view:: data

    Return a pointer to the first character

    Synopsis

                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.

    Exception Safety

    Throws nothing.

    [#]

    Function authority_view:: buffer

    Return the complete authority

    Synopsis

                core::string_view
    buffer() const noexcept;
            

    Description

    This function returns the authority as a percent-encoded string.

    Example

    assert( parse_authority( "www.example.com" ).value().buffer() == "www.example.com" );

    BNF

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

    Exception Safety

    Throws nothing.

    Specification

  • 3.2. Authority (rfc3986)
  • [#]

    Function authority_view:: has_userinfo

    Return true if a userinfo is present

    Synopsis

                bool
    has_userinfo() const noexcept;
            

    Description

    This function returns true if this contains a userinfo.

    Example

    assert( url_view( "http://jane%2Ddoe:pass@example.com" ).has_userinfo() );

    Complexity

    Constant.

    Exception Safety

    Throws nothing.

    BNF

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

    Specification

  • 3.2.1. User Information (rfc3986)
  • [#]

    Function authority_view:: userinfo

    Return the userinfo

    Synopsis

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

    Example

    assert( url_view( "http://jane%2Ddoe:pass@example.com" ).userinfo() == "jane-doe:pass" );

    Complexity

    Linear in `this->userinfo().size()`.

    Exception Safety

    Calls to allocate may throw.

    BNF

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

    Specification

  • 3.2.1. User Information (rfc3986)
  • [#]

    Function authority_view:: encoded_userinfo

    Return the userinfo

    Synopsis

                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.

    Example

    assert( url_view( "http://jane%2Ddoe:pass@example.com" ).encoded_userinfo() == "jane%2Ddoe:pass" );

    Complexity

    Constant.

    Exception Safety

    Throws nothing

    BNF

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

    Specification

  • 3.2.1. User Information (rfc3986)
  • [#]

    Function authority_view:: user

    Return the user

    Synopsis

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

    Example

    assert( url_view( "http://jane%2Ddoe:pass@example.com" ).user() == "jane-doe" );

    Complexity

    Linear in `this->user().size()`.

    Exception Safety

    Calls to allocate may throw.

    BNF

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

    Specification

  • 3.2.1. User Information (rfc3986)
  • [#]

    Function authority_view:: encoded_user

    Return the user

    Synopsis

                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.

    Example

    assert( url_view( "http://jane%2Ddoe:pass@example.com" ).encoded_user() == "jane%2Ddoe" );

    Complexity

    Constant.

    Exception Safety

    Throws nothing.

    BNF

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

    Specification

  • 3.2.1. User Information (rfc3986)
  • [#]

    Function authority_view:: has_password

    Return true if a password is present

    Synopsis

                bool
    has_password() const noexcept;
            

    Description

    This function returns true if the userinfo is present and contains a password.

    Example

    assert( url_view( "http://jane%2Ddoe:pass@example.com" ).has_password() );

    Complexity

    Constant.

    Exception Safety

    Throws nothing.

    BNF

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

    Specification

  • 3.2.1. User Information (rfc3986)
  • [#]

    Function authority_view:: password

    Return the password

    Synopsis

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

    Example

    assert( url_view( "http://jane%2Ddoe:pass@example.com" ).password() == "pass" );

    Complexity

    Linear in `this->password().size()`.

    Exception Safety

    Calls to allocate may throw.

    BNF

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

    Specification

  • 3.2.1. User Information (rfc3986)
  • [#]

    Function authority_view:: encoded_password

    Return the password

    Synopsis

                pct_string_view
    encoded_password() const noexcept;
            

    Description

    This function returns the password portion of the userinfo as a percent-encoded string.

    Example

    assert( url_view( "http://jane%2Ddoe:pass@example.com" ).encoded_password() == "pass" );

    Complexity

    Constant.

    Exception Safety

    Throws nothing.

    BNF

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

    Specification

  • 3.2.1. User Information (rfc3986)
  • [#]

    Function authority_view:: host_type

    Return the host type

    Synopsis

                host_type
    host_type() const noexcept;
            

    Description

    This function returns one of the following constants representing the type of host present.

  • host_type::ipv4
  • host_type::ipv6
  • host_type::ipvfuture
  • host_type::name
  • Example

    assert( url_view( "https://192.168.0.1/local.htm" ).host_type() == host_type::ipv4 );

    Complexity

    Constant.

    Exception Safety

    Throws nothing.

    Specification

  • 3.2.2. Host (rfc3986)
  • [#]

    Function authority_view:: host

    Return the host

    Synopsis

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

    Example

    assert( url_view( "https://www%2droot.example.com/" ).host() == "www-root.example.com" );

    Complexity

    Linear in `this->host().size()`.

    Exception Safety

    Calls to allocate may throw.

    BNF

    host = IP-literal / IPv4address / reg-name IP-literal = "[" ( IPv6address / IPvFuture ) "]" reg-name = *( unreserved / pct-encoded / "-" / ".")

    Specification

  • 3.2.2. Host (rfc3986)
  • [#]

    Function authority_view:: encoded_host

    Return the host

    Synopsis

                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.

    Example

    assert( url_view( "https://www%2droot.example.com/" ).encoded_host() == "www%2droot.example.com" );

    Complexity

    Constant.

    Exception Safety

    Throws nothing.

    BNF

    host = IP-literal / IPv4address / reg-name IP-literal = "[" ( IPv6address / IPvFuture ) "]" reg-name = *( unreserved / pct-encoded / "-" / ".")

    Specification

  • 3.2.2. Host (rfc3986)
  • [#]

    Function authority_view:: host_address

    Return the host

    Synopsis

                template
    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.
  • Example

    assert( url_view( "https://[1::6:c0a8:1]/" ).host_address() == "1::6:c0a8:1" );

    Complexity

    Linear in `this->host_address().size()`.

    Exception Safety

    Calls to allocate may throw.

    BNF

    host = IP-literal / IPv4address / reg-name IP-literal = "[" ( IPv6address / IPvFuture ) "]" reg-name = *( unreserved / pct-encoded / "-" / ".")

    Specification

  • 3.2.2. Host (rfc3986)
  • [#]

    Function authority_view:: encoded_host_address

    Return the host

    Synopsis

                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.
  • Example

    assert( url_view( "https://www%2droot.example.com/" ).encoded_host_address() == "www%2droot.example.com" );

    Complexity

    Constant.

    Exception Safety

    Throws nothing.

    BNF

    host = IP-literal / IPv4address / reg-name IP-literal = "[" ( IPv6address / IPvFuture ) "]" reg-name = *( unreserved / pct-encoded / "-" / ".")

    Specification

  • 3.2.2. Host (rfc3986)
  • [#]

    Function authority_view:: host_ipv4_address

    Return the host IPv4 address

    Synopsis

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

    Example

    assert( url_view( "http://127.0.0.1/index.htm?user=win95" ).host_ipv4_address() == ipv4_address( "127.0.0.1" ) );

    Complexity

    Constant.

    Exception Safety

    Throws nothing.

    BNF

    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

    Specification

  • 3.2.2. Host (rfc3986)
  • [#]

    Function authority_view:: host_ipv6_address

    Return the host IPv6 address

    Synopsis

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

    Example

    assert( url_view( "ftp://[::1]/" ).host_ipv6_address() == ipv6_address( "::1" ) );

    Complexity

    Constant.

    Exception Safety

    Throws nothing.

    BNF

    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

    Specification

  • 3.2.2. Host (rfc3986)
  • [#]

    Function authority_view:: host_ipvfuture

    Return the host IPvFuture address

    Synopsis

                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.

    Example

    assert( url_view( "http://[v1fe.d:9]/index.htm" ).host_ipvfuture() == "v1fe.d:9" );

    Complexity

    Constant.

    Exception Safety

    Throws nothing.

    BNF

    IPvFuture = "v" 1*HEXDIG "." 1*( unreserved / sub-delims / ":" )

    Specification

  • 3.2.2. Host (rfc3986)
  • [#]

    Function authority_view:: host_name

    Return the host name

    Synopsis

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

    Example

    assert( url_view( "https://www%2droot.example.com/" ).host_name() == "www-root.example.com" );

    Complexity

    Linear in `this->host_name().size()`.

    Exception Safety

    Calls to allocate may throw.

    BNF

    host = IP-literal / IPv4address / reg-name IP-literal = "[" ( IPv6address / IPvFuture ) "]" reg-name = *( unreserved / pct-encoded / "-" / ".")

    Specification

  • 3.2.2. Host (rfc3986)
  • [#]

    Function authority_view:: encoded_host_name

    Return the host name

    Synopsis

                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.

    Example

    assert( url_view( "https://www%2droot.example.com/" ).encoded_host_name() == "www%2droot.example.com" );

    Complexity

    Constant.

    Exception Safety

    Throws nothing.

    BNF

    host = IP-literal / IPv4address / reg-name IP-literal = "[" ( IPv6address / IPvFuture ) "]" reg-name = *( unreserved / pct-encoded / "-" / ".")

    Specification

  • 3.2.2. Host (rfc3986)
  • [#]

    Function authority_view:: has_port

    Return true if a port is present

    Synopsis

                bool
    has_port() const noexcept;
            

    Description

    This function returns true if an authority is present and contains a port.

    Example

    assert( url_view( "wss://www.example.com:443" ).has_port() );

    Complexity

    Constant.

    Exception Safety

    Throws nothing.

    BNF

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

    Specification

  • 3.2.3. Port (rfc3986)
  • [#]

    Function authority_view:: port

    Return the port

    Synopsis

                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.

    Example

    assert( url_view( "http://localhost.com:8080" ).port() == "8080" );

    Complexity

    Constant.

    Exception Safety

    Throws nothing.

    BNF

    port = *DIGIT

    Specification

  • 3.2.3. Port (rfc3986)
  • [#]

    Function authority_view:: port_number

    Return the port

    Synopsis

                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.

    Example

    assert( url_view( "http://localhost.com:8080" ).port_number() == 8080 );

    Complexity

    Constant.

    Exception Safety

    Throws nothing.

    BNF

    port = *DIGIT

    Specification

  • 3.2.3. Port (rfc3986)
  • [#]

    Function authority_view:: encoded_host_and_port

    Return the host and port

    Synopsis

                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.

    Example

    assert( url_view( "http://www.example.com:8080/index.htm" ).encoded_host_and_port() == "www.example.com:8080" );

    Complexity

    Constant.

    Exception Safety

    Throws nothing.

    BNF

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

    Specification

  • 3.2.2. Host (rfc3986)
  • 3.2.3. Port (rfc3986)
  • [#]

    Function authority_view:: compare

    Return the result of comparing this with another authority

    Synopsis

                int
    compare(authority_view const& other) const noexcept;
            

    Description

    This function compares two authorities according to Syntax-Based comparison algorithm.

    Exception Safety

    Throws nothing.

    Specification

  • 6.2.2 Syntax-Based Normalization (rfc3986)
  • [#]

    Friend operator==

    Return the result of comparing two authorities The authorities are compared component by component as if they were first normalized.

    Synopsis

                friend
    bool
    operator==(
        authority_view const& a0,
        authority_view const& a1) noexcept;
            

    Description

    Complexity

    Linear in `min( a0.size(), a1.size() )`

    Exception Safety

    Throws nothing

    [#]

    Friend operator!=

    Return the result of comparing two authorities The authorities are compared component by component as if they were first normalized.

    Synopsis

                friend
    bool
    operator!=(
        authority_view const& a0,
        authority_view const& a1) noexcept;
            

    Description

    Complexity

    Linear in `min( a0.size(), a1.size() )`

    Exception Safety

    Throws nothing

    [#]

    Friend operator<

    Return the result of comparing two authorities The authorities are compared component by component as if they were first normalized.

    Synopsis

                friend
    bool
    operator<(
        authority_view const& a0,
        authority_view const& a1) noexcept;
            

    Description

    Complexity

    Linear in `min( a0.size(), a1.size() )`

    Exception Safety

    Throws nothing

    [#]

    Friend operator<=

    Return the result of comparing two authorities The authorities are compared component by component as if they were first normalized.

    Synopsis

                friend
    bool
    operator<=(
        authority_view const& a0,
        authority_view const& a1) noexcept;
            

    Description

    Complexity

    Linear in `min( a0.size(), a1.size() )`

    Exception Safety

    Throws nothing

    [#]

    Friend operator>

    Return the result of comparing two authorities The authorities are compared component by component as if they were first normalized.

    Synopsis

                friend
    bool
    operator>(
        authority_view const& a0,
        authority_view const& a1) noexcept;
            

    Description

    Complexity

    Linear in `min( a0.size(), a1.size() )`

    Exception Safety

    Throws nothing

    [#]

    Friend operator>=

    Return the result of comparing two authorities The authorities are compared component by component as if they were first normalized.

    Synopsis

                friend
    bool
    operator>=(
        authority_view const& a0,
        authority_view const& a1) noexcept;
            

    Description

    Complexity

    Linear in `min( a0.size(), a1.size() )`

    Exception Safety

    Throws nothing

    [#]

    Friend operator<<

    Synopsis

                friend
    std::ostream&
    operator<<(
        std::ostream& os,
        authority_view const& a);
            
    [#]

    Function parse_authority

    Parse an authority

    Synopsis

                system::result
    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.

    BNF

    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

    Exception Safety

    Throws nothing.

    Specification

  • 3.2. Authority (rfc3986)
  • [#]

    Class ignore_case_t

    Synopsis

                struct ignore_case_t;
            
    [#]

    ignore_case

    Synopsis

                constexpr
    ignore_case_t const ignore_case = {};
            
    [#]

    Class ignore_case_param

    An optional parameter to determine case-sensitivity

    Synopsis

                class ignore_case_param;
            

    Member Functions

    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.

    Overload set ignore_case_param:: ignore_case_param

    Members

    Constructor

    constexpr
    ignore_case_param() noexcept = default;
    » more...

    Constructor

    constexpr
    ignore_case_param(ignore_case_t) noexcept;
    » more...
    [#]

    Function ignore_case_param:: operator bool

    True if an algorithm should ignore case

    Synopsis

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

    [#]

    Class segments_encoded_base

    Common functionality for containers

    Synopsis

                class segments_encoded_base;
            

    Types

    Types

    Member Functions

    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:

    Containers

  • segments_ref
  • segments_view
  • segments_encoded_ref
  • segments_encoded_view
  • [#]

    Class segments_encoded_base:: iterator

    Synopsis

                class iterator;
            

    Types

    Member Functions

    [#]

    segments_encoded_base:: iterator:: value_type

    Synopsis

                using value_type = value_type;
            
    [#]

    segments_encoded_base:: iterator:: reference

    Synopsis

                using reference = reference;
            
    [#]

    segments_encoded_base:: iterator:: pointer

    Synopsis

                using pointer = reference;
            
    [#]

    segments_encoded_base:: iterator:: difference_type

    Synopsis

                using difference_type = std::ptrdiff_t;
            
    [#]

    segments_encoded_base:: iterator:: iterator_category

    Synopsis

                using iterator_category = std::bidirectional_iterator_tag;
            

    Overload set segments_encoded_base:: iterator:: iterator

    Members

    constexpr
    iterator() = default;
    » more...

    constexpr
    iterator(iterator const&) = default;
    » more...
    [#]

    Function segments_encoded_base:: iterator:: operator=

    Synopsis

                constexpr
    iterator&
    operator=(iterator const&) = default;
            
    [#]

    Function segments_encoded_base:: iterator:: operator*

    Synopsis

                reference
    operator*() const noexcept;
            
    [#]

    Function segments_encoded_base:: iterator:: operator->

    Synopsis

                pointer
    operator->() const noexcept;
            

    Overload set segments_encoded_base:: iterator:: operator++

    Members

    iterator&
    operator++() noexcept;
    » more...

    iterator
    operator++(int) noexcept;
    » more...

    Overload set segments_encoded_base:: iterator:: operator--

    Members

    iterator&
    operator--() noexcept;
    » more...

    iterator
    operator--(int) noexcept;
    » more...
    [#]

    Function segments_encoded_base:: iterator:: operator==

    Synopsis

                bool
    operator==(iterator const& other) const noexcept;
            
    [#]

    Function segments_encoded_base:: iterator:: operator!=

    Synopsis

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

    segments_encoded_base:: const_iterator

    iterator

    Synopsis

                using const_iterator = iterator;
            
    [#]

    segments_encoded_base:: value_type

    The value type

    Synopsis

                using value_type = std::string;
            

    Description

    Values of this type represent a segment where unique ownership is retained by making a copy.

    Example

    segments_encoded_base::value_type ps( url_view( "/path/to/file.txt" ).encoded_segments().back() );
    [#]

    segments_encoded_base:: reference

    The reference type

    Synopsis

                using reference = pct_string_view;
            

    Description

    This is the type of value returned when iterators of the view are dereferenced.

    [#]

    segments_encoded_base:: const_reference

    The reference type

    Synopsis

                using const_reference = pct_string_view;
            

    Description

    This is the type of value returned when iterators of the view are dereferenced.

    [#]

    segments_encoded_base:: size_type

    An unsigned integer type used to represent size.

    Synopsis

                using size_type = std::size_t;
            
    [#]

    segments_encoded_base:: difference_type

    A signed integer type used to represent differences.

    Synopsis

                using difference_type = std::ptrdiff_t;
            
    [#]

    Function segments_encoded_base:: max_size

    Return the maximum number of characters possible

    Synopsis

                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.

    Exception Safety

    Throws nothing.

    [#]

    Function segments_encoded_base:: buffer

    Return the referenced character buffer.

    Synopsis

                pct_string_view
    buffer() const noexcept;
            

    Description

    This function returns the character buffer referenced by the view. The returned string may contain percent escapes.

    Example

    assert( url_view( "/path/to/file.txt" ).encoded_segments().buffer() == "/path/to/file.txt" );

    Complexity

    Constant.

    Exception Safety

    Throws nothing.

    [#]

    Function segments_encoded_base:: is_absolute

    Returns true if this references an absolute path.

    Synopsis

                bool
    is_absolute() const noexcept;
            

    Description

    Absolute paths always start with a forward slash ('/').

    Example

    assert( url_view( "/path/to/file.txt" ).encoded_segments().is_absolute() == true );

    Complexity

    Constant.

    Exception Safety

    Throws nothing.

    [#]

    Function segments_encoded_base:: empty

    Return true if there are no segments

    Synopsis

                bool
    empty() const noexcept;
            

    Description

    Example

    assert( ! url_view( "/index.htm" ).encoded_segments().empty() );

    Complexity

    Constant.

    Exception Safety

    Throws nothing.

    [#]

    Function segments_encoded_base:: size

    Return the number of segments

    Synopsis

                std::size_t
    size() const noexcept;
            

    Description

    Example

    assert( url_view( "/path/to/file.txt" ).encoded_segments().size() == 3 );

    Complexity

    Constant.

    Exception Safety

    Throws nothing.

    [#]

    Function segments_encoded_base:: front

    Return the first segment

    Synopsis

                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.

    Preconditions

    this->empty() == false

    Effects

    return *begin();

    Example

    assert( url_view( "/path/to/file.txt" ).encoded_segments().front() == "path" );

    Complexity

    Constant.

    Exception Safety

    Throws nothing.

    [#]

    Function segments_encoded_base:: back

    Return the last segment

    Synopsis

                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.

    Preconditions

    this->empty() == false

    Example

    assert( url_view( "/path/to/file.txt" ).encoded_segments().back() == "file.txt" );

    Preconditions

    this->empty() == false

    Effects

    return *--end();

    Complexity

    Constant.

    Exception Safety

    Throws nothing.

    [#]

    Function segments_encoded_base:: begin

    Return an iterator to the beginning

    Synopsis

                iterator
    begin() const noexcept;
            

    Description

    Complexity

    Linear in `this->front().size()` or constant if `this->empty()`.

    Exception Safety

    Throws nothing.

    [#]

    Function segments_encoded_base:: end

    Return an iterator to the end

    Synopsis

                iterator
    end() const noexcept;
            

    Description

    Complexity

    Constant.

    Exception Safety

    Throws nothing.

    [#]

    Class segments_base

    Common functionality for containers

    Synopsis

                class segments_base;
            

    Types

    Types

    Member Functions

    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:

    Containers

  • segments_ref
  • segments_view
  • segments_encoded_ref
  • segments_encoded_view
  • [#]

    Class segments_base:: iterator

    Synopsis

                class iterator;
            

    Types

    Member Functions

    [#]

    segments_base:: iterator:: value_type

    Synopsis

                using value_type = value_type;
            
    [#]

    segments_base:: iterator:: reference

    Synopsis

                using reference = reference;
            
    [#]

    segments_base:: iterator:: pointer

    Synopsis

                using pointer = reference;
            
    [#]

    segments_base:: iterator:: difference_type

    Synopsis

                using difference_type = difference_type;
            
    [#]

    segments_base:: iterator:: iterator_category

    Synopsis

                using iterator_category = std::bidirectional_iterator_tag;
            

    Overload set segments_base:: iterator:: iterator

    Members

    constexpr
    iterator() = default;
    » more...

    constexpr
    iterator(iterator const&) = default;
    » more...
    [#]

    Function segments_base:: iterator:: operator=

    Synopsis

                constexpr
    iterator&
    operator=(iterator const&) noexcept = default;
            
    [#]

    Function segments_base:: iterator:: operator*

    Synopsis

                reference
    operator*() const;
            
    [#]

    Function segments_base:: iterator:: operator->

    Synopsis

                pointer
    operator->() const = delete;
            

    Overload set segments_base:: iterator:: operator++

    Members

    iterator&
    operator++() noexcept;
    » more...

    iterator
    operator++(int) noexcept;
    » more...

    Overload set segments_base:: iterator:: operator--

    Members

    iterator&
    operator--() noexcept;
    » more...

    iterator
    operator--(int) noexcept;
    » more...
    [#]

    Function segments_base:: iterator:: operator==

    Synopsis

                bool
    operator==(iterator const& other) const noexcept;
            
    [#]

    Function segments_base:: iterator:: operator!=

    Synopsis

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

    segments_base:: const_iterator

    iterator

    Synopsis

                using const_iterator = iterator;
            
    [#]

    segments_base:: value_type

    The value type

    Synopsis

                using value_type = std::string;
            

    Description

    Values of this type represent a segment where unique ownership is retained by making a copy.

    Example

    segments_base::value_type ps( url_view( "/path/to/file.txt" ).segments().back() );
    [#]

    segments_base:: reference

    The reference type

    Synopsis

                using reference = std::string;
            

    Description

    This is the type of value returned when iterators of the view are dereferenced.

    [#]

    segments_base:: const_reference

    The reference type

    Synopsis

                using const_reference = std::string;
            

    Description

    This is the type of value returned when iterators of the view are dereferenced.

    [#]

    segments_base:: size_type

    An unsigned integer type used to represent size.

    Synopsis

                using size_type = std::size_t;
            
    [#]

    segments_base:: difference_type

    A signed integer type used to represent differences.

    Synopsis

                using difference_type = std::ptrdiff_t;
            
    [#]

    Function segments_base:: max_size

    Return the maximum number of characters possible

    Synopsis

                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.

    Exception Safety

    Throws nothing.

    [#]

    Function segments_base:: buffer

    Return the referenced character buffer.

    Synopsis

                pct_string_view
    buffer() const noexcept;
            

    Description

    This function returns the character buffer referenced by the view. The returned string may contain percent escapes.

    Example

    assert( url_view( "/path/to/file.txt" ).segments().buffer() == "/path/to/file.txt" );

    Complexity

    Constant.

    Exception Safety

    Throws nothing.

    [#]

    Function segments_base:: is_absolute

    Returns true if this references an absolute path.

    Synopsis

                bool
    is_absolute() const noexcept;
            

    Description

    Absolute paths always start with a forward slash ('/').

    Example

    assert( url_view( "/path/to/file.txt" ).segments().is_absolute() == true );

    Complexity

    Constant.

    Exception Safety

    Throws nothing.

    [#]

    Function segments_base:: empty

    Return true if there are no segments

    Synopsis

                bool
    empty() const noexcept;
            

    Description

    Example

    assert( ! url_view( "/index.htm" ).segments().empty() );

    Complexity

    Constant.

    Exception Safety

    Throws nothing.

    [#]

    Function segments_base:: size

    Return the number of segments

    Synopsis

                std::size_t
    size() const noexcept;
            

    Description

    Example

    assert( url_view( "/path/to/file.txt" ).segments().size() == 3 );

    Complexity

    Constant.

    Exception Safety

    Throws nothing.

    [#]

    Function segments_base:: front

    Return the first segment

    Synopsis

                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.

    Preconditions

    this->empty() == false

    Effects

    return *begin();

    Example

    assert( url_view( "/path/to/file.txt" ).segments().front() == "path" );

    Complexity

    Linear in `this->front().size()`.

    Exception Safety

    Calls to allocate may throw.

    [#]

    Function segments_base:: back

    Return the last segment

    Synopsis

                std::string
    back() const noexcept;
            

    Description

    Preconditions

    this->empty() == false

    Example

    assert( url_view( "/path/to/file.txt" ).segments().back() == "file.txt" );

    Preconditions

    this->empty() == false

    Effects

    return *--end();

    Complexity

    Linear in `this->back().size()`.

    Exception Safety

    Calls to allocate may throw.

    [#]

    Function segments_base:: begin

    Return an iterator to the beginning

    Synopsis

                iterator
    begin() const noexcept;
            

    Description

    Complexity

    Linear in `this->front().size()` or constant if `this->empty()`.

    Exception Safety

    Throws nothing.

    [#]

    Function segments_base:: end

    Return an iterator to the end

    Synopsis

                iterator
    end() const noexcept;
            

    Description

    Complexity

    Constant.

    Exception Safety

    Throws nothing.

    [#]

    Class segments_view

    A view representing path segments in a URL

    Synopsis

                class segments_view
        : public segments_base;
            

    Types

    Types

    Member Functions

    Description

    Objects of this type are used to interpret the path as a bidirectional view of segment strings.

    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.

    Example

    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.

    Iterator Invalidation

    Changes to the underlying character buffer can invalidate iterators which reference it.

    Overload set segments_view:: segments_view

    Members

    Constructor

    constexpr
    segments_view() = default;
    » more...

    Constructor

    constexpr
    segments_view(segments_view const& other) = default;
    » more...

    Constructor

    segments_view(core::string_view s);
    » more...
    [#]

    Function segments_view:: operator=

    Assignment

    Synopsis

                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.

    Postconditions

    this->buffer().data() == other.buffer().data()

    Complexity

    Constant

    Exception Safety

    Throws nothing

    [#]

    Class segments_encoded_view

    A view representing path segments in a URL

    Synopsis

                class segments_encoded_view
        : public segments_encoded_base;
            

    Types

    Types

    Member Functions

    Friends

    Description

    Objects of this type are used to interpret the path as a bidirectional view of segment strings.

    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.

    Example

    url_view u( "/path/to/file.txt" ); segments_encoded_view ps = u.encoded_segments(); assert( ps.buffer().data() == u.buffer().data() );

    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.

    Iterator Invalidation

    Changes to the underlying character buffer can invalidate iterators which reference it.

    Overload set segments_encoded_view:: segments_encoded_view

    Members

    Constructor

    constexpr
    segments_encoded_view() = default;
    » more...

    Constructor

    constexpr
    segments_encoded_view(segments_encoded_view const&) noexcept = default;
    » more...

    Constructor

    segments_encoded_view(core::string_view s);
    » more...
    [#]

    Function segments_encoded_view:: operator=

    Assignment

    Synopsis

                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.

    Postconditions

    this->buffer().data() == other.buffer().data()

    Complexity

    Constant

    Exception Safety

    Throws nothing

    [#]

    Function segments_encoded_view:: operator segments_view

    Conversion

    Synopsis

                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.

    Example

    segments_view ps = parse_path( "/path/to/file.txt" ).value();

    Postconditions

    segments_view( *this ).buffer().data() == this->buffer().data()

    Complexity

    Constant

    Exception Safety

    Throws nothing

    [#]

    Friend parse_path

    Synopsis

                friend
    system::result
    parse_path(core::string_view s) noexcept;
            
    [#]

    Function parse_path

    Parse a string and return an encoded segment view

    Synopsis

                system::result
    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.

    BNF

    path = [ "/" ] segment *( "/" segment )

    Exception Safety

    No-throw guarantee.

    Specification

  • 3.3. Path (rfc3986)
  • [#]

    Class authority_rule_t

    Synopsis

                struct authority_rule_t;
            

    Types

    Member Functions

    [#]

    authority_rule_t:: value_type

    Synopsis

                using value_type = authority_view;
            
    [#]

    Function authority_rule_t:: parse

    Synopsis

                system::result
    parse(
        char const*& it,
        char const* end) const noexcept;
            
    [#]

    authority_rule

    Synopsis

                constexpr
    authority_rule_t const authority_rule = {};
            
    [#]

    Class pct_encoded_rule_t

    Synopsis

                template
    struct pct_encoded_rule_t;
            

    Types

    Member Functions

    Friends

    [#]

    pct_encoded_rule_t:: value_type

    Synopsis

                using value_type = pct_string_view;
            
    [#]

    Friend pct_encoded_rule

    Synopsis

                template
    friend
    constexpr
    pct_encoded_rule_t
    pct_encoded_rule(CharSet_ const& cs) noexcept;
            
    [#]

    Function pct_encoded_rule_t:: parse

    Synopsis

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

    Overload set pct_encoded_rule

    Members

    template
    constexpr
    pct_encoded_rule_t
    pct_encoded_rule(CharSet_ const& cs) noexcept;
    » more...

    template
    constexpr
    pct_encoded_rule_t
    pct_encoded_rule(CharSet const& cs) noexcept;
    » more...
    [#]

    variant

    The type of variant used by the library

    Synopsis

                template
    using variant = variant2::variant;
            

    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.

    [#]

    optional

    Synopsis

                template
    using optional = optional;
            
    [#]

    Class params_encoded_base

    Common functionality for containers

    Synopsis

                class params_encoded_base;
            

    Types

    Types

    Member Functions

    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:

    Containers

  • params_ref
  • params_view
  • params_encoded_ref
  • params_encoded_view
  • [#]

    Class params_encoded_base:: iterator

    Synopsis

                class iterator;
            

    Types

    Member Functions

    Friends

    [#]

    params_encoded_base:: iterator:: value_type

    Synopsis

                using value_type = value_type;
            
    [#]

    params_encoded_base:: iterator:: reference

    Synopsis

                using reference = reference;
            
    [#]

    params_encoded_base:: iterator:: pointer

    Synopsis

                using pointer = reference;
            
    [#]

    params_encoded_base:: iterator:: difference_type

    Synopsis

                using difference_type = std::ptrdiff_t;
            
    [#]

    params_encoded_base:: iterator:: iterator_category

    Synopsis

                using iterator_category = std::bidirectional_iterator_tag;
            

    Overload set params_encoded_base:: iterator:: iterator

    Members

    iterator() = default;
    » more...

    constexpr
    iterator(iterator const&) = default;
    » more...
    [#]

    Function params_encoded_base:: iterator:: operator=

    Synopsis

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

    Overload set params_encoded_base:: iterator:: operator++

    Members

    iterator&
    operator++() noexcept;
    » more...

    iterator
    operator++(int) noexcept;
    » more...

    Overload set params_encoded_base:: iterator:: operator--

    Members

    iterator&
    operator--() noexcept;
    » more...

    iterator
    operator--(int) noexcept;
    » more...
    [#]

    Function params_encoded_base:: iterator:: operator*

    Synopsis

                reference
    operator*() const;
            
    [#]

    Function params_encoded_base:: iterator:: operator->

    Synopsis

                pointer
    operator->() const;
            
    [#]

    Friend operator==

    Synopsis

                friend
    bool
    operator==(
        iterator const& it0,
        iterator const& it1) noexcept;
            
    [#]

    Friend operator!=

    Synopsis

                friend
    bool
    operator!=(
        iterator const& it0,
        iterator const& it1) noexcept;
            
    [#]

    params_encoded_base:: const_iterator

    iterator

    Synopsis

                using const_iterator = iterator;
            
    [#]

    params_encoded_base:: value_type

    The value type

    Synopsis

                using value_type = param;
            

    Description

    Values of this type represent parameters whose strings retain unique ownership by making a copy.

    Example

    params_encoded_view::value_type qp( *url_view( "?first=John&last=Doe" ).params().find( "first" ) );
    [#]

    params_encoded_base:: reference

    The reference type

    Synopsis

                using reference = param_pct_view;
            

    Description

    This is the type of value returned when iterators of the view are dereferenced.

    [#]

    params_encoded_base:: const_reference

    The reference type

    Synopsis

                using const_reference = param_pct_view;
            

    Description

    This is the type of value returned when iterators of the view are dereferenced.

    [#]

    params_encoded_base:: size_type

    An unsigned integer type to represent sizes.

    Synopsis

                using size_type = std::size_t;
            
    [#]

    params_encoded_base:: difference_type

    A signed integer type used to represent differences.

    Synopsis

                using difference_type = std::ptrdiff_t;
            
    [#]

    Function params_encoded_base:: max_size

    Return the maximum number of characters possible

    Synopsis

                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.

    Exception Safety

    Throws nothing.

    [#]

    Function params_encoded_base:: buffer

    Return the query corresponding to these params

    Synopsis

                pct_string_view
    buffer() const noexcept;
            

    Description

    This function returns the query string referenced by the container. The returned string may contain percent escapes.

    Example

    assert( url_view( "?first=John&last=Doe" ).encoded_params().buffer() == "first=John&last=Doe" );

    Complexity

    Constant.

    Exception Safety

    Throws nothing.

    BNF

    query-params = query-param *( "&" query-param ) query-param = key [ "=" value ] key = *qpchar value = *( qpchar / "=" )

    Specification

  • Query string (Wikipedia)
  • [#]

    Function params_encoded_base:: empty

    Return true if there are no params

    Synopsis

                bool
    empty() const noexcept;
            

    Description

    Example

    assert( ! url_view( "?key=value" ).encoded_params().empty() );

    Complexity

    Constant.

    Exception Safety

    Throws nothing.

    [#]

    Function params_encoded_base:: size

    Return the number of params

    Synopsis

                std::size_t
    size() const noexcept;
            

    Description

    Example

    assert( url_view( "?key=value").encoded_params().size() == 1 );

    Complexity

    Constant.

    Exception Safety

    Throws nothing.

    [#]

    Function params_encoded_base:: begin

    Return an iterator to the beginning

    Synopsis

                iterator
    begin() const noexcept;
            

    Description

    Complexity

    Linear in the size of the first param.

    Exception Safety

    Throws nothing.

    [#]

    Function params_encoded_base:: end

    Return an iterator to the end

    Synopsis

                iterator
    end() const noexcept;
            

    Description

    Complexity

    Constant.

    Exception Safety

    Throws nothing.

    [#]

    Function params_encoded_base:: contains

    Return true if a matching key exists

    Synopsis

                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.

    Example

    assert( url_view( "?first=John&last=Doe" ).encoded_params().contains( "first" ) );

    Complexity

    Linear in `this->buffer().size()`.

    Exception Safety

    Exceptions thrown on invalid input.

    [#]

    Function params_encoded_base:: count

    Return the number of matching keys

    Synopsis

                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.

    Example

    assert( url_view( "?first=John&last=Doe" ).encoded_params().count( "first" ) == 1 );

    Complexity

    Linear in `this->buffer().size()`.

    Exception Safety

    Exceptions thrown on invalid input.

    Overload set params_encoded_base:: find

    Members

    Find a matching key

    iterator
    find(
        pct_string_view key,
        ignore_case_param ic = = {}) const noexcept;
    » more...

    Find a matching key

    iterator
    find(
        iterator from,
        pct_string_view key,
        ignore_case_param ic = = {}) const noexcept;
    » more...

    Overload set params_encoded_base:: find_last

    Members

    Find a matching key

    iterator
    find_last(
        pct_string_view key,
        ignore_case_param ic = = {}) const noexcept;
    » more...

    Find a matching key

    iterator
    find_last(
        iterator before,
        pct_string_view key,
        ignore_case_param ic = = {}) const noexcept;
    » more...
    [#]

    Class params_ref

    A view representing query parameters in a URL

    Synopsis

                class params_ref
        : public params_base;
            

    Types

    Types

    Member Functions

    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.

    Example

    url u( "?first=John&last=Doe" ); params_ref p = u.params();

    Iterator Invalidation

    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()`).
  • Overload set params_ref:: params_ref

    Members

    Constructor

    constexpr
    params_ref(params_ref const& other) = default;
    » more...

    Constructor

    params_ref(
        params_ref const& other,
        encoding_opts opt) noexcept;
    » more...

    Overload set params_ref:: operator=

    Members

    Assignment

    params_ref&
    operator=(params_ref const& other);
    » more...

    Assignment

    params_ref&
    operator=(std::initializer_list init);
    » more...
    [#]

    Function params_ref:: operator params_view

    Conversion

    Synopsis

                operator params_view() const noexcept;
            
    [#]

    Function params_ref:: url

    Return the referenced url

    Synopsis

                url_base&
    url() const noexcept;
            

    Description

    This function returns the url referenced by the view.

    Example

    url u( "?key=value" ); assert( &u.segments().url() == &u );

    Exception Safety

    Throws nothing.
    [#]

    Function params_ref:: clear

    Clear the contents of the container

    Synopsis

                void
    clear() noexcept;
            

    Description

    All iterators are invalidated.

    Effects

    this->url().remove_query();

    Postconditions

    this->empty() == true && this->url().has_query() == false

    Complexity

    Constant.

    Exception Safety

    Throws nothing.

    Overload set params_ref:: assign

    Members

    Assign elements

    void
    assign(std::initializer_list init);
    » more...

    Assign elements

    template
    void
    assign(
        FwdIt first,
        FwdIt last);
    » more...

    Overload set params_ref:: append

    Members

    Append elements

    iterator
    append(param_view const& p);
    » more...

    Append elements

    iterator
    append(std::initializer_list init);
    » more...

    Append elements

    template
    iterator
    append(
        FwdIt first,
        FwdIt last);
    » more...

    Overload set params_ref:: insert

    Members

    Insert elements

    iterator
    insert(
        iterator before,
        param_view const& p);
    » more...

    Insert elements

    iterator
    insert(
        iterator before,
        std::initializer_list init);
    » more...

    Insert elements

    template
    iterator
    insert(
        iterator before,
        FwdIt first,
        FwdIt last);
    » more...

    Overload set params_ref:: erase

    Members

    Erase elements

    iterator
    erase(iterator pos) noexcept;
    » more...

    Erase elements

    iterator
    erase(
        iterator first,
        iterator last) noexcept;
    » more...

    Erase elements

    std::size_t
    erase(
        core::string_view key,
        ignore_case_param ic = = {}) noexcept;
    » more...

    Overload set params_ref:: replace

    Members

    Replace elements

    iterator
    replace(
        iterator pos,
        param_view const& p);
    » more...

    Replace elements

    iterator
    replace(
        iterator from,
        iterator to,
        std::initializer_list init);
    » more...

    Replace elements

    template
    iterator
    replace(
        iterator from,
        iterator to,
        FwdIt first,
        FwdIt last);
    » more...
    [#]

    Function params_ref:: unset

    Remove the value on an element

    Synopsis

                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.

    Example

    url u( "?first=John&last=Doe" ); u.params().unset( u.params().begin() ); assert( u.encoded_query() == "first&last=Doe" );

    Complexity

    Linear in `this->url().encoded_query().size()`.

    Exception Safety

    Throws nothing.

    Overload set params_ref:: set

    Members

    Set a value

    iterator
    set(
        iterator pos,
        core::string_view value);
    » more...

    Set a value

    iterator
    set(
        core::string_view key,
        core::string_view value,
        ignore_case_param ic = = {});
    » more...
    [#]

    Class params_base

    Common functionality for containers

    Synopsis

                class params_base;
            

    Types

    Types

    Member Functions

    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:

    Containers

  • params_ref
  • params_view
  • params_encoded_ref
  • params_encoded_view
  • [#]

    Class params_base:: iterator

    Synopsis

                class iterator;
            

    Types

    Member Functions

    [#]

    params_base:: iterator:: value_type

    Synopsis

                using value_type = value_type;
            
    [#]

    params_base:: iterator:: reference

    Synopsis

                using reference = reference;
            
    [#]

    params_base:: iterator:: pointer

    Synopsis

                using pointer = reference;
            
    [#]

    params_base:: iterator:: difference_type

    Synopsis

                using difference_type = difference_type;
            
    [#]

    params_base:: iterator:: iterator_category

    Synopsis

                using iterator_category = std::bidirectional_iterator_tag;
            

    Overload set params_base:: iterator:: iterator

    Members

    iterator() = default;
    » more...

    constexpr
    iterator(iterator const&) = default;
    » more...
    [#]

    Function params_base:: iterator:: operator=

    Synopsis

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

    Overload set params_base:: iterator:: operator++

    Members

    iterator&
    operator++() noexcept;
    » more...

    iterator
    operator++(int) noexcept;
    » more...

    Overload set params_base:: iterator:: operator--

    Members

    iterator&
    operator--() noexcept;
    » more...

    iterator
    operator--(int) noexcept;
    » more...
    [#]

    Function params_base:: iterator:: operator*

    Synopsis

                reference
    operator*() const;
            
    [#]

    Function params_base:: iterator:: operator->

    Synopsis

                pointer
    operator->() const = delete;
            
    [#]

    Function params_base:: iterator:: operator==

    Synopsis

                bool
    operator==(iterator const& other) const noexcept;
            
    [#]

    Function params_base:: iterator:: operator!=

    Synopsis

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

    params_base:: const_iterator

    iterator

    Synopsis

                using const_iterator = iterator;
            
    [#]

    params_base:: value_type

    The value type

    Synopsis

                using value_type = param;
            

    Description

    Values of this type represent parameters whose strings retain unique ownership by making a copy.

    Example

    params_view::value_type qp( *url_view( "?first=John&last=Doe" ).params().find( "first" ) );
    [#]

    params_base:: reference

    The reference type

    Synopsis

                using reference = param;
            

    Description

    This is the type of value returned when iterators of the view are dereferenced.

    [#]

    params_base:: const_reference

    The reference type

    Synopsis

                using const_reference = param;
            

    Description

    This is the type of value returned when iterators of the view are dereferenced.

    [#]

    params_base:: size_type

    An unsigned integer type to represent sizes.

    Synopsis

                using size_type = std::size_t;
            
    [#]

    params_base:: difference_type

    A signed integer type used to represent differences.

    Synopsis

                using difference_type = std::ptrdiff_t;
            
    [#]

    Function params_base:: max_size

    Return the maximum number of characters possible

    Synopsis

                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.

    Exception Safety

    Throws nothing.

    [#]

    Function params_base:: buffer

    Return the referenced character buffer.

    Synopsis

                pct_string_view
    buffer() const noexcept;
            

    Description

    This function returns the character buffer referenced by the view. The returned string may contain percent escapes.

    Example

    assert( url_view( "?first=John&last=Doe" ).params().buffer() == "?first=John&last=Doe" );

    Complexity

    Constant.

    Exception Safety

    Throws nothing.

    [#]

    Function params_base:: empty

    Return true if there are no params

    Synopsis

                bool
    empty() const noexcept;
            

    Description

    Example

    assert( ! url_view( "?key=value" ).params().empty() );

    Complexity

    Constant.

    Exception Safety

    Throws nothing.

    [#]

    Function params_base:: size

    Return the number of params

    Synopsis

                std::size_t
    size() const noexcept;
            

    Description

    Example

    assert( url_view( "?key=value").params().size() == 1 );

    Complexity

    Constant.

    Exception Safety

    Throws nothing.

    [#]

    Function params_base:: begin

    Return an iterator to the beginning

    Synopsis

                iterator
    begin() const noexcept;
            

    Description

    Complexity

    Linear in the size of the first param.

    Exception Safety

    Throws nothing.

    [#]

    Function params_base:: end

    Return an iterator to the end

    Synopsis

                iterator
    end() const noexcept;
            

    Description

    Complexity

    Constant.

    Exception Safety

    Throws nothing.

    [#]

    Function params_base:: contains

    Return true if a matching key exists

    Synopsis

                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.

    Example

    assert( url_view( "?first=John&last=Doe" ).params().contains( "first" ) );

    Complexity

    Linear in `this->buffer().size()`.

    Exception Safety

    Throws nothing.

    [#]

    Function params_base:: count

    Return the number of matching keys

    Synopsis

                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.

    Example

    assert( url_view( "?first=John&last=Doe" ).params().count( "first" ) == 1 );

    Complexity

    Linear in `this->buffer().size()`.

    Exception Safety

    Throws nothing.

    Overload set params_base:: find

    Members

    Find a matching key

    iterator
    find(
        core::string_view key,
        ignore_case_param ic = = {}) const noexcept;
    » more...

    Find a matching key

    iterator
    find(
        iterator from,
        core::string_view key,
        ignore_case_param ic = = {}) const noexcept;
    » more...

    Overload set params_base:: find_last

    Members

    Find a matching key

    iterator
    find_last(
        core::string_view key,
        ignore_case_param ic = = {}) const noexcept;
    » more...

    Find a matching key

    iterator
    find_last(
        iterator before,
        core::string_view key,
        ignore_case_param ic = = {}) const noexcept;
    » more...
    [#]

    Class params_view

    A view representing query parameters in a URL

    Synopsis

                class params_view
        : public params_base;
            

    Types

    Types

    Member Functions

    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.

    Example

    url_view u( "?first=John&last=Doe" ); params_view p = u.params();

    Percent escapes in strings returned when dereferencing iterators are automatically decoded.

    Iterator Invalidation

    Changes to the underlying character buffer can invalidate iterators which reference it.

    Overload set params_view:: params_view

    Members

    Constructor

    params_view() = default;
    » more...

    Constructor

    constexpr
    params_view(params_view const& other) = default;
    » more...

    Constructor

    params_view(
        params_view const& other,
        encoding_opts opt) noexcept;
    » more...

    Constructor

    params_view(core::string_view s);
    » more...

    Constructor

    params_view(
        core::string_view s,
        encoding_opts opt);
    » more...
    [#]

    Function params_view:: operator=

    Assignment

    Synopsis

                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.

    Postconditions

    this->buffer().data() == other.buffer().data()

    Complexity

    Constant

    Exception Safety

    Throws nothing

    [#]

    Class params_encoded_view

    A view representing query parameters in a URL

    Synopsis

                class params_encoded_view
        : public params_encoded_base;
            

    Types

    Types

    Member Functions

    Friends

    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.

    Example

    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.

    Iterator Invalidation

    Changes to the underlying character buffer can invalidate iterators which reference it.

    Overload set params_encoded_view:: params_encoded_view

    Members

    Constructor

    constexpr
    params_encoded_view() = default;
    » more...

    Constructor

    constexpr
    params_encoded_view(params_encoded_view const& other) = default;
    » more...

    Constructor

    params_encoded_view(core::string_view s);
    » more...
    [#]

    Function params_encoded_view:: operator=

    Assignment

    Synopsis

                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.

    Postconditions

    this->buffer().data() == other.buffer().data()

    Complexity

    Constant

    Exception Safety

    Throws nothing

    [#]

    Function params_encoded_view:: operator params_view

    Conversion

    Synopsis

                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.

    Example

    params_view qp = parse_path( "/path/to/file.txt" ).value();

    Postconditions

    params_view( *this ).buffer().data() == this->buffer().data()

    Complexity

    Constant

    Exception Safety

    Throws nothing

    [#]

    Friend parse_query

    Synopsis

                friend
    system::result
    parse_query(core::string_view s) noexcept;
            
    [#]

    Function parse_query

    Parse a string and return an encoded params view

    Synopsis

                system::result
    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.

    BNF

    Exception Safety

    No-throw guarantee.

    Specification

    [#]

    Class url_base

    Common functionality for containers

    Synopsis

                class url_base
        : public url_view_base;
            

    Member Functions

    Friends

    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:

    Containers

  • url
  • url_view
  • static_url
  • Functions

  • parse_absolute_uri
  • parse_origin_form
  • parse_relative_ref
  • parse_uri
  • parse_uri_reference
  • [#]

    Function url_base:: c_str

    Return the url as a null-terminated string

    Synopsis

                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.

    Example

    assert( std::strlen( url( "http://www.example.com" ).c_str() ) == 22 );

    Complexity

    Constant.

    Exception Safety

    Throws nothing.

    [#]

    Function url_base:: capacity

    Return the number of characters that can be stored without reallocating

    Synopsis

                std::size_t
    capacity() const noexcept;
            

    Description

    This does not include the null terminator, which is always present.

    Complexity

    Constant.

    Exception Safety

    Throws nothing.

    [#]

    Function url_base:: clear

    Clear the contents while preserving the capacity

    Synopsis

                void
    clear() noexcept;
            

    Description

    Postconditions

    this->empty() == true

    Complexity

    Constant.

    Exception Safety

    No-throw guarantee.

    [#]

    Function url_base:: reserve

    Adjust the capacity without changing the size

    Synopsis

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

    Exception Safety

    Strong guarantee. Calls to allocate may throw.

    [#]

    Function url_base:: set_scheme

    Set the scheme

    Synopsis

                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.

    Example

    assert( url( "http://www.example.com" ).set_scheme( "https" ).scheme_id() == scheme::https );

    Complexity

    Linear in `this->size() + s.size()`.

    Exception Safety

    Strong guarantee. Calls to allocate may throw. Exceptions thrown on invalid input.

    BNF

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

    Specification

  • 3.1. Scheme (rfc3986)
  • [#]

    Function url_base:: set_scheme_id

    Synopsis

                url_base&
    set_scheme_id(scheme id);
            
    [#]

    Function url_base:: remove_scheme

    Remove the scheme

    Synopsis

                url_base&
    remove_scheme();
            

    Description

    This function removes the scheme if it is present.

    Example

    assert( url("http://www.example.com/index.htm" ).remove_scheme().buffer() == "//www.example.com/index.htm" );

    Postconditions

    this->has_scheme() == false && this->scheme_id() == scheme::none

    Complexity

    Linear in `this->size()`.

    Exception Safety

    Throws nothing.

    BNF

    URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ]

    Specification

  • 3.1. Scheme (rfc3986)
  • [#]

    Function url_base:: set_encoded_authority

    Set the authority

    Synopsis

                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.

    Example

    assert( url().set_encoded_authority( "My%20Computer" ).has_authority() );

    Exception Safety

    Strong guarantee. Calls to allocate may throw. Exceptions thrown on invalid input.

    BNF

    authority = [ userinfo "@" ] host [ ":" port ] userinfo = *( unreserved / pct-encoded / sub-delims / ":" ) host = IP-literal / IPv4address / reg-name port = *DIGIT

    Specification

  • 3.2. Authority (rfc3986)
  • [#]

    Function url_base:: remove_authority

    Remove the authority

    Synopsis

                url_base&
    remove_authority();
            

    Description

    This function removes the authority, which includes the userinfo, host, and a port if present.

    Example

    assert( url( "http://example.com/echo.cgi" ).remove_authority().buffer() == "http:/echo.cgi" );

    Postconditions

    this->has_authority() == false && this->has_userinfo() == false && this->has_port() == false

    Complexity

    Linear in `this->size()`.

    Exception Safety

    Throws nothing.

    BNF

    authority = [ userinfo "@" ] host [ ":" port ] userinfo = *( unreserved / pct-encoded / sub-delims / ":" ) host = IP-literal / IPv4address / reg-name port = *DIGIT

    Specification

  • 3.2. Authority (rfc3986)
  • [#]

    Function url_base:: set_userinfo

    Set the userinfo

    Synopsis

                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.

    Example

    assert( url( "http://example.com" ).set_userinfo( "user:pass" ).encoded_user() == "user" );

    Complexity

    Linear in `this->size() + s.size()`.

    Exception Safety

    Strong guarantee. Calls to allocate may throw.

    BNF

    userinfo = [ [ user ] [ ':' password ] ] user = *( unreserved / pct-encoded / sub-delims ) password = *( unreserved / pct-encoded / sub-delims / ":" )

    Specification

  • 3.2.1. User Information (rfc3986)
  • [#]

    Function url_base:: set_encoded_userinfo

    Set the userinfo.

    Synopsis

                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.

    Example

    assert( url( "http://example.com" ).set_encoded_userinfo( "john%20doe" ).user() == "john doe" );

    Complexity

    Linear in `this->size() + s.size()`.

    Exception Safety

    Strong guarantee. Calls to allocate may throw. Exceptions thrown on invalid input.

    BNF

    userinfo = [ [ user ] [ ':' password ] ] user = *( unreserved / pct-encoded / sub-delims ) password = *( unreserved / pct-encoded / sub-delims / ":" )

    Specification

  • 3.2.1. User Information (rfc3986)
  • [#]

    Function url_base:: remove_userinfo

    Remove the userinfo

    Synopsis

                url_base&
    remove_userinfo() noexcept;
            

    Description

    This function removes the userinfo if present, without removing any authority.

    Example

    assert( url( "http://user@example.com" ).remove_userinfo().has_userinfo() == false );

    Postconditions

    this->has_userinfo() == false && this->encoded_userinfo().empty == true

    Complexity

    Linear in `this->size()`.

    Exception Safety

    Throws nothing.

    BNF

    userinfo = [ [ user ] [ ':' password ] ] user = *( unreserved / pct-encoded / sub-delims ) password = *( unreserved / pct-encoded / sub-delims / ":" )

    Specification

  • 3.2.1. User Information (rfc3986)
  • [#]

    Function url_base:: set_user

    Set the user

    Synopsis

                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.

    Example

    assert( url().set_user("john doe").encoded_userinfo() == "john%20doe" );

    Postconditions

    this->has_authority() == true && this->has_userinfo() == true

    Complexity

    Linear in `this->size() + s.size()`.

    Exception Safety

    Strong guarantee. Calls to allocate may throw.

    BNF

    userinfo = [ [ user ] [ ':' password ] ] user = *( unreserved / pct-encoded / sub-delims ) password = *( unreserved / pct-encoded / sub-delims / ":" )

    Specification

  • 3.2.1. User Information (rfc3986)
  • [#]

    Function url_base:: set_encoded_user

    Set the user

    Synopsis

                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.

    Example

    assert( url().set_encoded_user("john%20doe").userinfo() == "john doe" );

    Postconditions

    this->has_authority() == true && this->has_userinfo() == true

    Complexity

    Linear in `this->size() + s.size()`.

    Exception Safety

    Strong guarantee. Calls to allocate may throw.

    BNF

    userinfo = [ [ user ] [ ':' password ] ] user = *( unreserved / pct-encoded / sub-delims ) password = *( unreserved / pct-encoded / sub-delims / ":" )

    Specification

  • 3.2.1. User Information (rfc3986)
  • [#]

    Function url_base:: set_password

    Set the password.

    Synopsis

                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.

    Example

    assert( url("http://user@example.com").set_password( "pass" ).encoded_userinfo() == "user:pass" );

    Postconditions

    this->has_password() == true && this->password() == s

    Exception Safety

    Strong guarantee. Calls to allocate may throw.

    BNF

    userinfo = [ [ user ] [ ':' password ] ] user = *( unreserved / pct-encoded / sub-delims ) password = *( unreserved / pct-encoded / sub-delims / ":" )

    Specification

  • 3.2.1. User Information (rfc3986)
  • [#]

    Function url_base:: set_encoded_password

    Set the password.

    Synopsis

                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.

    Example

    assert( url("http://user@example.com").set_encoded_password( "pass" ).encoded_userinfo() == "user:pass" );

    Postconditions

    this->has_password() == true

    Exception Safety

    Strong guarantee. Calls to allocate may throw.

    BNF

    userinfo = [ [ user ] [ ':' password ] ] user = *( unreserved / pct-encoded / sub-delims ) password = *( unreserved / pct-encoded / sub-delims / ":" )

    Specification

  • 3.2.1. User Information (rfc3986)
  • [#]

    Function url_base:: remove_password

    Remove the password

    Synopsis

                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.

    Example

    assert( url( "http://user:pass@example.com" ).remove_password().authority().buffer() == "user@example.com" );

    Postconditions

    this->has_password() == false && this->encoded_password().empty() == true

    Complexity

    Linear in `this->size()`.

    Exception Safety

    Throws nothing.

    BNF

    userinfo = [ [ user ] [ ':' password ] ] user = *( unreserved / pct-encoded / sub-delims ) password = *( unreserved / pct-encoded / sub-delims / ":" )

    Specification

  • 3.2.1. User Information (rfc3986)
  • [#]

    Function url_base:: set_host

    Set the host

    Synopsis

                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.

    Example

    assert( url( "http://www.example.com" ).set_host( "127.0.0.1" ).buffer() == "http://127.0.0.1" );

    Postconditions

    this->has_authority() == true

    Complexity

    Linear in `this->size() + s.size()`.

    Exception Safety

    Strong guarantee. Calls to allocate may throw.

    BNF

    host = IP-literal / IPv4address / reg-name IP-literal = "[" ( IPv6address / IPvFuture ) "]" reg-name = *( unreserved / pct-encoded / "-" / ".")

    Specification

  • IPv4 (Wikipedia)
  • IP Version 6 Addressing Architecture (rfc4291)
  • 3.2.2. Host (rfc3986)
  • [#]

    Function url_base:: set_encoded_host

    Set the host

    Synopsis

                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.

    Example

    assert( url( "http://www.example.com" ).set_host( "127.0.0.1" ).buffer() == "http://127.0.0.1" );

    Postconditions

    this->has_authority() == true

    Complexity

    Linear in `this->size() + s.size()`.

    Exception Safety

    Strong guarantee. Calls to allocate may throw. Exceptions thrown on invalid input.

    BNF

    host = IP-literal / IPv4address / reg-name IP-literal = "[" ( IPv6address / IPvFuture ) "]" reg-name = *( unreserved / pct-encoded / "-" / ".")

    Specification

  • IPv4 (Wikipedia)
  • IP Version 6 Addressing Architecture (rfc4291)
  • 3.2.2. Host (rfc3986)
  • [#]

    Function url_base:: set_host_address

    Set the host to an address

    Synopsis

                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.

    Example

    assert( url( "http://www.example.com" ).set_host_address( "127.0.0.1" ).buffer() == "http://127.0.0.1" );

    Postconditions

    this->has_authority() == true

    Complexity

    Linear in `s.size()`.

    Exception Safety

    Strong guarantee. Calls to allocate may throw.

    BNF

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

    Specification

  • IPv4 (Wikipedia)
  • IP Version 6 Addressing Architecture (rfc4291)
  • 3.2.2. Host (rfc3986)
  • [#]

    Function url_base:: set_encoded_host_address

    Set the host to an address

    Synopsis

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

    Example

    assert( url( "http://www.example.com" ).set_host( "127.0.0.1" ).buffer() == "http://127.0.0.1" );

    Postconditions

    this->has_authority() == true

    Complexity

    Linear in `this->size() + s.size()`.

    Exception Safety

    Strong guarantee. Calls to allocate may throw. Exceptions thrown on invalid input.

    BNF

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

    Specification

  • IPv4 (Wikipedia)
  • IP Version 6 Addressing Architecture (rfc4291)
  • 3.2.2. Host (rfc3986)
  • [#]

    Function url_base:: set_host_ipv4

    Set the host to an address

    Synopsis

                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 .

    Example

    assert( url("http://www.example.com").set_host_ipv4( ipv4_address( "127.0.0.1" ) ).buffer() == "http://127.0.0.1" );

    Complexity

    Linear in `this->size()`.

    Postconditions

    this->has_authority() == true && this->host_ipv4_address() == addr && this->host_type() == host_type::ipv4

    Exception Safety

    Strong guarantee. Calls to allocate may throw.

    BNF

    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

    Specification

  • IPv4 (Wikipedia)
  • 3.2.2. Host (rfc3986)
  • [#]

    Function url_base:: set_host_ipv6

    Set the host to an address

    Synopsis

                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 .

    Example

    assert( url().set_host_ipv6( ipv6_address( "1::6:c0a8:1" ) ).authority().buffer() == "[1::6:c0a8:1]" );

    Postconditions

    this->has_authority() == true && this->host_ipv6_address() == addr && this->host_type() == host_type::ipv6

    Complexity

    Linear in `this->size()`.

    Exception Safety

    Strong guarantee. Calls to allocate may throw.

    BNF

    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

    Specification

  • IP Version 6 Addressing Architecture (rfc4291)
  • 3.2.2. Host (rfc3986)
  • [#]

    Function url_base:: set_host_ipvfuture

    Set the host to an address

    Synopsis

                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 .

    Example

    assert( url().set_host_ipvfuture( "v42.bis" ).buffer() == "//[v42.bis]" );

    Complexity

    Linear in `this->size() + s.size()`.

    Postconditions

    this->has_authority() == true && this->host_ipvfuture) == s && this->host_type() == host_type::ipvfuture

    Exception Safety

    Strong guarantee. Calls to allocate may throw. Exceptions thrown on invalid input.

    BNF

    IPvFuture = "v" 1*HEXDIG "." 1*( unreserved / sub-delims / ":" )

    Specification

  • 3.2.2. Host (rfc3986)
  • [#]

    Function url_base:: set_host_name

    Set the host to a name

    Synopsis

                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 .

    Example

    assert( url( "http://www.example.com/index.htm").set_host_name( "localhost" ).host_address() == "localhost" );

    Postconditions

    this->has_authority() == true && this->host_ipv6_address() == addr && this->host_type() == host_type::name

    Exception Safety

    Strong guarantee. Calls to allocate may throw.

    BNF

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

    Specification

  • 3.2.2. Host (rfc3986)
  • [#]

    Function url_base:: set_encoded_host_name

    Set the host to a name

    Synopsis

                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 .

    Example

    assert( url( "http://www.example.com/index.htm").set_encoded_host_name( "localhost" ).host_address() == "localhost" );

    Postconditions

    this->has_authority() == true && this->host_ipv6_address() == addr && this->host_type() == host_type::name

    Exception Safety

    Strong guarantee. Calls to allocate may throw. Exceptions thrown on invalid input.

    BNF

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

    Specification

  • 3.2.2. Host (rfc3986)
  • [#]

    Function url_base:: set_port_number

    Set the port

    Synopsis

                url_base&
    set_port_number(std::uint16_t n);
            

    Description

    The port is set to the specified integer.

    Example

    assert( url( "http://www.example.com" ).set_port_number( 8080 ).authority().buffer() == "www.example.com:8080" );

    Postconditions

    this->has_authority() == true && this->has_port() == true && this->port_number() == n

    Complexity

    Linear in `this->size()`.

    Exception Safety

    Strong guarantee. Calls to allocate may throw.

    BNF

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

    Specification

  • 3.2.3. Port (rfc3986)
  • [#]

    Function url_base:: set_port

    Set the port

    Synopsis

                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.

    Example

    assert( url( "http://www.example.com" ).set_port( "8080" ).authority().buffer() == "www.example.com:8080" );

    Postconditions

    this->has_port() == true && this->port_number() == n && this->port() == std::to_string(n)

    Exception Safety

    Strong guarantee. Calls to allocate may throw. Exceptions thrown on invalid input.

    BNF

    port = *DIGIT

    Specification

  • 3.2.3. Port (rfc3986)
  • [#]

    Function url_base:: remove_port

    Remove the port

    Synopsis

                url_base&
    remove_port() noexcept;
            

    Description

    If a port exists, it is removed. The rest of the authority is unchanged.

    Example

    assert( url( "http://www.example.com:80" ).remove_port().authority().buffer() == "www.example.com" );

    Postconditions

    this->has_port() == false && this->port_number() == 0 && this->port() == ""

    Complexity

    Linear in `this->size()`.

    Exception Safety

    Throws nothing.

    BNF

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

    Specification

  • 3.2.3. Port (rfc3986)
  • [#]

    Function url_base:: set_path_absolute

    Set if the path is absolute

    Synopsis

                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.

    Example

    url u( "path/to/file.txt" ); assert( u.set_path_absolute( true ) ); assert( u.buffer() == "/path/to/file.txt" );

    Postconditions

    this->is_path_absolute() == true && this->encoded_path().front() == '/'

    Complexity

    Linear in `this->size()`.

    BNF

    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

    Specification

  • 3.3. Path (rfc3986)
  • [#]

    Function url_base:: set_path

    Set the path.

    Synopsis

                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.

    Example

    url u( "http://www.example.com" ); u.set_path( "path/to/file.txt" ); assert( u.path() == "/path/to/file.txt" );

    Complexity

    Linear in `this->size() + s.size()`.

    Exception Safety

    Strong guarantee. Calls to allocate may throw.

    BNF

    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

    Specification

  • 3.3. Path (rfc3986)
  • [#]

    Function url_base:: set_encoded_path

    Set the path.

    Synopsis

                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.

    Example

    url u( "http://www.example.com" ); u.set_encoded_path( "path/to/file.txt" ); assert( u.encoded_path() == "/path/to/file.txt" );

    Complexity

    Linear in `this->size() + s.size()`.

    Exception Safety

    Strong guarantee. Calls to allocate may throw. Exceptions thrown on invalid input.

    BNF

    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

    Specification

  • 3.3. Path (rfc3986)
  • Overload set url_base:: segments

    Members

    Return the path as a container of segments

    segments_ref
    segments() noexcept;
    » more...

    Return the path as a container of segments

    segments_view
    segments() const noexcept;
    » more...

    Overload set url_base:: encoded_segments

    Members

    Return the path as a container of segments

    segments_encoded_ref
    encoded_segments() noexcept;
    » more...

    Return the path as a container of segments

    segments_encoded_view
    encoded_segments() const noexcept;
    » more...
    [#]

    Function url_base:: set_query

    Set the query

    Synopsis

                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.

    Example

    assert( url( "http://example.com" ).set_query( "id=42" ).query() == "id=42" );

    Postconditions

    this->has_query() == true && this->query() == s

    Exception Safety

    Strong guarantee. Calls to allocate may throw.

    BNF

    query = *( pchar / "/" / "?" ) query-param = key [ "=" value ] query-params = [ query-param ] *( "&" query-param )

    Specification

  • 3.4. Query (rfc3986)
  • Query string (Wikipedia)
  • [#]

    Function url_base:: set_encoded_query

    Set the query

    Synopsis

                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.

    Example

    assert( url( "http://example.com" ).set_encoded_query( "id=42" ).encoded_query() == "id=42" );

    Postconditions

    this->has_query() == true && this->query() == decode_view( s );

    Exception Safety

    Strong guarantee. Calls to allocate may throw. Exceptions thrown on invalid input.

    BNF

    query = *( pchar / "/" / "?" ) query-param = key [ "=" value ] query-params = [ query-param ] *( "&" query-param )

    Specification

  • 3.4. Query (rfc3986)
  • Query string (Wikipedia)
  • Overload set url_base:: params

    Members

    Return the query as a container of parameters

    params_ref
    params() noexcept;
    » more...

    url_view_base::params

    params_view
    params() const noexcept;
    » more...

    Return the query as a container of parameters

    params_ref
    params(encoding_opts opt) noexcept;
    » more...

    Overload set url_base:: encoded_params

    Members

    Return the query as a container of parameters

    params_encoded_view
    encoded_params() const noexcept;
    » more...

    Return the query as a container of parameters

    params_encoded_ref
    encoded_params() noexcept;
    » more...
    [#]

    Function url_base:: set_params

    Set the query params

    Synopsis

                url_base&
    set_params(std::initializer_list ps) 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.

    Example

    assert( url( "http://example.com" ).set_params( {"id", "42"} ).query() == "id=42" );

    Postconditions

    this->has_query() == true

    Exception Safety

    Strong guarantee. Calls to allocate may throw.

    Complexity

    Linear.

    BNF

    query = *( pchar / "/" / "?" ) query-param = key [ "=" value ] query-params = [ query-param ] *( "&" query-param )

    Specification

  • ://en.wikipedia.org/wiki/Query_string" >Query string (Wikipedia)
  • [#]

    Function url_base:: set_encoded_params

    Set the query params

    Synopsis

                url_base&
    set_encoded_params(std::initializer_list 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.

    Example

    assert( url( "http://example.com" ).set_encoded_params( {"id", "42"} ).encoded_query() == "id=42" );

    Postconditions

    this->has_query() == true

    Complexity

    Linear.

    Exception Safety

    Strong guarantee. Calls to allocate may throw. Exceptions thrown on invalid input.

    BNF

    query = *( pchar / "/" / "?" ) query-param = key [ "=" value ] query-params = [ query-param ] *( "&" query-param )

    Specification

  • 3.4. Query (rfc3986)
  • Query string (Wikipedia)
  • [#]

    Function url_base:: remove_query

    Remove the query

    Synopsis

                url_base&
    remove_query() noexcept;
            

    Description

    If a query is present, it is removed. An empty query is distinct from having no query.

    Example

    assert( url( "http://www.example.com?id=42" ).remove_query().buffer() == "http://www.example.com" );

    Postconditions

    this->has_query() == false && this->params().empty()

    Exception Safety

    Throws nothing.

    BNF

    query = *( pchar / "/" / "?" ) query-param = key [ "=" value ] query-params = [ query-param ] *( "&" query-param )

    Specification

  • 3.4. Query (rfc3986)
  • Query string (Wikipedia)
  • [#]

    Function url_base:: remove_fragment

    Remove the fragment

    Synopsis

                url_base&
    remove_fragment() noexcept;
            

    Description

    This function removes the fragment. An empty fragment is distinct from having no fragment.

    Example

    assert( url( "?first=john&last=doe#anchor" ).remove_fragment().buffer() == "?first=john&last=doe" );

    Postconditions

    this->has_fragment() == false && this->encoded_fragment() == ""

    Complexity

    Constant.

    Exception Safety

    Throws nothing.

    BNF

    fragment = *( pchar / "/" / "?" )

    Specification

  • 3.5. Fragment
  • [#]

    Function url_base:: set_fragment

    Set the fragment.

    Synopsis

                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.

    Example

    assert( url("?first=john&last=doe" ).set_encoded_fragment( "john doe" ).encoded_fragment() == "john%20doe" );

    Postconditions

    this->has_fragment() == true && this->fragment() == s

    Complexity

    Linear in `this->size() + s.size()`.

    Exception Safety

    Strong guarantee. Calls to allocate may throw.

    BNF

    fragment = *( pchar / "/" / "?" )

    Specification

  • 3.5. Fragment
  • [#]

    Function url_base:: set_encoded_fragment

    Set the fragment.

    Synopsis

                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.

    Example

    assert( url("?first=john&last=doe" ).set_encoded_fragment( "john%2Ddoe" ).fragment() == "john-doe" );

    Postconditions

    this->has_fragment() == true && this->fragment() == decode_view( s )

    Complexity

    Linear in `this->size() + s.size()`.

    Exception Safety

    Strong guarantee. Calls to allocate may throw. Exceptions thrown on invalid input.

    BNF

    fragment = *( pchar / "/" / "?" )

    Specification

  • 3.5. Fragment
  • [#]

    Function url_base:: remove_origin

    Remove the origin component

    Synopsis

                url_base&
    remove_origin();
            

    Description

    This function removes the origin, which consists of the scheme and authority.

    Example

    assert( url( "http://www.example.com/index.htm" ).remove_origin().buffer() == "/index.htm" );

    Postconditions

    this->scheme_id() == scheme::none && this->has_authority() == false

    Complexity

    Linear in `this->size()`.

    Exception Safety

    Throws nothing.

    [#]

    Function url_base:: normalize

    Normalize the URL components

    Synopsis

                url_base&
    normalize();
            

    Description

    Applies Syntax-based normalization to all components of the URL.

    Exception Safety

    Strong guarantee. Calls to allocate may throw.

    Specification

  • 6.2.2 Syntax-Based Normalization (rfc3986)
  • [#]

    Function url_base:: normalize_scheme

    Normalize the URL scheme

    Synopsis

                url_base&
    normalize_scheme();
            

    Description

    Applies Syntax-based normalization to the URL scheme.

    The scheme is normalized to lowercase.

    Exception Safety

    Strong guarantee. Calls to allocate may throw.

    Specification

  • 6.2.2 Syntax-Based Normalization (rfc3986)
  • [#]

    Function url_base:: normalize_authority

    Normalize the URL authority

    Synopsis

                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.

    Exception Safety

    Strong guarantee. Calls to allocate may throw.

    Specification

  • 6.2.2 Syntax-Based Normalization (rfc3986)
  • [#]

    Function url_base:: normalize_path

    Normalize the URL path

    Synopsis

                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.

    Exception Safety

    Strong guarantee. Calls to allocate may throw.

    Specification

  • 6.2.2 Syntax-Based Normalization (rfc3986)
  • [#]

    Function url_base:: normalize_query

    Normalize the URL query

    Synopsis

                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.

    Exception Safety

    Strong guarantee. Calls to allocate may throw.

    Specification

  • 6.2.2 Syntax-Based Normalization (rfc3986)
  • [#]

    Function url_base:: normalize_fragment

    Normalize the URL fragment

    Synopsis

                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.

    Exception Safety

    Strong guarantee. Calls to allocate may throw.

    Specification

  • 6.2.2 Syntax-Based Normalization (rfc3986)
  • [#]

    Function url_base:: resolve

    Resolve a URL reference against this base URL

    Synopsis

                system::result
    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 .

    Example

    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" );

    BNF

    absolute-URI = scheme ":" hier-part [ "?" query ]

    Exception Safety

    Basic guarantee. Calls to allocate may throw.

    Specification

    5. Reference Resolution (rfc3986)

    [#]

    Friend resolve

    Synopsis

                friend
    system::result
    resolve(
        url_view_base const& base,
        url_view_base const& ref,
        url_base& dest);
            
    [#]

    Class params_encoded_ref

    A view representing query parameters in a URL

    Synopsis

                class params_encoded_ref
        : public params_encoded_base;
            

    Types

    Types

    Member Functions

    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.

    Example

    url u( "?first=John&last=Doe" ); params_encoded_ref 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.

    Iterator Invalidation

    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()`).
  • [#]

    Function params_encoded_ref:: params_encoded_ref

    Constructor

    Synopsis

                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.

    Postconditions

    &this->url() == &other.url();

    Complexity

    Constant.

    Exception Safety

    Throws nothing.

    Overload set params_encoded_ref:: operator=

    Members

    Assignment

    params_encoded_ref&
    operator=(params_encoded_ref const& other);
    » more...

    Assignment

    params_encoded_ref&
    operator=(std::initializer_list init);
    » more...
    [#]

    Function params_encoded_ref:: operator params_encoded_view

    Conversion

    Synopsis

                operator params_encoded_view() const noexcept;
            

    Description

    Complexity

    Constant.

    Exception Safety

    Throws nothing.

    [#]

    Function params_encoded_ref:: url

    Return the referenced url

    Synopsis

                url_base&
    url() const noexcept;
            

    Description

    This function returns the url referenced by the view.

    Example

    url u( "?key=value" ); assert( &u.encoded_params().url() == &u );

    Exception Safety

    Throws nothing.
    [#]

    Function params_encoded_ref:: clear

    Clear the contents of the container

    Synopsis

                void
    clear() noexcept;
            

    Description

    All iterators are invalidated.

    Effects

    this->url().remove_query();

    Postconditions

    this->empty() == true && this->url().has_query() == false

    Complexity

    Constant.

    Exception Safety

    Throws nothing.

    Overload set params_encoded_ref:: assign

    Members

    Assign params

    void
    assign(std::initializer_list init);
    » more...

    Assign params

    template
    void
    assign(
        FwdIt first,
        FwdIt last);
    » more...

    Overload set params_encoded_ref:: append

    Members

    Append params

    iterator
    append(param_pct_view const& p);
    » more...

    Append params

    iterator
    append(std::initializer_list init);
    » more...

    Append params

    template
    iterator
    append(
        FwdIt first,
        FwdIt last);
    » more...

    Overload set params_encoded_ref:: insert

    Members

    Insert params

    iterator
    insert(
        iterator before,
        param_pct_view const& p);
    » more...

    Insert params

    iterator
    insert(
        iterator before,
        std::initializer_list init);
    » more...

    Insert params

    template
    iterator
    insert(
        iterator before,
        FwdIt first,
        FwdIt last);
    » more...

    Overload set params_encoded_ref:: erase

    Members

    Erase params

    iterator
    erase(iterator pos) noexcept;
    » more...

    Erase params

    iterator
    erase(
        iterator first,
        iterator last) noexcept;
    » more...

    Erase params

    std::size_t
    erase(
        pct_string_view key,
        ignore_case_param ic = = {}) noexcept;
    » more...

    Overload set params_encoded_ref:: replace

    Members

    Replace params

    iterator
    replace(
        iterator pos,
        param_pct_view const& p);
    » more...

    Replace params

    iterator
    replace(
        iterator from,
        iterator to,
        std::initializer_list init);
    » more...

    Replace params

    template
    iterator
    replace(
        iterator from,
        iterator to,
        FwdIt first,
        FwdIt last);
    » more...
    [#]

    Function params_encoded_ref:: unset

    Remove the value on an element

    Synopsis

                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.

    Example

    url u( "?first=John&last=Doe" ); u.encoded_params().unset( u.encoded_params().begin() ); assert( u.encoded_query() == "first&last=Doe" );

    Complexity

    Linear in `this->url().encoded_query().size()`.

    Exception Safety

    Throws nothing.

    Overload set params_encoded_ref:: set

    Members

    Set a value

    iterator
    set(
        iterator pos,
        pct_string_view value);
    » more...

    Set a value

    iterator
    set(
        pct_string_view key,
        pct_string_view value,
        ignore_case_param ic = = {});
    » more...
    [#]

    Class segments_encoded_ref

    A view representing path segments in a URL

    Synopsis

                class segments_encoded_ref
        : public segments_encoded_base;
            

    Types

    Types

    Member Functions

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

    The view is modifiable; calling non-const members causes changes to the referenced url.

    Example

    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.

    Iterator Invalidation

    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()`).
  • [#]

    Function segments_encoded_ref:: segments_encoded_ref

    Constructor

    Synopsis

                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.

    Postconditions

    &this->url() == &other.url();

    Complexity

    Constant.

    Exception Safety

    Throws nothing.

    Overload set segments_encoded_ref:: operator=

    Members

    Assignment

    segments_encoded_ref&
    operator=(segments_encoded_ref const& other);
    » more...

    segments_encoded_ref&
    operator=(segments_encoded_view const& other);
    » more...

    Assignment

    segments_encoded_ref&
    operator=(std::initializer_list init);
    » more...
    [#]

    Function segments_encoded_ref:: operator segments_encoded_view

    Conversion

    Synopsis

                operator segments_encoded_view() const noexcept;
            
    [#]

    Function segments_encoded_ref:: url

    Return the referenced url

    Synopsis

                url_base&
    url() const noexcept;
            

    Description

    This function returns the url referenced by the view.

    Example

    url u( "/path/to/file.txt" ); assert( &u.encoded_segments().url() == &u );

    Exception Safety

    Throws nothing.

    [#]

    Function segments_encoded_ref:: clear

    Clear the contents of the container

    Synopsis

                void
    clear() noexcept;
            

    Description

    All iterators are invalidated.

    Effects

    this->url().set_encoded_path( "" );

    Postconditions

    this->empty() == true

    Complexity

    Linear in `this->url().encoded_query().size() + this->url().encoded_fragment().size()`.

    Exception Safety

    Throws nothing.

    Overload set segments_encoded_ref:: assign

    Members

    Assign segments

    void
    assign(std::initializer_list init);
    » more...

    Assign segments

    template
    void
    assign(
        FwdIt first,
        FwdIt last);
    » more...

    Overload set segments_encoded_ref:: insert

    Members

    Insert segments

    iterator
    insert(
        iterator before,
        pct_string_view s);
    » more...

    Insert segments

    iterator
    insert(
        iterator before,
        std::initializer_list init);
    » more...

    Insert segments

    template
    iterator
    insert(
        iterator before,
        FwdIt first,
        FwdIt last);
    » more...

    Overload set segments_encoded_ref:: erase

    Members

    Erase segments

    iterator
    erase(iterator pos) noexcept;
    » more...

    Erase segments

    iterator
    erase(
        iterator first,
        iterator last) noexcept;
    » more...

    Overload set segments_encoded_ref:: replace

    Members

    Replace segments

    iterator
    replace(
        iterator pos,
        pct_string_view s);
    » more...

    Replace segments

    iterator
    replace(
        iterator from,
        iterator to,
        pct_string_view s);
    » more...

    Replace segments

    iterator
    replace(
        iterator from,
        iterator to,
        std::initializer_list init);
    » more...

    Replace segments

    template
    iterator
    replace(
        iterator from,
        iterator to,
        FwdIt first,
        FwdIt last);
    » more...
    [#]

    Function segments_encoded_ref:: push_back

    Append a segment

    Synopsis

                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.

    Postconditions

    this->back() == s

    Exception Safety

    Strong guarantee. Calls to allocate may throw. Exceptions thrown on invalid input.

    [#]

    Function segments_encoded_ref:: pop_back

    Remove the last segment

    Synopsis

                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.

    Preconditions

    not this->empty()

    Exception Safety

    Throws nothing.

    [#]

    Class segments_ref

    A view representing path segments in a URL

    Synopsis

                class segments_ref
        : public segments_base;
            

    Types

    Types

    Member Functions

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

    The view is modifiable; calling non-const members causes changes to the referenced url.

    Example

    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.

    Iterator Invalidation

    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()`).
  • [#]

    Function segments_ref:: segments_ref

    Constructor

    Synopsis

                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.

    Postconditions

    &this->url() == &other.url();

    Complexity

    Constant.

    Exception Safety

    Throws nothing.

    Overload set segments_ref:: operator=

    Members

    Assignment

    segments_ref&
    operator=(segments_ref const& other);
    » more...

    segments_ref&
    operator=(segments_view const& other);
    » more...

    Assignment

    segments_ref&
    operator=(std::initializer_list init);
    » more...
    [#]

    Function segments_ref:: operator segments_view

    Conversion

    Synopsis

                operator segments_view() const noexcept;
            
    [#]

    Function segments_ref:: url

    Return the referenced url

    Synopsis

                url_base&
    url() const noexcept;
            

    Description

    This function returns the url referenced by the view.

    Example

    url u( "/path/to/file.txt" ); assert( &u.segments().url() == &u );

    Exception Safety

    Throws nothing.

    [#]

    Function segments_ref:: clear

    Clear the contents of the container

    Synopsis

                void
    clear() noexcept;
            

    Description

    All iterators are invalidated.

    Effects

    this->url().set_encoded_path( "" );

    Postconditions

    this->empty() == true

    Complexity

    Linear in `this->url().encoded_query().size() + this->url().encoded_fragment().size()`.

    Exception Safety

    Throws nothing.

    Overload set segments_ref:: assign

    Members

    Assign segments

    void
    assign(std::initializer_list init);
    » more...

    Assign segments

    template
    void
    assign(
        FwdIt first,
        FwdIt last);
    » more...

    Overload set segments_ref:: insert

    Members

    Insert segments

    iterator
    insert(
        iterator before,
        core::string_view s);
    » more...

    Insert segments

    iterator
    insert(
        iterator before,
        std::initializer_list init);
    » more...

    Insert segments

    template
    iterator
    insert(
        iterator before,
        FwdIt first,
        FwdIt last);
    » more...

    Overload set segments_ref:: erase

    Members

    Erase segments

    iterator
    erase(iterator pos) noexcept;
    » more...

    Erase segments

    iterator
    erase(
        iterator first,
        iterator last) noexcept;
    » more...

    Overload set segments_ref:: replace

    Members

    Replace segments

    iterator
    replace(
        iterator pos,
        core::string_view s);
    » more...

    Replace segments

    iterator
    replace(
        iterator from,
        iterator to,
        core::string_view s);
    » more...

    Replace segments

    iterator
    replace(
        iterator from,
        iterator to,
        std::initializer_list init);
    » more...

    Replace segments

    template
    iterator
    replace(
        iterator from,
        iterator to,
        FwdIt first,
        FwdIt last);
    » more...
    [#]

    Function segments_ref:: push_back

    Append a segment

    Synopsis

                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.

    Postconditions

    this->back() == s

    Exception Safety

    Strong guarantee. Calls to allocate may throw.

    [#]

    Function segments_ref:: pop_back

    Remove the last segment

    Synopsis

                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.

    Preconditions

    not this->empty()

    Exception Safety

    Throws nothing.

    [#]

    Class url_view_base

    Common functionality for containers

    Synopsis

                class url_view_base;
            

    Member Functions

    Friends

    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:

    Containers

  • url
  • url_view
  • static_url
  • Functions

  • parse_absolute_uri
  • parse_origin_form
  • parse_relative_ref
  • parse_uri
  • parse_uri_reference
  • [#]

    Function url_view_base:: digest

    Synopsis

                std::size_t
    digest(std::size_t = 0) const noexcept;
            
    [#]

    Function url_view_base:: max_size

    Return the maximum number of characters possible

    Synopsis

                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.

    Complexity

    Constant.

    Exception Safety

    Throws nothing.

    [#]

    Function url_view_base:: size

    Return the number of characters in the url

    Synopsis

                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.

    Example

    assert( url_view( "file:///Program%20Files" ).size() == 23 );

    Complexity

    Constant.

    Exception Safety

    Throws nothing.

    [#]

    Function url_view_base:: empty

    Return true if the url is empty

    Synopsis

                bool
    empty() const noexcept;
            

    Description

    The empty string matches the relative-ref grammar.

    Example

    assert( url_view( "" ).empty() );

    Complexity

    Constant.

    Exception Safety

    Throws nothing.

    BNF

    relative-ref = relative-part [ "?" query ] [ "#" fragment ] relative-part = "//" authority path-abempty / path-absolute / path-noscheme / path-empty

    Specification

  • 4.2. Relative Reference (rfc3986)
  • [#]

    Function url_view_base:: data

    Return a pointer to the url's character buffer

    Synopsis

                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.

    Complexity

    Constant.

    Exception Safety

    Throws nothing.

    [#]

    Function url_view_base:: buffer

    Return the url string

    Synopsis

                core::string_view
    buffer() const noexcept;
            

    Description

    This function returns the entire url, which may contain percent escapes.

    Example

    assert( url_view( "http://www.example.com" ).buffer() == "http://www.example.com" );

    Complexity

    Constant.

    Exception Safety

    Throws nothing.

    [#]

    Function url_view_base:: operator core::string_view

    Return the URL as a core::string_view

    Synopsis

                operator core::string_view() const noexcept;
            

    Description

    Complexity

    Constant.

    Exception Safety

    Throws nothing.

    [#]

    Function url_view_base:: persist

    Return a shared, persistent copy of the url

    Synopsis

                std::shared_ptr
    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.

    Example

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

    Complexity

    Linear in `this->size()`.

    Exception Safety

    Calls to allocate may throw.

    [#]

    Function url_view_base:: has_scheme

    Return true a scheme is present

    Synopsis

                bool
    has_scheme() const noexcept;
            

    Description

    This function returns true if this contains a scheme.

    Example

    assert( url_view( "http://www.example.com" ).has_scheme() );

    Complexity

    Constant.

    Exception Safety

    Throws nothing.

    BNF

    URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ] absolute-URI = scheme ":" hier-part [ "?" query ] scheme = ALPHA *( ALPHA / DIGIT / "+" / "-" / "." )

    Specification

  • 3.1. Scheme (rfc3986)
  • [#]

    Function url_view_base:: scheme

    Return the scheme

    Synopsis

                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.

    Example

    assert( url_view( "http://www.example.com" ).scheme() == "http" );

    Exception Safety

    Throws nothing.

    BNF

    scheme = ALPHA *( ALPHA / DIGIT / "+" / "-" / "." ) URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ] absolute-URI = scheme ":" hier-part [ "?" query ]

    Specification

  • 3.1. Scheme (rfc3986)
  • [#]

    Function url_view_base:: scheme_id

    Return the scheme

    Synopsis

                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 .
  • Example

    assert( url_view( "wss://www.example.com/crypto.cgi" ).scheme_id() == scheme::wss );

    Complexity

    Constant.

    Exception Safety

    Throws nothing.

    BNF

    URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ] absolute-URI = scheme ":" hier-part [ "?" query ] scheme = ALPHA *( ALPHA / DIGIT / "+" / "-" / "." )

    Specification

  • 3.1. Scheme (rfc3986)
  • [#]

    Function url_view_base:: has_authority

    Return true if an authority is present

    Synopsis

                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.

    Example

    assert( url_view( "http://www.example.com/index.htm" ).has_authority() );

    Complexity

    Constant.

    Exception Safety

    Throws nothing.

    BNF

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

    Specification

  • 3.2. Authority (rfc3986)
  • [#]

    Function url_view_base:: authority

    Return the authority

    Synopsis

                authority_view
    authority() const noexcept;
            

    Description

    This function returns the authority as an authority_view .

    Example

    authority_view a = url_view( "https://www.example.com:8080/index.htm" ).authority();

    Complexity

    Constant.

    Exception Safety

    Throws nothing.

    BNF

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

    Specification

  • 3.2. Authority (rfc3986)
  • [#]

    Function url_view_base:: encoded_authority

    Return the authority.

    Synopsis

                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.

    Example

    assert( url_view( "file://Network%20Drive/My%2DFiles" ).encoded_authority() == "Network%20Drive" );

    Complexity

    Constant.

    Exception Safety

    Throws nothing.

    BNF

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

    Specification

  • 3.2. Authority (rfc3986)
  • [#]

    Function url_view_base:: has_userinfo

    Return true if a userinfo is present

    Synopsis

                bool
    has_userinfo() const noexcept;
            

    Description

    This function returns true if this contains a userinfo.

    Example

    assert( url_view( "http://jane%2Ddoe:pass@example.com" ).has_userinfo() );

    Complexity

    Constant.

    Exception Safety

    Throws nothing.

    BNF

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

    Specification

  • 3.2.1. User Information (rfc3986)
  • [#]

    Function url_view_base:: has_password

    Return true if a password is present

    Synopsis

                bool
    has_password() const noexcept;
            

    Description

    This function returns true if the userinfo is present and contains a password.

    Example

    assert( url_view( "http://jane%2Ddoe:pass@example.com" ).has_password() );

    Complexity

    Constant.

    Exception Safety

    Throws nothing.

    BNF

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

    Specification

  • 3.2.1. User Information (rfc3986)
  • [#]

    Function url_view_base:: userinfo

    Return the userinfo

    Synopsis

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

    Example

    assert( url_view( "http://jane%2Ddoe:pass@example.com" ).userinfo() == "jane-doe:pass" );

    Complexity

    Linear in `this->userinfo().size()`.

    Exception Safety

    Calls to allocate may throw.

    BNF

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

    Specification

  • 3.2.1. User Information (rfc3986)
  • [#]

    Function url_view_base:: encoded_userinfo

    Return the userinfo

    Synopsis

                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.

    Example

    assert( url_view( "http://jane%2Ddoe:pass@example.com" ).encoded_userinfo() == "jane%2Ddoe:pass" );

    Complexity

    Constant.

    Exception Safety

    Throws nothing

    BNF

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

    Specification

  • 3.2.1. User Information (rfc3986)
  • [#]

    Function url_view_base:: user

    Return the user

    Synopsis

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

    Example

    assert( url_view( "http://jane%2Ddoe:pass@example.com" ).user() == "jane-doe" );

    Complexity

    Linear in `this->user().size()`.

    Exception Safety

    Calls to allocate may throw.

    BNF

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

    Specification

  • 3.2.1. User Information (rfc3986)
  • [#]

    Function url_view_base:: encoded_user

    Return the user

    Synopsis

                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.

    Example

    assert( url_view( "http://jane%2Ddoe:pass@example.com" ).encoded_user() == "jane%2Ddoe" );

    Complexity

    Constant.

    Exception Safety

    Throws nothing.

    BNF

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

    Specification

  • 3.2.1. User Information (rfc3986)
  • [#]

    Function url_view_base:: password

    Return the password

    Synopsis

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

    Example

    assert( url_view( "http://jane%2Ddoe:pass@example.com" ).password() == "pass" );

    Complexity

    Linear in `this->password().size()`.

    Exception Safety

    Calls to allocate may throw.

    BNF

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

    Specification

  • 3.2.1. User Information (rfc3986)
  • [#]

    Function url_view_base:: encoded_password

    Return the password

    Synopsis

                pct_string_view
    encoded_password() const noexcept;
            

    Description

    This function returns the password portion of the userinfo as a percent-encoded string.

    Example

    assert( url_view( "http://jane%2Ddoe:pass@example.com" ).encoded_password() == "pass" );

    Complexity

    Constant.

    Exception Safety

    Throws nothing.

    BNF

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

    Specification

  • 3.2.1. User Information (rfc3986)
  • [#]

    Function url_view_base:: host_type

    Return the host type

    Synopsis

                host_type
    host_type() const noexcept;
            

    Description

    This function returns one of the following constants representing the type of host present.

  • host_type::ipv4
  • host_type::ipv6
  • host_type::ipvfuture
  • host_type::name
  • host_type::none
  • When has_authority is false, the host type is host_type::none .

    Example

    assert( url_view( "https://192.168.0.1/local.htm" ).host_type() == host_type::ipv4 );

    Complexity

    Constant.

    Exception Safety

    Throws nothing.

    Specification

  • 3.2.2. Host (rfc3986)
  • [#]

    Function url_view_base:: host

    Return the host

    Synopsis

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

    Example

    assert( url_view( "https://www%2droot.example.com/" ).host() == "www-root.example.com" );

    Complexity

    Linear in `this->host().size()`.

    Exception Safety

    Calls to allocate may throw.

    BNF

    host = IP-literal / IPv4address / reg-name IP-literal = "[" ( IPv6address / IPvFuture ) "]" reg-name = *( unreserved / pct-encoded / "-" / ".")

    Specification

  • 3.2.2. Host (rfc3986)
  • [#]

    Function url_view_base:: encoded_host

    Return the host

    Synopsis

                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.

    Example

    assert( url_view( "https://www%2droot.example.com/" ).encoded_host() == "www%2droot.example.com" );

    Complexity

    Constant.

    Exception Safety

    Throws nothing.

    BNF

    host = IP-literal / IPv4address / reg-name IP-literal = "[" ( IPv6address / IPvFuture ) "]" reg-name = *( unreserved / pct-encoded / "-" / ".")

    Specification

  • 3.2.2. Host (rfc3986)
  • [#]

    Function url_view_base:: host_address

    Return the host

    Synopsis

                template
    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.
  • Example

    assert( url_view( "https://[1::6:c0a8:1]/" ).host_address() == "1::6:c0a8:1" );

    Complexity

    Linear in `this->host_address().size()`.

    Exception Safety

    Calls to allocate may throw.

    BNF

    host = IP-literal / IPv4address / reg-name IP-literal = "[" ( IPv6address / IPvFuture ) "]" reg-name = *( unreserved / pct-encoded / "-" / ".")

    Specification

  • 3.2.2. Host (rfc3986)
  • [#]

    Function url_view_base:: encoded_host_address

    Return the host

    Synopsis

                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.
  • Example

    assert( url_view( "https://www%2droot.example.com/" ).encoded_host_address() == "www%2droot.example.com" );

    Complexity

    Constant.

    Exception Safety

    Throws nothing.

    BNF

    host = IP-literal / IPv4address / reg-name IP-literal = "[" ( IPv6address / IPvFuture ) "]" reg-name = *( unreserved / pct-encoded / "-" / ".")

    Specification

  • 3.2.2. Host (rfc3986)
  • [#]

    Function url_view_base:: host_ipv4_address

    Return the host IPv4 address

    Synopsis

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

    Example

    assert( url_view( "http://127.0.0.1/index.htm?user=win95" ).host_ipv4_address() == ipv4_address( "127.0.0.1" ) );

    Complexity

    Constant.

    Exception Safety

    Throws nothing.

    BNF

    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

    Specification

  • 3.2.2. Host (rfc3986)
  • [#]

    Function url_view_base:: host_ipv6_address

    Return the host IPv6 address

    Synopsis

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

    Example

    assert( url_view( "ftp://[::1]/" ).host_ipv6_address() == ipv6_address( "::1" ) );

    Complexity

    Constant.

    Exception Safety

    Throws nothing.

    BNF

    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

    Specification

  • 3.2.2. Host (rfc3986)
  • [#]

    Function url_view_base:: host_ipvfuture

    Return the host IPvFuture address

    Synopsis

                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.

    Example

    assert( url_view( "http://[v1fe.d:9]/index.htm" ).host_ipvfuture() == "v1fe.d:9" );

    Complexity

    Constant.

    Exception Safety

    Throws nothing.

    BNF

    IPvFuture = "v" 1*HEXDIG "." 1*( unreserved / sub-delims / ":" )

    Specification

  • 3.2.2. Host (rfc3986)
  • [#]

    Function url_view_base:: host_name

    Return the host name

    Synopsis

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

    Example

    assert( url_view( "https://www%2droot.example.com/" ).host_name() == "www-root.example.com" );

    Complexity

    Linear in `this->host_name().size()`.

    Exception Safety

    Calls to allocate may throw.

    BNF

    host = IP-literal / IPv4address / reg-name IP-literal = "[" ( IPv6address / IPvFuture ) "]" reg-name = *( unreserved / pct-encoded / "-" / ".")

    Specification

  • 3.2.2. Host (rfc3986)
  • [#]

    Function url_view_base:: encoded_host_name

    Return the host name

    Synopsis

                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.

    Example

    assert( url_view( "https://www%2droot.example.com/" ).encoded_host_name() == "www%2droot.example.com" );

    Complexity

    Constant.

    Exception Safety

    Throws nothing.

    BNF

    host = IP-literal / IPv4address / reg-name IP-literal = "[" ( IPv6address / IPvFuture ) "]" reg-name = *( unreserved / pct-encoded / "-" / ".")

    Specification

  • 3.2.2. Host (rfc3986)
  • [#]

    Function url_view_base:: zone_id

    Return the IPv6 Zone ID

    Synopsis

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

    Example

    assert( url_view( "http://[fe80::1%25eth0]/" ).zone_id() == "eth0" );

    Complexity

    Linear in `this->encoded_zone_id().size()`.

    Exception Safety

    Calls to allocate may throw.

    BNF

    host = IP-literal / IPv4address / reg-name IP-literal = "[" ( IPv6address / IPv6addrz / IPvFuture ) "]" ZoneID = 1*( unreserved / pct-encoded ) IPv6addrz = IPv6address "%25" ZoneID

    Specification

  • Representing IPv6 Zone Identifiers in Address Literals and Uniform Resource Identifiers
  • [#]

    Function url_view_base:: encoded_zone_id

    Return the IPv6 Zone ID

    Synopsis

                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.

    Example

    assert( url_view( "http://[fe80::1%25eth0]/" ).encoded_zone_id() == "eth0" );

    Complexity

    Constant.

    Exception Safety

    Throws nothing.

    BNF

    host = IP-literal / IPv4address / reg-name IP-literal = "[" ( IPv6address / IPv6addrz / IPvFuture ) "]" ZoneID = 1*( unreserved / pct-encoded ) IPv6addrz = IPv6address "%25" ZoneID

    Specification

  • Representing IPv6 Zone Identifiers in Address Literals and Uniform Resource Identifiers
  • [#]

    Function url_view_base:: has_port

    Return true if a port is present

    Synopsis

                bool
    has_port() const noexcept;
            

    Description

    This function returns true if an authority is present and contains a port.

    Example

    assert( url_view( "wss://www.example.com:443" ).has_port() );

    Complexity

    Constant.

    Exception Safety

    Throws nothing.

    BNF

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

    Specification

  • 3.2.3. Port (rfc3986)
  • [#]

    Function url_view_base:: port

    Return the port

    Synopsis

                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.

    Example

    assert( url_view( "http://localhost.com:8080" ).port() == "8080" );

    Complexity

    Constant.

    Exception Safety

    Throws nothing.

    BNF

    port = *DIGIT

    Specification

  • 3.2.3. Port (rfc3986)
  • [#]

    Function url_view_base:: port_number

    Return the port

    Synopsis

                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.

    Example

    assert( url_view( "http://localhost.com:8080" ).port_number() == 8080 );

    Complexity

    Constant.

    Exception Safety

    Throws nothing.

    BNF

    port = *DIGIT

    Specification

  • 3.2.3. Port (rfc3986)
  • [#]

    Function url_view_base:: is_path_absolute

    Return true if the path is absolute

    Synopsis

                bool
    is_path_absolute() const noexcept;
            

    Description

    This function returns true if the path begins with a forward slash ('/').

    Example

    assert( url_view( "/path/to/file.txt" ).is_path_absolute() );

    Complexity

    Constant.

    Exception Safety

    Throws nothing.

    BNF

    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

    Specification

  • 3.3. Path (rfc3986)
  • [#]

    Function url_view_base:: path

    Return the path

    Synopsis

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

    Example

    assert( url_view( "file:///Program%20Files/Games/config.ini" ).path() == "/Program Files/Games/config.ini" );

    Complexity

    Linear in `this->path().size()`.

    Exception Safety

    Calls to allocate may throw.

    BNF

    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

    Specification

  • 3.3. Path (rfc3986)
  • [#]

    Function url_view_base:: encoded_path

    Return the path

    Synopsis

                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.

    Example

    assert( url_view( "file:///Program%20Files/Games/config.ini" ).encoded_path() == "/Program%20Files/Games/config.ini" );

    Complexity

    Constant.

    Exception Safety

    Throws nothing.

    BNF

    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

    Specification

  • 3.3. Path (rfc3986)
  • [#]

    Function url_view_base:: segments

    Return the path as a container of segments

    Synopsis

                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.

    Example

    segments_view sv = url_view( "/path/to/file.txt" ).segments();

    Complexity

    Constant.

    Exception Safety

    Throws nothing.

    BNF

    path = [ "/" ] segment *( "/" segment )

    Specification

  • 3.3. Path (rfc3986)
  • [#]

    Function url_view_base:: encoded_segments

    Return the path as a container of segments

    Synopsis

                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.

    Example

    segments_encoded_view sv = url_view( "/path/to/file.txt" ).encoded_segments();

    Complexity

    Constant.

    Exception Safety

    Throws nothing.

    BNF

    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

    Specification

  • 3.3. Path (rfc3986)
  • [#]

    Function url_view_base:: has_query

    Return true if a query is present

    Synopsis

                bool
    has_query() const noexcept;
            

    Description

    This function returns true if this contains a query. An empty query is distinct from having no query.

    Example

    assert( url_view( "/sql?id=42&col=name&page-size=20" ).has_query() );

    Complexity

    Constant.

    Exception Safety

    Throws nothing.

    BNF

    query = *( pchar / "/" / "?" ) query-param = key [ "=" value ] query-params = [ query-param ] *( "&" query-param )

    Specification

  • ://en.wikipedia.org/wiki/Query_string" >Query string (Wikipedia)
  • [#]

    Function url_view_base:: query

    Return the query

    Synopsis

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

    Example

    assert( url_view( "/sql?id=42&name=jane%2Ddoe&page+size=20" ).query() == "id=42&name=jane-doe&page size=20" );

    Complexity

    Linear in `this->query().size()`.

    Exception Safety

    Calls to allocate may throw.

    BNF

    query = *( pchar / "/" / "?" ) query-param = key [ "=" value ] query-params = [ query-param ] *( "&" query-param )

    Specification

  • ://en.wikipedia.org/wiki/Query_string" >Query string (Wikipedia)
  • [#]

    Function url_view_base:: encoded_query

    Return the query

    Synopsis

                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.

    Example

    assert( url_view( "/sql?id=42&name=jane%2Ddoe&page+size=20" ).encoded_query() == "id=42&name=jane%2Ddoe&page+size=20" );

    Complexity

    Constant.

    Exception Safety

    Throws nothing.

    BNF

    query = *( pchar / "/" / "?" ) query-param = key [ "=" value ] query-params = [ query-param ] *( "&" query-param )

    Specification

  • ://en.wikipedia.org/wiki/Query_string" >Query string (Wikipedia)
  • Overload set url_view_base:: params

    Members

    Return the query as a container of parameters

    params_view
    params() const noexcept;
    » more...

    params_view
    params(encoding_opts opt) const noexcept;
    » more...
    [#]

    Function url_view_base:: encoded_params

    Return the query as a container of parameters

    Synopsis

                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.

    Example

    params_encoded_view pv = url_view( "/sql?id=42&name=jane%2Ddoe&page+size=20" ).encoded_params();

    Complexity

    Constant.

    Exception Safety

    Throws nothing.

    Specification

  • 3.4. Query (rfc3986)
  • BNF

    query = *( pchar / "/" / "?" ) query-param = key [ "=" value ] query-params = [ query-param ] *( "&" query-param )

    Specification

  • ://en.wikipedia.org/wiki/Query_string" >Query string (Wikipedia)
  • [#]

    Function url_view_base:: has_fragment

    Return true if a fragment is present

    Synopsis

                bool
    has_fragment() const noexcept;
            

    Description

    This function returns true if the url contains a fragment. An empty fragment is distinct from no fragment.

    Example

    assert( url_view( "http://www.example.com/index.htm#anchor" ).has_fragment() );

    Complexity

    Constant.

    Exception Safety

    Throws nothing.

    BNF

    URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ] relative-ref = relative-part [ "?" query ] [ "#" fragment ]

    Specification

  • 3.5. Fragment (rfc3986)
  • [#]

    Function url_view_base:: fragment

    Return the fragment

    Synopsis

                template
    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.
  • Example

    assert( url_view( "http://www.example.com/index.htm#a%2D1" ).fragment() == "a-1" );

    Complexity

    Linear in `this->fragment().size()`.

    Exception Safety

    Calls to allocate may throw. String tokens may throw exceptions.

    BNF

    fragment = *( pchar / "/" / "?" ) fragment-part = [ "#" fragment ]

    Specification

  • 3.5. Fragment (rfc3986)
  • [#]

    Function url_view_base:: encoded_fragment

    Return the fragment

    Synopsis

                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.

    Example

    assert( url_view( "http://www.example.com/index.htm#a%2D1" ).encoded_fragment() == "a%2D1" );

    Complexity

    Constant.

    Exception Safety

    Throws nothing.

    BNF

    fragment = *( pchar / "/" / "?" ) pchar = unreserved / pct-encoded / sub-delims / ":" / "@"

    Specification

  • 3.5. Fragment (rfc3986)
  • [#]

    Function url_view_base:: encoded_host_and_port

    Return the host and port

    Synopsis

                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.

    Example

    assert( url_view( "http://www.example.com:8080/index.htm" ).encoded_host_and_port() == "www.example.com:8080" );

    Complexity

    Constant.

    Exception Safety

    Throws nothing.

    BNF

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

    Specification

  • 3.2.2. Host (rfc3986)
  • 3.2.3. Port (rfc3986)
  • [#]

    Function url_view_base:: encoded_origin

    Return the origin

    Synopsis

                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.

    Example

    assert( url_view( "http://www.example.com:8080/index.htm?text=none#h1" ).encoded_origin() == "http://www.example.com:8080" );

    Complexity

    Constant.

    Exception Safety

    Throws nothing.

    [#]

    Function url_view_base:: encoded_resource

    Return the resource

    Synopsis

                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.

    Example

    assert( url_view( "http://www.example.com/index.html?query#frag" ).encoded_resource() == "/index.html?query#frag" );

    Complexity

    Constant.

    Exception Safety

    Throws nothing.

    Specification

  • 3.3. Path (rfc3986)
  • 3.4. Query (rfc3986)
  • [#]

    Function url_view_base:: encoded_target

    Return the target

    Synopsis

                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.

    Example

    assert( url_view( "http://www.example.com/index.html?query#frag" ).encoded_target() == "/index.html?query" );

    Complexity

    Constant.

    Exception Safety

    Throws nothing.

    Specification

  • 3.3. Path (rfc3986)
  • 3.4. Query (rfc3986)
  • [#]

    Function url_view_base:: compare

    Return the result of comparing this with another url

    Synopsis

                int
    compare(url_view_base const& other) const noexcept;
            

    Description

    This function compares two URLs according to Syntax-Based comparison algorithm.

    Complexity

    Linear in `min( u0.size(), u1.size() )`

    Exception Safety

    Throws nothing.

    Specification

  • 6.2.2 Syntax-Based Normalization (rfc3986)
  • [#]

    Friend operator==

    Return the result of comparing two URLs

    Synopsis

                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.

    Example

    url_view u0( "http://www.a.com/index.htm" ); url_view u1( "http://www.a.com/index.htm" ); assert( u0 == u1 );

    Effects

    url a(u0); a.normalize(); url b(u1); b.normalize(); return std::make_tuple( a.scheme(), a.user(), a.password(), a.host(), a.port(), a.path(), a.query(), a.fragment()) == std::make_tuple( b.scheme(), b.user(), b.password(), b.host(), b.port(), b.path(), b.query(), b.fragment());

    Complexity

    Linear in `min( u0.size(), u1.size() )`

    Exception Safety

    Throws nothing

    Specification

  • 6.2.2 Syntax-Based Normalization (rfc3986)
  • [#]

    Friend operator!=

    Return the result of comparing two URLs

    Synopsis

                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.

    Example

    url_view u0( "http://www.a.com/index.htm" ); url_view u1( "http://www.b.com/index.htm" ); assert( u0 != u1 );

    Effects

    url a(u0); a.normalize(); url b(u1); b.normalize(); return std::make_tuple( a.scheme(), a.user(), a.password(), a.host(), a.port(), a.path(), a.query(), a.fragment()) != std::make_tuple( b.scheme(), b.user(), b.password(), b.host(), b.port(), b.path(), b.query(), b.fragment());

    Complexity

    Linear in `min( u0.size(), u1.size() )`

    Exception Safety

    Throws nothing

    Specification

  • 6.2.2 Syntax-Based Normalization (rfc3986)
  • [#]

    Friend operator<

    Return the result of comparing two URLs

    Synopsis

                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.

    Example

    url_view u0( "http://www.a.com/index.htm" ); url_view u1( "http://www.b.com/index.htm" ); assert( u0 < u1 );

    Effects

    url a(u0); a.normalize(); url b(u1); b.normalize(); return std::make_tuple( a.scheme(), a.user(), a.password(), a.host(), a.port(), a.path(), a.query(), a.fragment()) < std::make_tuple( b.scheme(), b.user(), b.password(), b.host(), b.port(), b.path(), b.query(), b.fragment());

    Complexity

    Linear in `min( u0.size(), u1.size() )`

    Exception Safety

    Throws nothing

    Specification

  • 6.2.2 Syntax-Based Normalization (rfc3986)
  • [#]

    Friend operator<=

    Return the result of comparing two URLs

    Synopsis

                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.

    Example

    url_view u0( "http://www.b.com/index.htm" ); url_view u1( "http://www.b.com/index.htm" ); assert( u0 <= u1 );

    Effects

    url a(u0); a.normalize(); url b(u1); b.normalize(); return std::make_tuple( a.scheme(), a.user(), a.password(), a.host(), a.port(), a.path(), a.query(), a.fragment()) <= std::make_tuple( b.scheme(), b.user(), b.password(), b.host(), b.port(), b.path(), b.query(), b.fragment());

    Complexity

    Linear in `min( u0.size(), u1.size() )`

    Exception Safety

    Throws nothing

    Specification

  • 6.2.2 Syntax-Based Normalization (rfc3986)
  • [#]

    Friend operator>

    Return the result of comparing two URLs

    Synopsis

                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.

    Example

    url_view u0( "http://www.b.com/index.htm" ); url_view u1( "http://www.a.com/index.htm" ); assert( u0 > u1 );

    Effects

    url a(u0); a.normalize(); url b(u1); b.normalize(); return std::make_tuple( a.scheme(), a.user(), a.password(), a.host(), a.port(), a.path(), a.query(), a.fragment()) > std::make_tuple( b.scheme(), b.user(), b.password(), b.host(), b.port(), b.path(), b.query(), b.fragment());

    Complexity

    Linear in `min( u0.size(), u1.size() )`

    Exception Safety

    Throws nothing

    Specification

  • 6.2.2 Syntax-Based Normalization (rfc3986)
  • [#]

    Friend operator>=

    Return the result of comparing two URLs

    Synopsis

                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.

    Example

    url_view u0( "http://www.a.com/index.htm" ); url_view u1( "http://www.a.com/index.htm" ); assert( u0 >= u1 );

    Effects

    url a(u0); a.normalize(); url b(u1); b.normalize(); return std::make_tuple( a.scheme(), a.user(), a.password(), a.host(), a.port(), a.path(), a.query(), a.fragment()) >= std::make_tuple( b.scheme(), b.user(), b.password(), b.host(), b.port(), b.path(), b.query(), b.fragment());

    Complexity

    Linear in `min( u0.size(), u1.size() )`

    Exception Safety

    Throws nothing

    Specification

  • 6.2.2 Syntax-Based Normalization (rfc3986)
  • [#]

    Friend operator<<

    Synopsis

                friend
    std::ostream&
    operator<<(
        std::ostream& os,
        url_view_base const& u);
            
    [#]

    Function resolve

    Resolve a URL reference against a base URL

    Synopsis

                system::result
    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.

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

    Example

    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" );

    BNF

    absolute-URI = scheme ":" hier-part [ "?" query ]

    Exception Safety

    Basic guarantee. Calls to allocate may throw.

    Specification

    5. Reference Resolution (rfc3986)

    [#]

    Class url

    A modifiable container for a URL.

    Synopsis

                class url
        : public url_base;
            

    Member Functions

    Friends

    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.

    Exception Safety

  • Functions marked `noexcept` provide the no-throw guarantee, otherwise:
  • Functions which throw offer the strong exception safety guarantee.
  • BNF

    URI-reference = URI / relative-ref URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ] relative-ref = relative-part [ "?" query ] [ "#" fragment ] absolute-URI = scheme ":" hier-part [ "?" query ]

    Specification

  • Uniform Resource Identifier (URI): Generic Syntax (rfc3986)
  • [#]

    Function url:: ~url

    Destructor

    Synopsis

                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.

    Overload set url:: url

    Members

    Constructor

    url() noexcept;
    » more...

    Constructor

    url(core::string_view s);
    » more...

    Constructor

    url(url&& u) noexcept;
    » more...

    Constructor

    url(url_view_base const& u);
    » more...

    Constructor

    url(url const& u);
    » more...

    Overload set url:: operator=

    Members

    Assignment

    url&
    operator=(url&& u) noexcept;
    » more...

    Assignment

    url&
    operator=(url_view_base const& u);
    » more...

    Assignment

    url&
    operator=(url const& u);
    » more...
    [#]

    Function url:: swap

    Swap the contents.

    Synopsis

                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.

    Example

    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" );

    Complexity

    Constant

    Exception Safety

    Throws nothing.

    [#]

    Friend swap

    Swap

    Synopsis

                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.

    Example

    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" );

    Effects

    v0.swap( v1 );

    Complexity

    Constant

    Exception Safety

    Throws nothing

    [#]

    Function url:: set_scheme

    Set the scheme

    Synopsis

                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.

    Example

    assert( url( "http://www.example.com" ).set_scheme( "https" ).scheme_id() == scheme::https );

    Complexity

    Linear in `this->size() + s.size()`.

    Exception Safety

    Strong guarantee. Calls to allocate may throw. Exceptions thrown on invalid input.

    BNF

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

    Specification

  • 3.1. Scheme (rfc3986)
  • [#]

    Function url:: set_scheme_id

    url_base::set_scheme_id

    Synopsis

                url&
    set_scheme_id(scheme id);
            
    [#]

    Function url:: remove_scheme

    Remove the scheme

    Synopsis

                url&
    remove_scheme();
            

    Description

    This function removes the scheme if it is present.

    Example

    assert( url("http://www.example.com/index.htm" ).remove_scheme().buffer() == "//www.example.com/index.htm" );

    Postconditions

    this->has_scheme() == false && this->scheme_id() == scheme::none

    Complexity

    Linear in `this->size()`.

    Exception Safety

    Throws nothing.

    BNF

    URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ]

    Specification

  • 3.1. Scheme (rfc3986)
  • [#]

    Function url:: set_encoded_authority

    Set the authority

    Synopsis

                url&
    set_encoded_authority(pct_string_view s);
            

    Description

    This function sets the authority to the specified string. The string may contain percent-escapes.

    Example

    assert( url().set_encoded_authority( "My%20Computer" ).has_authority() );

    Exception Safety

    Strong guarantee. Calls to allocate may throw. Exceptions thrown on invalid input.

    BNF

    authority = [ userinfo "@" ] host [ ":" port ] userinfo = *( unreserved / pct-encoded / sub-delims / ":" ) host = IP-literal / IPv4address / reg-name port = *DIGIT

    Specification

  • 3.2. Authority (rfc3986)
  • [#]

    Function url:: remove_authority

    Remove the authority

    Synopsis

                url&
    remove_authority();
            

    Description

    This function removes the authority, which includes the userinfo, host, and a port if present.

    Example

    assert( url( "http://example.com/echo.cgi" ).remove_authority().buffer() == "http:/echo.cgi" );

    Postconditions

    this->has_authority() == false && this->has_userinfo() == false && this->has_port() == false

    Complexity

    Linear in `this->size()`.

    Exception Safety

    Throws nothing.

    BNF

    authority = [ userinfo "@" ] host [ ":" port ] userinfo = *( unreserved / pct-encoded / sub-delims / ":" ) host = IP-literal / IPv4address / reg-name port = *DIGIT

    Specification

  • 3.2. Authority (rfc3986)
  • [#]

    Function url:: set_userinfo

    Set the userinfo

    Synopsis

                url&
    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.

    Example

    assert( url( "http://example.com" ).set_userinfo( "user:pass" ).encoded_user() == "user" );

    Complexity

    Linear in `this->size() + s.size()`.

    Exception Safety

    Strong guarantee. Calls to allocate may throw.

    BNF

    userinfo = [ [ user ] [ ':' password ] ] user = *( unreserved / pct-encoded / sub-delims ) password = *( unreserved / pct-encoded / sub-delims / ":" )

    Specification

  • 3.2.1. User Information (rfc3986)
  • [#]

    Function url:: set_encoded_userinfo

    Set the userinfo.

    Synopsis

                url&
    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.

    Example

    assert( url( "http://example.com" ).set_encoded_userinfo( "john%20doe" ).user() == "john doe" );

    Complexity

    Linear in `this->size() + s.size()`.

    Exception Safety

    Strong guarantee. Calls to allocate may throw. Exceptions thrown on invalid input.

    BNF

    userinfo = [ [ user ] [ ':' password ] ] user = *( unreserved / pct-encoded / sub-delims ) password = *( unreserved / pct-encoded / sub-delims / ":" )

    Specification

  • 3.2.1. User Information (rfc3986)
  • [#]

    Function url:: remove_userinfo

    Remove the userinfo

    Synopsis

                url&
    remove_userinfo() noexcept;
            

    Description

    This function removes the userinfo if present, without removing any authority.

    Example

    assert( url( "http://user@example.com" ).remove_userinfo().has_userinfo() == false );

    Postconditions

    this->has_userinfo() == false && this->encoded_userinfo().empty == true

    Complexity

    Linear in `this->size()`.

    Exception Safety

    Throws nothing.

    BNF

    userinfo = [ [ user ] [ ':' password ] ] user = *( unreserved / pct-encoded / sub-delims ) password = *( unreserved / pct-encoded / sub-delims / ":" )

    Specification

  • 3.2.1. User Information (rfc3986)
  • [#]

    Function url:: set_user

    Set the user

    Synopsis

                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.

    Example

    assert( url().set_user("john doe").encoded_userinfo() == "john%20doe" );

    Postconditions

    this->has_authority() == true && this->has_userinfo() == true

    Complexity

    Linear in `this->size() + s.size()`.

    Exception Safety

    Strong guarantee. Calls to allocate may throw.

    BNF

    userinfo = [ [ user ] [ ':' password ] ] user = *( unreserved / pct-encoded / sub-delims ) password = *( unreserved / pct-encoded / sub-delims / ":" )

    Specification

  • 3.2.1. User Information (rfc3986)
  • [#]

    Function url:: set_encoded_user

    Set the user

    Synopsis

                url&
    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.

    Example

    assert( url().set_encoded_user("john%20doe").userinfo() == "john doe" );

    Postconditions

    this->has_authority() == true && this->has_userinfo() == true

    Complexity

    Linear in `this->size() + s.size()`.

    Exception Safety

    Strong guarantee. Calls to allocate may throw.

    BNF

    userinfo = [ [ user ] [ ':' password ] ] user = *( unreserved / pct-encoded / sub-delims ) password = *( unreserved / pct-encoded / sub-delims / ":" )

    Specification

  • 3.2.1. User Information (rfc3986)
  • [#]

    Function url:: set_password

    Set the password.

    Synopsis

                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.

    Example

    assert( url("http://user@example.com").set_password( "pass" ).encoded_userinfo() == "user:pass" );

    Postconditions

    this->has_password() == true && this->password() == s

    Exception Safety

    Strong guarantee. Calls to allocate may throw.

    BNF

    userinfo = [ [ user ] [ ':' password ] ] user = *( unreserved / pct-encoded / sub-delims ) password = *( unreserved / pct-encoded / sub-delims / ":" )

    Specification

  • 3.2.1. User Information (rfc3986)
  • [#]

    Function url:: set_encoded_password

    Set the password.

    Synopsis

                url&
    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.

    Example

    assert( url("http://user@example.com").set_encoded_password( "pass" ).encoded_userinfo() == "user:pass" );

    Postconditions

    this->has_password() == true

    Exception Safety

    Strong guarantee. Calls to allocate may throw.

    BNF

    userinfo = [ [ user ] [ ':' password ] ] user = *( unreserved / pct-encoded / sub-delims ) password = *( unreserved / pct-encoded / sub-delims / ":" )

    Specification

  • 3.2.1. User Information (rfc3986)
  • [#]

    Function url:: remove_password

    Remove the password

    Synopsis

                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.

    Example

    assert( url( "http://user:pass@example.com" ).remove_password().authority().buffer() == "user@example.com" );

    Postconditions

    this->has_password() == false && this->encoded_password().empty() == true

    Complexity

    Linear in `this->size()`.

    Exception Safety

    Throws nothing.

    BNF

    userinfo = [ [ user ] [ ':' password ] ] user = *( unreserved / pct-encoded / sub-delims ) password = *( unreserved / pct-encoded / sub-delims / ":" )

    Specification

  • 3.2.1. User Information (rfc3986)
  • [#]

    Function url:: set_host

    Set the host

    Synopsis

                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.

    Example

    assert( url( "http://www.example.com" ).set_host( "127.0.0.1" ).buffer() == "http://127.0.0.1" );

    Postconditions

    this->has_authority() == true

    Complexity

    Linear in `this->size() + s.size()`.

    Exception Safety

    Strong guarantee. Calls to allocate may throw.

    BNF

    host = IP-literal / IPv4address / reg-name IP-literal = "[" ( IPv6address / IPvFuture ) "]" reg-name = *( unreserved / pct-encoded / "-" / ".")

    Specification

  • IPv4 (Wikipedia)
  • IP Version 6 Addressing Architecture (rfc4291)
  • 3.2.2. Host (rfc3986)
  • [#]

    Function url:: set_encoded_host

    Set the host

    Synopsis

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

    Example

    assert( url( "http://www.example.com" ).set_host( "127.0.0.1" ).buffer() == "http://127.0.0.1" );

    Postconditions

    this->has_authority() == true

    Complexity

    Linear in `this->size() + s.size()`.

    Exception Safety

    Strong guarantee. Calls to allocate may throw. Exceptions thrown on invalid input.

    BNF

    host = IP-literal / IPv4address / reg-name IP-literal = "[" ( IPv6address / IPvFuture ) "]" reg-name = *( unreserved / pct-encoded / "-" / ".")

    Specification

  • IPv4 (Wikipedia)
  • IP Version 6 Addressing Architecture (rfc4291)
  • 3.2.2. Host (rfc3986)
  • [#]

    Function url:: set_host_address

    Set the host to an address

    Synopsis

                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.

    Example

    assert( url( "http://www.example.com" ).set_host_address( "127.0.0.1" ).buffer() == "http://127.0.0.1" );

    Postconditions

    this->has_authority() == true

    Complexity

    Linear in `s.size()`.

    Exception Safety

    Strong guarantee. Calls to allocate may throw.

    BNF

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

    Specification

  • IPv4 (Wikipedia)
  • IP Version 6 Addressing Architecture (rfc4291)
  • 3.2.2. Host (rfc3986)
  • [#]

    Function url:: set_encoded_host_address

    Set the host to an address

    Synopsis

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

    Example

    assert( url( "http://www.example.com" ).set_host( "127.0.0.1" ).buffer() == "http://127.0.0.1" );

    Postconditions

    this->has_authority() == true

    Complexity

    Linear in `this->size() + s.size()`.

    Exception Safety

    Strong guarantee. Calls to allocate may throw. Exceptions thrown on invalid input.

    BNF

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

    Specification

  • IPv4 (Wikipedia)
  • IP Version 6 Addressing Architecture (rfc4291)
  • 3.2.2. Host (rfc3986)
  • [#]

    Function url:: set_host_ipv4

    Set the host to an address

    Synopsis

                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 .

    Example

    assert( url("http://www.example.com").set_host_ipv4( ipv4_address( "127.0.0.1" ) ).buffer() == "http://127.0.0.1" );

    Complexity

    Linear in `this->size()`.

    Postconditions

    this->has_authority() == true && this->host_ipv4_address() == addr && this->host_type() == host_type::ipv4

    Exception Safety

    Strong guarantee. Calls to allocate may throw.

    BNF

    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

    Specification

  • IPv4 (Wikipedia)
  • 3.2.2. Host (rfc3986)
  • [#]

    Function url:: set_host_ipv6

    Set the host to an address

    Synopsis

                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 .

    Example

    assert( url().set_host_ipv6( ipv6_address( "1::6:c0a8:1" ) ).authority().buffer() == "[1::6:c0a8:1]" );

    Postconditions

    this->has_authority() == true && this->host_ipv6_address() == addr && this->host_type() == host_type::ipv6

    Complexity

    Linear in `this->size()`.

    Exception Safety

    Strong guarantee. Calls to allocate may throw.

    BNF

    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

    Specification

  • IP Version 6 Addressing Architecture (rfc4291)
  • 3.2.2. Host (rfc3986)
  • [#]

    Function url:: set_host_ipvfuture

    Set the host to an address

    Synopsis

                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 .

    Example

    assert( url().set_host_ipvfuture( "v42.bis" ).buffer() == "//[v42.bis]" );

    Complexity

    Linear in `this->size() + s.size()`.

    Postconditions

    this->has_authority() == true && this->host_ipvfuture) == s && this->host_type() == host_type::ipvfuture

    Exception Safety

    Strong guarantee. Calls to allocate may throw. Exceptions thrown on invalid input.

    BNF

    IPvFuture = "v" 1*HEXDIG "." 1*( unreserved / sub-delims / ":" )

    Specification

  • 3.2.2. Host (rfc3986)
  • [#]

    Function url:: set_host_name

    Set the host to a name

    Synopsis

                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 .

    Example

    assert( url( "http://www.example.com/index.htm").set_host_name( "localhost" ).host_address() == "localhost" );

    Postconditions

    this->has_authority() == true && this->host_ipv6_address() == addr && this->host_type() == host_type::name

    Exception Safety

    Strong guarantee. Calls to allocate may throw.

    BNF

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

    Specification

  • 3.2.2. Host (rfc3986)
  • [#]

    Function url:: set_encoded_host_name

    Set the host to a name

    Synopsis

                url&
    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 .

    Example

    assert( url( "http://www.example.com/index.htm").set_encoded_host_name( "localhost" ).host_address() == "localhost" );

    Postconditions

    this->has_authority() == true && this->host_ipv6_address() == addr && this->host_type() == host_type::name

    Exception Safety

    Strong guarantee. Calls to allocate may throw. Exceptions thrown on invalid input.

    BNF

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

    Specification

  • 3.2.2. Host (rfc3986)
  • [#]

    Function url:: set_port_number

    Set the port

    Synopsis

                url&
    set_port_number(std::uint16_t n);
            

    Description

    The port is set to the specified integer.

    Example

    assert( url( "http://www.example.com" ).set_port_number( 8080 ).authority().buffer() == "www.example.com:8080" );

    Postconditions

    this->has_authority() == true && this->has_port() == true && this->port_number() == n

    Complexity

    Linear in `this->size()`.

    Exception Safety

    Strong guarantee. Calls to allocate may throw.

    BNF

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

    Specification

  • 3.2.3. Port (rfc3986)
  • [#]

    Function url:: set_port

    Set the port

    Synopsis

                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.

    Example

    assert( url( "http://www.example.com" ).set_port( "8080" ).authority().buffer() == "www.example.com:8080" );

    Postconditions

    this->has_port() == true && this->port_number() == n && this->port() == std::to_string(n)

    Exception Safety

    Strong guarantee. Calls to allocate may throw. Exceptions thrown on invalid input.

    BNF

    port = *DIGIT

    Specification

  • 3.2.3. Port (rfc3986)
  • [#]

    Function url:: remove_port

    Remove the port

    Synopsis

                url&
    remove_port() noexcept;
            

    Description

    If a port exists, it is removed. The rest of the authority is unchanged.

    Example

    assert( url( "http://www.example.com:80" ).remove_port().authority().buffer() == "www.example.com" );

    Postconditions

    this->has_port() == false && this->port_number() == 0 && this->port() == ""

    Complexity

    Linear in `this->size()`.

    Exception Safety

    Throws nothing.

    BNF

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

    Specification

  • 3.2.3. Port (rfc3986)
  • [#]

    Function url:: set_path

    Set the path.

    Synopsis

                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

    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.

    Example

    url u( "http://www.example.com" ); u.set_path( "path/to/file.txt" ); assert( u.path() == "/path/to/file.txt" );

    Complexity

    Linear in `this->size() + s.size()`.

    Exception Safety

    Strong guarantee. Calls to allocate may throw.

    BNF

    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

    Specification

  • 3.3. Path (rfc3986)
  • [#]

    Function url:: set_encoded_path

    Set the path.

    Synopsis

                url&
    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.

    Example

    url u( "http://www.example.com" ); u.set_encoded_path( "path/to/file.txt" ); assert( u.encoded_path() == "/path/to/file.txt" );

    Complexity

    Linear in `this->size() + s.size()`.

    Exception Safety

    Strong guarantee. Calls to allocate may throw. Exceptions thrown on invalid input.

    BNF

    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

    Specification

  • 3.3. Path (rfc3986)
  • [#]

    Function url:: set_query

    Set the query

    Synopsis

                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.

    Example

    assert( url( "http://example.com" ).set_query( "id=42" ).query() == "id=42" );

    Postconditions

    this->has_query() == true && this->query() == s

    Exception Safety

    Strong guarantee. Calls to allocate may throw.

    BNF

    query = *( pchar / "/" / "?" ) query-param = key [ "=" value ] query-params = [ query-param ] *( "&" query-param )

    Specification

  • 3.4. Query (rfc3986)
  • Query string (Wikipedia)
  • [#]

    Function url:: set_encoded_query

    Set the query

    Synopsis

                url&
    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.

    Example

    assert( url( "http://example.com" ).set_encoded_query( "id=42" ).encoded_query() == "id=42" );

    Postconditions

    this->has_query() == true && this->query() == decode_view( s );

    Exception Safety

    Strong guarantee. Calls to allocate may throw. Exceptions thrown on invalid input.

    BNF

    query = *( pchar / "/" / "?" ) query-param = key [ "=" value ] query-params = [ query-param ] *( "&" query-param )

    Specification

  • 3.4. Query (rfc3986)
  • Query string (Wikipedia)
  • [#]

    Function url:: set_params

    Set the query params

    Synopsis

                url&
    set_params(std::initializer_list ps);
            

    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.

    Example

    assert( url( "http://example.com" ).set_params( {"id", "42"} ).query() == "id=42" );

    Postconditions

    this->has_query() == true

    Exception Safety

    Strong guarantee. Calls to allocate may throw.

    Complexity

    Linear.

    BNF

    query = *( pchar / "/" / "?" ) query-param = key [ "=" value ] query-params = [ query-param ] *( "&" query-param )

    Specification

  • ://en.wikipedia.org/wiki/Query_string" >Query string (Wikipedia)
  • [#]

    Function url:: set_encoded_params

    Set the query params

    Synopsis

                url&
    set_encoded_params(std::initializer_list 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.

    Example

    assert( url( "http://example.com" ).set_encoded_params( {"id", "42"} ).encoded_query() == "id=42" );

    Postconditions

    this->has_query() == true

    Complexity

    Linear.

    Exception Safety

    Strong guarantee. Calls to allocate may throw. Exceptions thrown on invalid input.

    BNF

    query = *( pchar / "/" / "?" ) query-param = key [ "=" value ] query-params = [ query-param ] *( "&" query-param )

    Specification

  • 3.4. Query (rfc3986)
  • Query string (Wikipedia)
  • [#]

    Function url:: remove_query

    Remove the query

    Synopsis

                url&
    remove_query() noexcept;
            

    Description

    If a query is present, it is removed. An empty query is distinct from having no query.

    Example

    assert( url( "http://www.example.com?id=42" ).remove_query().buffer() == "http://www.example.com" );

    Postconditions

    this->has_query() == false && this->params().empty()

    Exception Safety

    Throws nothing.

    BNF

    query = *( pchar / "/" / "?" ) query-param = key [ "=" value ] query-params = [ query-param ] *( "&" query-param )

    Specification

  • 3.4. Query (rfc3986)
  • Query string (Wikipedia)
  • [#]

    Function url:: remove_fragment

    Remove the fragment

    Synopsis

                url&
    remove_fragment() noexcept;
            

    Description

    This function removes the fragment. An empty fragment is distinct from having no fragment.

    Example

    assert( url( "?first=john&last=doe#anchor" ).remove_fragment().buffer() == "?first=john&last=doe" );

    Postconditions

    this->has_fragment() == false && this->encoded_fragment() == ""

    Complexity

    Constant.

    Exception Safety

    Throws nothing.

    BNF

    fragment = *( pchar / "/" / "?" )

    Specification

  • 3.5. Fragment
  • [#]

    Function url:: set_fragment

    Set the fragment.

    Synopsis

                url&
    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.

    Example

    assert( url("?first=john&last=doe" ).set_encoded_fragment( "john doe" ).encoded_fragment() == "john%20doe" );

    Postconditions

    this->has_fragment() == true && this->fragment() == s

    Complexity

    Linear in `this->size() + s.size()`.

    Exception Safety

    Strong guarantee. Calls to allocate may throw.

    BNF

    fragment = *( pchar / "/" / "?" )

    Specification

  • 3.5. Fragment
  • [#]

    Function url:: set_encoded_fragment

    Set the fragment.

    Synopsis

                url&
    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.

    Example

    assert( url("?first=john&last=doe" ).set_encoded_fragment( "john%2Ddoe" ).fragment() == "john-doe" );

    Postconditions

    this->has_fragment() == true && this->fragment() == decode_view( s )

    Complexity

    Linear in `this->size() + s.size()`.

    Exception Safety

    Strong guarantee. Calls to allocate may throw. Exceptions thrown on invalid input.

    BNF

    fragment = *( pchar / "/" / "?" )

    Specification

  • 3.5. Fragment
  • [#]

    Function url:: remove_origin

    Remove the origin component

    Synopsis

                url&
    remove_origin();
            

    Description

    This function removes the origin, which consists of the scheme and authority.

    Example

    assert( url( "http://www.example.com/index.htm" ).remove_origin().buffer() == "/index.htm" );

    Postconditions

    this->scheme_id() == scheme::none && this->has_authority() == false

    Complexity

    Linear in `this->size()`.

    Exception Safety

    Throws nothing.

    [#]

    Function url:: normalize

    Normalize the URL components

    Synopsis

                url&
    normalize();
            

    Description

    Applies Syntax-based normalization to all components of the URL.

    Exception Safety

    Strong guarantee. Calls to allocate may throw.

    Specification

  • 6.2.2 Syntax-Based Normalization (rfc3986)
  • [#]

    Function url:: normalize_scheme

    Normalize the URL scheme

    Synopsis

                url&
    normalize_scheme();
            

    Description

    Applies Syntax-based normalization to the URL scheme.

    The scheme is normalized to lowercase.

    Exception Safety

    Strong guarantee. Calls to allocate may throw.

    Specification

  • 6.2.2 Syntax-Based Normalization (rfc3986)
  • [#]

    Function url:: normalize_authority

    Normalize the URL authority

    Synopsis

                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.

    Exception Safety

    Strong guarantee. Calls to allocate may throw.

    Specification

  • 6.2.2 Syntax-Based Normalization (rfc3986)
  • [#]

    Function url:: normalize_path

    Normalize the URL path

    Synopsis

                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.

    Exception Safety

    Strong guarantee. Calls to allocate may throw.

    Specification

  • 6.2.2 Syntax-Based Normalization (rfc3986)
  • [#]

    Function url:: normalize_query

    Normalize the URL query

    Synopsis

                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.

    Exception Safety

    Strong guarantee. Calls to allocate may throw.

    Specification

  • 6.2.2 Syntax-Based Normalization (rfc3986)
  • [#]

    Function url:: normalize_fragment

    Normalize the URL fragment

    Synopsis

                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.

    Exception Safety

    Strong guarantee. Calls to allocate may throw.

    Specification

  • 6.2.2 Syntax-Based Normalization (rfc3986)
  • [#]

    Function swap

    Swap

    Synopsis

                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.

    Example

    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" );

    Effects

    v0.swap( v1 );

    Complexity

    Constant

    Exception Safety

    Throws nothing

    [#]

    Class ipv4_address_rule_t

    Synopsis

                struct ipv4_address_rule_t;
            

    Types

    Member Functions

    [#]

    ipv4_address_rule_t:: value_type

    Synopsis

                using value_type = ipv4_address;
            
    [#]

    Function ipv4_address_rule_t:: parse

    Synopsis

                system::result
    parse(
        char const*& it,
        char const* end) const noexcept;
            
    [#]

    ipv4_address_rule

    Synopsis

                constexpr
    ipv4_address_rule_t const ipv4_address_rule = {};
            
    [#]

    Class ipv6_address_rule_t

    Synopsis

                struct ipv6_address_rule_t;
            

    Types

    Member Functions

    [#]

    ipv6_address_rule_t:: value_type

    Synopsis

                using value_type = ipv6_address;
            
    [#]

    Function ipv6_address_rule_t:: parse

    Synopsis

                system::result
    parse(
        char const*& it,
        char const* end) const noexcept;
            
    [#]

    ipv6_address_rule

    Synopsis

                constexpr
    ipv6_address_rule_t const ipv6_address_rule = {};
            
    [#]

    Function parse_absolute_uri

    Return a reference to a parsed URL string

    Synopsis

                system::result
    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.

    Example

    system::result< url_view > rv = parse_absolute_uri( "http://example.com/index.htm?id=1" );

    BNF

    absolute-URI = scheme ":" hier-part [ "?" query ] hier-part = "//" authority path-abempty / path-absolute / path-rootless / path-empty

    Specification

  • 4.3. Absolute URI (rfc3986)
  • [#]

    Function parse_origin_form

    Return a reference to a parsed URL string

    Synopsis

                system::result
    parse_origin_form(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.

    Example

    system::result< url_view > = parse_origin_form( "/index.htm?layout=mobile" );

    BNF

    origin-form = absolute-path [ "?" query ] absolute-path = 1*( "/" segment )

    Specification

  • 5.3.1. origin-form (rfc7230)
  • [#]

    Function parse_relative_ref

    Return a reference to a parsed URL string

    Synopsis

                system::result
    parse_relative_ref(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.

    Example

    system::result< url_view > = parse_relative_ref( "images/dot.gif?v=hide#a" );

    BNF

    relative-ref = relative-part [ "?" query ] [ "#" fragment ] relative-part = "//" authority path-abempty / path-absolute / path-noscheme / path-abempty / path-empty

    Specification

  • 4.2. Relative Reference (rfc3986)
  • Errata ID: 5428 (rfc3986)
  • [#]

    Function parse_uri

    Return a reference to a parsed URL string

    Synopsis

                system::result
    parse_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.

    Example

    system::result< url_view > = parse_uri( "https://www.example.com/index.htm?id=guest#s1" );

    BNF

    URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ] hier-part = "//" authority path-abempty / path-absolute / path-rootless / path-empty

    Specification

  • 3. Syntax Components (rfc3986)
  • [#]

    Function parse_uri_reference

    Return a reference to a parsed URL string

    Synopsis

                system::result
    parse_uri_reference(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.

    Example

    system::result< url_view > = parse_uri_reference( "ws://echo.example.com/?name=boost#demo" );

    BNF

    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

    Specification

  • 4.1. URI Reference (rfc3986)
  • Errata ID: 5428 (rfc3986)
  • [#]

    Class absolute_uri_rule_t

    Synopsis

                struct absolute_uri_rule_t;
            

    Types

    Member Functions

    [#]

    absolute_uri_rule_t:: value_type

    Synopsis

                using value_type = url_view;
            
    [#]

    Function absolute_uri_rule_t:: parse

    Synopsis

                system::result
    parse(
        char const*& it,
        char const* end) const noexcept;
            
    [#]

    absolute_uri_rule

    Synopsis

                constexpr
    absolute_uri_rule_t const absolute_uri_rule = {};
            
    [#]

    Class relative_ref_rule_t

    Synopsis

                struct relative_ref_rule_t;
            

    Types

    Member Functions

    [#]

    relative_ref_rule_t:: value_type

    Synopsis

                using value_type = url_view;
            
    [#]

    Function relative_ref_rule_t:: parse

    Synopsis

                system::result
    parse(
        char const*& it,
        char const* end) const noexcept;
            
    [#]

    relative_ref_rule

    Synopsis

                constexpr
    relative_ref_rule_t const relative_ref_rule = {};
            
    [#]

    Class uri_rule_t

    Synopsis

                struct uri_rule_t;
            

    Types

    Member Functions

    [#]

    uri_rule_t:: value_type

    Synopsis

                using value_type = url_view;
            
    [#]

    Function uri_rule_t:: parse

    Synopsis

                system::result
    parse(
        char const*& it,
        char const const* end) const noexcept;
            
    [#]

    uri_rule

    Synopsis

                constexpr
    uri_rule_t const uri_rule = {};
            
    [#]

    Class uri_reference_rule_t

    Synopsis

                struct uri_reference_rule_t;
            

    Types

    Member Functions

    [#]

    uri_reference_rule_t:: value_type

    Synopsis

                using value_type = url_view;
            
    [#]

    Function uri_reference_rule_t:: parse

    Synopsis

                system::result
    parse(
        char const*& it,
        char const* end) const noexcept;
            
    [#]

    uri_reference_rule

    Synopsis

                constexpr
    uri_reference_rule_t const uri_reference_rule = {};
            
    [#]

    Class origin_form_rule_t

    Synopsis

                struct origin_form_rule_t;
            

    Types

    Member Functions

    [#]

    origin_form_rule_t:: value_type

    Synopsis

                using value_type = url_view;
            
    [#]

    Function origin_form_rule_t:: parse

    Synopsis

                system::result
    parse(
        char const*& it,
        char const* end) const noexcept;
            
    [#]

    origin_form_rule

    Synopsis

                constexpr
    origin_form_rule_t const origin_form_rule = {};
            
    [#]

    Class query_rule_t

    Synopsis

                struct query_rule_t;
            

    Types

    Member Functions

    [#]

    query_rule_t:: value_type

    Synopsis

                using value_type = params_encoded_view;
            
    [#]

    Function query_rule_t:: parse

    Synopsis

                system::result
    parse(
        char const*& it,
        char const* end) const noexcept;
            
    [#]

    query_rule

    Synopsis

                constexpr
    query_rule_t const query_rule = {};
            
    [#]

    Class static_url

    A modifiable container for a URL.

    Synopsis

                template
    class static_url
        : public static_url_base;
            

    Member Functions

    Friends

    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.

    Example

    static_url< 1024 > u( "https://www.example.com" );

    Invariants

    this->capacity() == Capacity + 1
    [#]

    Function static_url:: ~static_url

    Destructor

    Synopsis

                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.

    Overload set static_url:: static_url

    Members

    Constructor

    static_url() noexcept;
    » more...

    Constructor

    static_url(core::string_view s);
    » more...

    Constructor

    static_url(static_url const& u) noexcept;
    » more...

    Constructor

    static_url(url_view_base const& u);
    » more...

    Overload set static_url:: operator=

    Members

    Assignment

    static_url&
    operator=(static_url const& u) noexcept;
    » more...

    Assignment

    static_url&
    operator=(url_view_base const& u);
    » more...
    [#]

    Function static_url:: set_scheme

    Set the scheme

    Synopsis

                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.

    Example

    assert( url( "http://www.example.com" ).set_scheme( "https" ).scheme_id() == scheme::https );

    Complexity

    Linear in `this->size() + s.size()`.

    Exception Safety

    Strong guarantee. Calls to allocate may throw. Exceptions thrown on invalid input.

    BNF

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

    Specification

  • 3.1. Scheme (rfc3986)
  • [#]

    Function static_url:: set_scheme_id

    url_base::set_scheme_id

    Synopsis

                static_url&
    set_scheme_id(scheme id);
            
    [#]

    Function static_url:: remove_scheme

    Remove the scheme

    Synopsis

                static_url&
    remove_scheme();
            

    Description

    This function removes the scheme if it is present.

    Example

    assert( url("http://www.example.com/index.htm" ).remove_scheme().buffer() == "//www.example.com/index.htm" );

    Postconditions

    this->has_scheme() == false && this->scheme_id() == scheme::none

    Complexity

    Linear in `this->size()`.

    Exception Safety

    Throws nothing.

    BNF

    URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ]

    Specification

  • 3.1. Scheme (rfc3986)
  • [#]

    Function static_url:: set_encoded_authority

    Set the authority

    Synopsis

                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.

    Example

    assert( url().set_encoded_authority( "My%20Computer" ).has_authority() );

    Exception Safety

    Strong guarantee. Calls to allocate may throw. Exceptions thrown on invalid input.

    BNF

    authority = [ userinfo "@" ] host [ ":" port ] userinfo = *( unreserved / pct-encoded / sub-delims / ":" ) host = IP-literal / IPv4address / reg-name port = *DIGIT

    Specification

  • 3.2. Authority (rfc3986)
  • [#]

    Function static_url:: remove_authority

    Remove the authority

    Synopsis

                static_url&
    remove_authority();
            

    Description

    This function removes the authority, which includes the userinfo, host, and a port if present.

    Example

    assert( url( "http://example.com/echo.cgi" ).remove_authority().buffer() == "http:/echo.cgi" );

    Postconditions

    this->has_authority() == false && this->has_userinfo() == false && this->has_port() == false

    Complexity

    Linear in `this->size()`.

    Exception Safety

    Throws nothing.

    BNF

    authority = [ userinfo "@" ] host [ ":" port ] userinfo = *( unreserved / pct-encoded / sub-delims / ":" ) host = IP-literal / IPv4address / reg-name port = *DIGIT

    Specification

  • 3.2. Authority (rfc3986)
  • [#]

    Function static_url:: set_userinfo

    Set the userinfo

    Synopsis

                static_url&
    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.

    Example

    assert( url( "http://example.com" ).set_userinfo( "user:pass" ).encoded_user() == "user" );

    Complexity

    Linear in `this->size() + s.size()`.

    Exception Safety

    Strong guarantee. Calls to allocate may throw.

    BNF

    userinfo = [ [ user ] [ ':' password ] ] user = *( unreserved / pct-encoded / sub-delims ) password = *( unreserved / pct-encoded / sub-delims / ":" )

    Specification

  • 3.2.1. User Information (rfc3986)
  • [#]

    Function static_url:: set_encoded_userinfo

    Set the userinfo.

    Synopsis

                static_url&
    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.

    Example

    assert( url( "http://example.com" ).set_encoded_userinfo( "john%20doe" ).user() == "john doe" );

    Complexity

    Linear in `this->size() + s.size()`.

    Exception Safety

    Strong guarantee. Calls to allocate may throw. Exceptions thrown on invalid input.

    BNF

    userinfo = [ [ user ] [ ':' password ] ] user = *( unreserved / pct-encoded / sub-delims ) password = *( unreserved / pct-encoded / sub-delims / ":" )

    Specification

  • 3.2.1. User Information (rfc3986)
  • [#]

    Function static_url:: remove_userinfo

    Remove the userinfo

    Synopsis

                static_url&
    remove_userinfo() noexcept;
            

    Description

    This function removes the userinfo if present, without removing any authority.

    Example

    assert( url( "http://user@example.com" ).remove_userinfo().has_userinfo() == false );

    Postconditions

    this->has_userinfo() == false && this->encoded_userinfo().empty == true

    Complexity

    Linear in `this->size()`.

    Exception Safety

    Throws nothing.

    BNF

    userinfo = [ [ user ] [ ':' password ] ] user = *( unreserved / pct-encoded / sub-delims ) password = *( unreserved / pct-encoded / sub-delims / ":" )

    Specification

  • 3.2.1. User Information (rfc3986)
  • [#]

    Function static_url:: set_user

    Set the user

    Synopsis

                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.

    Example

    assert( url().set_user("john doe").encoded_userinfo() == "john%20doe" );

    Postconditions

    this->has_authority() == true && this->has_userinfo() == true

    Complexity

    Linear in `this->size() + s.size()`.

    Exception Safety

    Strong guarantee. Calls to allocate may throw.

    BNF

    userinfo = [ [ user ] [ ':' password ] ] user = *( unreserved / pct-encoded / sub-delims ) password = *( unreserved / pct-encoded / sub-delims / ":" )

    Specification

  • 3.2.1. User Information (rfc3986)
  • [#]

    Function static_url:: set_encoded_user

    Set the user

    Synopsis

                static_url&
    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.

    Example

    assert( url().set_encoded_user("john%20doe").userinfo() == "john doe" );

    Postconditions

    this->has_authority() == true && this->has_userinfo() == true

    Complexity

    Linear in `this->size() + s.size()`.

    Exception Safety

    Strong guarantee. Calls to allocate may throw.

    BNF

    userinfo = [ [ user ] [ ':' password ] ] user = *( unreserved / pct-encoded / sub-delims ) password = *( unreserved / pct-encoded / sub-delims / ":" )

    Specification

  • 3.2.1. User Information (rfc3986)
  • [#]

    Function static_url:: set_password

    Set the password.

    Synopsis

                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.

    Example

    assert( url("http://user@example.com").set_password( "pass" ).encoded_userinfo() == "user:pass" );

    Postconditions

    this->has_password() == true && this->password() == s

    Exception Safety

    Strong guarantee. Calls to allocate may throw.

    BNF

    userinfo = [ [ user ] [ ':' password ] ] user = *( unreserved / pct-encoded / sub-delims ) password = *( unreserved / pct-encoded / sub-delims / ":" )

    Specification

  • 3.2.1. User Information (rfc3986)
  • [#]

    Function static_url:: set_encoded_password

    Set the password.

    Synopsis

                static_url&
    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.

    Example

    assert( url("http://user@example.com").set_encoded_password( "pass" ).encoded_userinfo() == "user:pass" );

    Postconditions

    this->has_password() == true

    Exception Safety

    Strong guarantee. Calls to allocate may throw.

    BNF

    userinfo = [ [ user ] [ ':' password ] ] user = *( unreserved / pct-encoded / sub-delims ) password = *( unreserved / pct-encoded / sub-delims / ":" )

    Specification

  • 3.2.1. User Information (rfc3986)
  • [#]

    Function static_url:: remove_password

    Remove the password

    Synopsis

                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.

    Example

    assert( url( "http://user:pass@example.com" ).remove_password().authority().buffer() == "user@example.com" );

    Postconditions

    this->has_password() == false && this->encoded_password().empty() == true

    Complexity

    Linear in `this->size()`.

    Exception Safety

    Throws nothing.

    BNF

    userinfo = [ [ user ] [ ':' password ] ] user = *( unreserved / pct-encoded / sub-delims ) password = *( unreserved / pct-encoded / sub-delims / ":" )

    Specification

  • 3.2.1. User Information (rfc3986)
  • [#]

    Function static_url:: set_host

    Set the host

    Synopsis

                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.

    Example

    assert( url( "http://www.example.com" ).set_host( "127.0.0.1" ).buffer() == "http://127.0.0.1" );

    Postconditions

    this->has_authority() == true

    Complexity

    Linear in `this->size() + s.size()`.

    Exception Safety

    Strong guarantee. Calls to allocate may throw.

    BNF

    host = IP-literal / IPv4address / reg-name IP-literal = "[" ( IPv6address / IPvFuture ) "]" reg-name = *( unreserved / pct-encoded / "-" / ".")

    Specification

  • IPv4 (Wikipedia)
  • IP Version 6 Addressing Architecture (rfc4291)
  • 3.2.2. Host (rfc3986)
  • [#]

    Function static_url:: set_encoded_host

    Set the host

    Synopsis

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

    Example

    assert( url( "http://www.example.com" ).set_host( "127.0.0.1" ).buffer() == "http://127.0.0.1" );

    Postconditions

    this->has_authority() == true

    Complexity

    Linear in `this->size() + s.size()`.

    Exception Safety

    Strong guarantee. Calls to allocate may throw. Exceptions thrown on invalid input.

    BNF

    host = IP-literal / IPv4address / reg-name IP-literal = "[" ( IPv6address / IPvFuture ) "]" reg-name = *( unreserved / pct-encoded / "-" / ".")

    Specification

  • IPv4 (Wikipedia)
  • IP Version 6 Addressing Architecture (rfc4291)
  • 3.2.2. Host (rfc3986)
  • [#]

    Function static_url:: set_host_address

    Set the host to an address

    Synopsis

                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.

    Example

    assert( url( "http://www.example.com" ).set_host_address( "127.0.0.1" ).buffer() == "http://127.0.0.1" );

    Postconditions

    this->has_authority() == true

    Complexity

    Linear in `s.size()`.

    Exception Safety

    Strong guarantee. Calls to allocate may throw.

    BNF

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

    Specification

  • IPv4 (Wikipedia)
  • IP Version 6 Addressing Architecture (rfc4291)
  • 3.2.2. Host (rfc3986)
  • [#]

    Function static_url:: set_encoded_host_address

    Set the host to an address

    Synopsis

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

    Example

    assert( url( "http://www.example.com" ).set_host( "127.0.0.1" ).buffer() == "http://127.0.0.1" );

    Postconditions

    this->has_authority() == true

    Complexity

    Linear in `this->size() + s.size()`.

    Exception Safety

    Strong guarantee. Calls to allocate may throw. Exceptions thrown on invalid input.

    BNF

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

    Specification

  • IPv4 (Wikipedia)
  • IP Version 6 Addressing Architecture (rfc4291)
  • 3.2.2. Host (rfc3986)
  • [#]

    Function static_url:: set_host_ipv4

    Set the host to an address

    Synopsis

                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 .

    Example

    assert( url("http://www.example.com").set_host_ipv4( ipv4_address( "127.0.0.1" ) ).buffer() == "http://127.0.0.1" );

    Complexity

    Linear in `this->size()`.

    Postconditions

    this->has_authority() == true && this->host_ipv4_address() == addr && this->host_type() == host_type::ipv4

    Exception Safety

    Strong guarantee. Calls to allocate may throw.

    BNF

    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

    Specification

  • IPv4 (Wikipedia)
  • 3.2.2. Host (rfc3986)
  • [#]

    Function static_url:: set_host_ipv6

    Set the host to an address

    Synopsis

                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 .

    Example

    assert( url().set_host_ipv6( ipv6_address( "1::6:c0a8:1" ) ).authority().buffer() == "[1::6:c0a8:1]" );

    Postconditions

    this->has_authority() == true && this->host_ipv6_address() == addr && this->host_type() == host_type::ipv6

    Complexity

    Linear in `this->size()`.

    Exception Safety

    Strong guarantee. Calls to allocate may throw.

    BNF

    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

    Specification

  • IP Version 6 Addressing Architecture (rfc4291)
  • 3.2.2. Host (rfc3986)
  • [#]

    Function static_url:: set_host_ipvfuture

    Set the host to an address

    Synopsis

                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 .

    Example

    assert( url().set_host_ipvfuture( "v42.bis" ).buffer() == "//[v42.bis]" );

    Complexity

    Linear in `this->size() + s.size()`.

    Postconditions

    this->has_authority() == true && this->host_ipvfuture) == s && this->host_type() == host_type::ipvfuture

    Exception Safety

    Strong guarantee. Calls to allocate may throw. Exceptions thrown on invalid input.

    BNF

    IPvFuture = "v" 1*HEXDIG "." 1*( unreserved / sub-delims / ":" )

    Specification

  • 3.2.2. Host (rfc3986)
  • [#]

    Function static_url:: set_host_name

    Set the host to a name

    Synopsis

                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 .

    Example

    assert( url( "http://www.example.com/index.htm").set_host_name( "localhost" ).host_address() == "localhost" );

    Postconditions

    this->has_authority() == true && this->host_ipv6_address() == addr && this->host_type() == host_type::name

    Exception Safety

    Strong guarantee. Calls to allocate may throw.

    BNF

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

    Specification

  • 3.2.2. Host (rfc3986)
  • [#]

    Function static_url:: set_encoded_host_name

    Set the host to a name

    Synopsis

                static_url&
    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 .

    Example

    assert( url( "http://www.example.com/index.htm").set_encoded_host_name( "localhost" ).host_address() == "localhost" );

    Postconditions

    this->has_authority() == true && this->host_ipv6_address() == addr && this->host_type() == host_type::name

    Exception Safety

    Strong guarantee. Calls to allocate may throw. Exceptions thrown on invalid input.

    BNF

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

    Specification

  • 3.2.2. Host (rfc3986)
  • [#]

    Function static_url:: set_port_number

    Set the port

    Synopsis

                static_url&
    set_port_number(std::uint16_t n);
            

    Description

    The port is set to the specified integer.

    Example

    assert( url( "http://www.example.com" ).set_port_number( 8080 ).authority().buffer() == "www.example.com:8080" );

    Postconditions

    this->has_authority() == true && this->has_port() == true && this->port_number() == n

    Complexity

    Linear in `this->size()`.

    Exception Safety

    Strong guarantee. Calls to allocate may throw.

    BNF

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

    Specification

  • 3.2.3. Port (rfc3986)
  • [#]

    Function static_url:: set_port

    Set the port

    Synopsis

                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.

    Example

    assert( url( "http://www.example.com" ).set_port( "8080" ).authority().buffer() == "www.example.com:8080" );

    Postconditions

    this->has_port() == true && this->port_number() == n && this->port() == std::to_string(n)

    Exception Safety

    Strong guarantee. Calls to allocate may throw. Exceptions thrown on invalid input.

    BNF

    port = *DIGIT

    Specification

  • 3.2.3. Port (rfc3986)
  • [#]

    Function static_url:: remove_port

    Remove the port

    Synopsis

                static_url&
    remove_port() noexcept;
            

    Description

    If a port exists, it is removed. The rest of the authority is unchanged.

    Example

    assert( url( "http://www.example.com:80" ).remove_port().authority().buffer() == "www.example.com" );

    Postconditions

    this->has_port() == false && this->port_number() == 0 && this->port() == ""

    Complexity

    Linear in `this->size()`.

    Exception Safety

    Throws nothing.

    BNF

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

    Specification

  • 3.2.3. Port (rfc3986)
  • [#]

    Function static_url:: set_path

    Set the path.

    Synopsis

                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

    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.

    Example

    url u( "http://www.example.com" ); u.set_path( "path/to/file.txt" ); assert( u.path() == "/path/to/file.txt" );

    Complexity

    Linear in `this->size() + s.size()`.

    Exception Safety

    Strong guarantee. Calls to allocate may throw.

    BNF

    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

    Specification

  • 3.3. Path (rfc3986)
  • [#]

    Function static_url:: set_encoded_path

    Set the path.

    Synopsis

                static_url&
    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.

    Example

    url u( "http://www.example.com" ); u.set_encoded_path( "path/to/file.txt" ); assert( u.encoded_path() == "/path/to/file.txt" );

    Complexity

    Linear in `this->size() + s.size()`.

    Exception Safety

    Strong guarantee. Calls to allocate may throw. Exceptions thrown on invalid input.

    BNF

    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

    Specification

  • 3.3. Path (rfc3986)
  • [#]

    Function static_url:: set_query

    Set the query

    Synopsis

                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.

    Example

    assert( url( "http://example.com" ).set_query( "id=42" ).query() == "id=42" );

    Postconditions

    this->has_query() == true && this->query() == s

    Exception Safety

    Strong guarantee. Calls to allocate may throw.

    BNF

    query = *( pchar / "/" / "?" ) query-param = key [ "=" value ] query-params = [ query-param ] *( "&" query-param )

    Specification

  • 3.4. Query (rfc3986)
  • Query string (Wikipedia)
  • [#]

    Function static_url:: set_encoded_query

    Set the query

    Synopsis

                static_url&
    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.

    Example

    assert( url( "http://example.com" ).set_encoded_query( "id=42" ).encoded_query() == "id=42" );

    Postconditions

    this->has_query() == true && this->query() == decode_view( s );

    Exception Safety

    Strong guarantee. Calls to allocate may throw. Exceptions thrown on invalid input.

    BNF

    query = *( pchar / "/" / "?" ) query-param = key [ "=" value ] query-params = [ query-param ] *( "&" query-param )

    Specification

  • 3.4. Query (rfc3986)
  • Query string (Wikipedia)
  • [#]

    Function static_url:: remove_query

    Remove the query

    Synopsis

                static_url&
    remove_query() noexcept;
            

    Description

    If a query is present, it is removed. An empty query is distinct from having no query.

    Example

    assert( url( "http://www.example.com?id=42" ).remove_query().buffer() == "http://www.example.com" );

    Postconditions

    this->has_query() == false && this->params().empty()

    Exception Safety

    Throws nothing.

    BNF

    query = *( pchar / "/" / "?" ) query-param = key [ "=" value ] query-params = [ query-param ] *( "&" query-param )

    Specification

  • 3.4. Query (rfc3986)
  • Query string (Wikipedia)
  • [#]

    Function static_url:: remove_fragment

    Remove the fragment

    Synopsis

                static_url&
    remove_fragment() noexcept;
            

    Description

    This function removes the fragment. An empty fragment is distinct from having no fragment.

    Example

    assert( url( "?first=john&last=doe#anchor" ).remove_fragment().buffer() == "?first=john&last=doe" );

    Postconditions

    this->has_fragment() == false && this->encoded_fragment() == ""

    Complexity

    Constant.

    Exception Safety

    Throws nothing.

    BNF

    fragment = *( pchar / "/" / "?" )

    Specification

  • 3.5. Fragment
  • [#]

    Function static_url:: set_fragment

    Set the fragment.

    Synopsis

                static_url&
    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.

    Example

    assert( url("?first=john&last=doe" ).set_encoded_fragment( "john doe" ).encoded_fragment() == "john%20doe" );

    Postconditions

    this->has_fragment() == true && this->fragment() == s

    Complexity

    Linear in `this->size() + s.size()`.

    Exception Safety

    Strong guarantee. Calls to allocate may throw.

    BNF

    fragment = *( pchar / "/" / "?" )

    Specification

  • 3.5. Fragment
  • [#]

    Function static_url:: set_encoded_fragment

    Set the fragment.

    Synopsis

                static_url&
    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.

    Example

    assert( url("?first=john&last=doe" ).set_encoded_fragment( "john%2Ddoe" ).fragment() == "john-doe" );

    Postconditions

    this->has_fragment() == true && this->fragment() == decode_view( s )

    Complexity

    Linear in `this->size() + s.size()`.

    Exception Safety

    Strong guarantee. Calls to allocate may throw. Exceptions thrown on invalid input.

    BNF

    fragment = *( pchar / "/" / "?" )

    Specification

  • 3.5. Fragment
  • [#]

    Function static_url:: remove_origin

    Remove the origin component

    Synopsis

                static_url&
    remove_origin();
            

    Description

    This function removes the origin, which consists of the scheme and authority.

    Example

    assert( url( "http://www.example.com/index.htm" ).remove_origin().buffer() == "/index.htm" );

    Postconditions

    this->scheme_id() == scheme::none && this->has_authority() == false

    Complexity

    Linear in `this->size()`.

    Exception Safety

    Throws nothing.

    [#]

    Function static_url:: normalize

    Normalize the URL components

    Synopsis

                static_url&
    normalize();
            

    Description

    Applies Syntax-based normalization to all components of the URL.

    Exception Safety

    Strong guarantee. Calls to allocate may throw.

    Specification

  • 6.2.2 Syntax-Based Normalization (rfc3986)
  • [#]

    Function static_url:: normalize_scheme

    Normalize the URL scheme

    Synopsis

                static_url&
    normalize_scheme();
            

    Description

    Applies Syntax-based normalization to the URL scheme.

    The scheme is normalized to lowercase.

    Exception Safety

    Strong guarantee. Calls to allocate may throw.

    Specification

  • 6.2.2 Syntax-Based Normalization (rfc3986)
  • [#]

    Function static_url:: normalize_authority

    Normalize the URL authority

    Synopsis

                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.

    Exception Safety

    Strong guarantee. Calls to allocate may throw.

    Specification

  • 6.2.2 Syntax-Based Normalization (rfc3986)
  • [#]

    Function static_url:: normalize_path

    Normalize the URL path

    Synopsis

                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.

    Exception Safety

    Strong guarantee. Calls to allocate may throw.

    Specification

  • 6.2.2 Syntax-Based Normalization (rfc3986)
  • [#]

    Function static_url:: normalize_query

    Normalize the URL query

    Synopsis

                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.

    Exception Safety

    Strong guarantee. Calls to allocate may throw.

    Specification

  • 6.2.2 Syntax-Based Normalization (rfc3986)
  • [#]

    Function static_url:: normalize_fragment

    Normalize the URL fragment

    Synopsis

                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.

    Exception Safety

    Strong guarantee. Calls to allocate may throw.

    Specification

  • 6.2.2 Syntax-Based Normalization (rfc3986)
  • [#]

    Class static_url_base

    Common implementation for all static URLs

    Synopsis

                class static_url_base
        : public url_base;
            

    Member Functions

    Friends

    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.

    Containers

  • url
  • url_view
  • static_url
  • Parsing Functions

  • parse_absolute_uri
  • parse_origin_form
  • parse_relative_ref
  • parse_uri
  • parse_uri_reference
  • [#]

    string_view

    The type of string_view used by the library

    Synopsis

                using string_view = 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.

    Overload set format

    Members

    Format arguments into a URL

    template
    url
    format(
        core::string_view fmt,
        Args&&... args);
    » more...

    Format arguments into a URL

    url
    format(
        core::string_view fmt,
        std::initializer_list args);
    » more...

    Overload set format_to

    Members

    Format arguments into a URL

    template
    void
    format_to(
        url_base& u,
        core::string_view fmt,
        Args&&... args);
    » more...

    Format arguments into a URL

    void
    format_to(
        url_base& u,
        core::string_view fmt,
        std::initializer_list args);
    » more...
    [#]

    Function arg

    Synopsis

                template
    detail::named_arg
    arg(
        core::string_view name,
        T const& arg);
            
    [#]

    gen_delim_chars

    The gen-delims character set

    Synopsis

                constexpr
    grammar::lut_chars const gen_delim_chars = ":/?#[]@";
            

    Description

    Example

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

    BNF

    gen-delims = ":" / "/" / "?" / "#" / "[" / "]" / "@"

    Specification

  • 2.2. Reserved Characters (rfc3986)
  • [#]

    reserved_chars

    The reserved character set

    Synopsis

                constexpr
    lut_chars const reserved_chars = ~unreserved_chars;
            

    Description

    Example

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

    Specification

  • 2.3. Unreserved Characters (rfc3986)
  • [#]

    Namespace system

    Types

    [#]

    Class is_error_code_enum

    Synopsis

                template<>
    struct is_error_code_enum;
            

    Variables

    [#]

    is_error_code_enum:: value

    Synopsis

                static
    bool const value = true;
            
    [#]

    Class is_error_code_enum

    Synopsis

                template<>
    struct is_error_code_enum;
            

    Variables

    [#]

    is_error_code_enum:: value

    Synopsis

                static
    bool const value = true;
            
    [#]

    Class is_error_condition_enum

    Synopsis

                template<>
    struct is_error_condition_enum;
            

    Variables

    [#]

    is_error_condition_enum:: value

    Synopsis

                static
    bool const value = true;
            
    [#]

    Using Declaration: url

    Synopsis

                using urls::url
    ;
            

    Introduced Symbols

    Name
    [#]

    Using Declaration: url_view

    Synopsis

                using urls::url_view
    ;
            

    Introduced Symbols

    Name
    [#]

    Namespace std

    Types

    [#]

    Class hash

    Synopsis

                template<>
    struct hash;
            

    Member Functions

    Overload set hash:: hash

    Members

    constexpr
    hash() = default;
    » more...

    constexpr
    hash(hash const&) = default;
    » more...

    hash(size_t salt) noexcept;
    » more...
    [#]

    Function hash:: operator=

    Synopsis

                constexpr
    hash&
    operator=(hash const&) = default;
            
    [#]

    Function hash:: operator()

    Synopsis

                size_t
    operator()(boost::urls::url const& u) const noexcept;
            
    [#]

    Class hash

    Synopsis

                template<>
    struct hash;
            

    Member Functions

    Overload set hash:: hash

    Members

    constexpr
    hash() = default;
    » more...

    constexpr
    hash(hash const&) = default;
    » more...

    hash(size_t salt) noexcept;
    » more...
    [#]

    Function hash:: operator=

    Synopsis

                constexpr
    hash&
    operator=(hash const&) = default;
            
    [#]

    Function hash:: operator()

    Synopsis

                size_t
    operator()(boost::urls::url_view const& u) const noexcept;
            
    [#]

    Class hash

    Synopsis

                template
    struct hash>;
            

    Member Functions

    Overload set hash:: hash

    Members

    hash() = default;
    » more...

    hash(hash const&) = default;
    » more...

    hash(size_t salt) noexcept;
    » more...
    [#]

    Function hash:: operator=

    Synopsis

                hash&
    operator=(hash const&) = default;
            
    [#]

    Function hash:: operator()

    Synopsis

                size_t
    operator()(boost::urls::static_url const& u) const noexcept;
            
    [#]

    Function arg:: arg

    Synopsis

                constexpr
    arg() = default;
            
    [#]

    Function arg:: arg

    Synopsis

                constexpr
    arg(arg&&) = default;
            
    [#]

    Function arg:: arg

    Synopsis

                arg(arg const&) = delete;
            
    [#]

    Function arg:: operator=

    Synopsis

                arg&
    operator=(arg&&) = delete;
            
    [#]

    Function arg:: operator=

    Synopsis

                arg&
    operator=(arg const&) = delete;
            
    [#]

    Function string_view_base:: starts_with

    Return true if a matching prefix exists

    Synopsis

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

    Description

    See `core::string_view::starts_with`

    [#]

    Function string_view_base:: starts_with

    Return true if a matching prefix exists

    Synopsis

                constexpr
    bool
    starts_with(char x) const noexcept;
            

    Description

    See `core::string_view::starts_with`

    [#]

    Function string_view_base:: starts_with

    Return true if a matching prefix exists

    Synopsis

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

    Description

    See `core::string_view::starts_with`

    [#]

    Function string_view_base:: ends_with

    Return true if a matching suffix exists

    Synopsis

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

    Description

    See `core::string_view::ends_with`

    [#]

    Function string_view_base:: ends_with

    Return true if a matching suffix exists

    Synopsis

                constexpr
    bool
    ends_with(char x) const noexcept;
            

    Description

    See `core::string_view::ends_with`

    [#]

    Function string_view_base:: ends_with

    Return true if a matching suffix exists

    Synopsis

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

    Description

    See `core::string_view::ends_with`

    [#]

    Function string_view_base:: find

    Return the position of matching characters

    Synopsis

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

    Description

    See `core::string_view::find`

    [#]

    Function string_view_base:: find

    Return the position of matching characters

    Synopsis

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

    Description

    See `core::string_view::find`

    [#]

    Function string_view_base:: find

    Return the position of matching characters

    Synopsis

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

    Description

    See `core::string_view::find`

    [#]

    Function string_view_base:: find

    Return the position of matching characters

    Synopsis

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

    Description

    See `core::string_view::find`

    [#]

    Function string_view_base:: rfind

    Return the position of matching characters

    Synopsis

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

    Description

    See `core::string_view::rfind`

    [#]

    Function string_view_base:: rfind

    Return the position of matching characters

    Synopsis

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

    Description

    See `core::string_view::rfind`

    [#]

    Function string_view_base:: rfind

    Return the position of matching characters

    Synopsis

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

    Description

    See `core::string_view::rfind`

    [#]

    Function string_view_base:: rfind

    Return the position of matching characters

    Synopsis

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

    Description

    See `core::string_view::rfind`

    [#]

    Function string_view_base:: compare

    Return the result of comparing to another string

    Synopsis

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

    Description

    See `core::string_view::compare`

    [#]

    Function string_view_base:: compare

    Return the result of comparing to another string

    Synopsis

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

    Description

    See `core::string_view::compare`

    [#]

    Function string_view_base:: compare

    Return the result of comparing to another string

    Synopsis

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

    Description

    See `core::string_view::compare`

    [#]

    Function string_view_base:: compare

    Return the result of comparing to another string

    Synopsis

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

    Description

    See `core::string_view::compare`

    [#]

    Function string_view_base:: compare

    Return the result of comparing to another string

    Synopsis

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

    Description

    See `core::string_view::compare`

    [#]

    Function string_view_base:: compare

    Return the result of comparing to another string

    Synopsis

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

    Description

    See `core::string_view::compare`

    [#]

    Function string_view_base:: find_first_of

    Return the position of the first match

    Synopsis

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

    Description

    See `core::string_view::find_first_of`

    [#]

    Function string_view_base:: find_first_of

    Return the position of the first match

    Synopsis

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

    Description

    See `core::string_view::find_first_of`

    [#]

    Function string_view_base:: find_first_of

    Return the position of the first match

    Synopsis

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

    Description

    See `core::string_view::find_first_of`

    [#]

    Function string_view_base:: find_first_of

    Return the position of the first match

    Synopsis

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

    Description

    See `core::string_view::find_first_of`

    [#]

    Function string_view_base:: find_last_of

    Return the position of the last match

    Synopsis

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

    Description

    See `core::string_view::find_last_of`

    [#]

    Function string_view_base:: find_last_of

    Return the position of the last match

    Synopsis

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

    Description

    See `core::string_view::find_last_of`

    [#]

    Function string_view_base:: find_last_of

    Return the position of the last match

    Synopsis

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

    Description

    See `core::string_view::find_last_of`

    [#]

    Function string_view_base:: find_last_of

    Return the position of the last match

    Synopsis

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

    Description

    See `core::string_view::find_last_of`

    [#]

    Function string_view_base:: contains

    Return true if matching characters are found

    Synopsis

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

    Description

    See `core::string_view::contains`

    [#]

    Function string_view_base:: contains

    Return true if matching characters are found

    Synopsis

                constexpr
    bool
    contains(char c) const noexcept;
            

    Description

    See `core::string_view::contains`

    [#]

    Function string_view_base:: contains

    Return true if matching characters are found

    Synopsis

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

    Description

    See `core::string_view::contains`

    [#]

    Function string_view_base:: find_first_not_of

    Return the position of the first non-match

    Synopsis

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

    Description

    See `core::string_view::find_first_not_of`

    [#]

    Function string_view_base:: find_first_not_of

    Return the position of the first non-match

    Synopsis

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

    Description

    See `core::string_view::find_first_not_of`

    [#]

    Function string_view_base:: find_first_not_of

    Return the position of the first non-match

    Synopsis

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

    Description

    See `core::string_view::find_first_not_of`

    [#]

    Function string_view_base:: find_first_not_of

    Return the position of the first non-match

    Synopsis

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

    Description

    See `core::string_view::find_first_not_of`

    [#]

    Function string_view_base:: find_last_not_of

    Return the position of the last non-match

    Synopsis

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

    Description

    See `core::string_view::find_last_not_of`

    [#]

    Function string_view_base:: find_last_not_of

    Return the position of the last non-match

    Synopsis

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

    Description

    See `core::string_view::find_last_not_of`

    [#]

    Function string_view_base:: find_last_not_of

    Return the position of the last non-match

    Synopsis

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

    Description

    See `core::string_view::find_last_not_of`

    [#]

    Function string_view_base:: find_last_not_of

    Return the position of the last non-match

    Synopsis

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

    Description

    See `core::string_view::find_last_not_of`

    [#]

    Function lut_chars:: operator()

    Return true if ch is in the character set.

    Synopsis

                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.

    Complexity

    Constant.

    Exception Safety

    Throws nothing.

    [#]

    Function lut_chars:: operator()

    Return true if ch is in the character set.

    Synopsis

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

    Description

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

    Complexity

    Constant.

    Exception Safety

    Throws nothing.

    [#]

    Function lut_chars:: lut_chars

    Constructor

    Synopsis

                constexpr
    lut_chars(char ch) noexcept;
            

    Description

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

    Example

    constexpr lut_chars asterisk( '*' );

    Complexity

    Constant.

    Exception Safety

    Throws nothing.

    [#]

    Function lut_chars:: lut_chars

    Constructor

    Synopsis

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

    Example

    constexpr lut_chars digits = "0123456789";

    Complexity

    Linear in `::strlen(s)`, or constant if `s` is a constant expression.

    Exception Safety

    Throws nothing.

    [#]

    Function lut_chars:: lut_chars

    Synopsis

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

    Function ref

    Synopsis

                template
    constexpr
    detail::charset_ref
    ref(CharSet const& cs) noexcept;
            
    [#]

    Function ref

    Synopsis

                template
    constexpr
    detail::rule_ref
    ref(Rule const& r) noexcept;
            
    [#]

    Function ref

    Synopsis

                constexpr
    void
    ref() = delete;
            
    [#]

    Function parse

    Parse a character buffer using a rule

    Synopsis

                template
    system::result
    parse(
        char const*& it,
        char const* end,
        Rule const& r);
            
    [#]

    Function parse

    Parse a character buffer using a rule

    Synopsis

                template
    system::result
    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.

    [#]

    Function ci_is_equal

    Synopsis

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

    Function ci_is_equal

    Synopsis

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

    Function variant_rule

    Synopsis

                template<
        class R0_,
        class... Rn_>
    constexpr
    variant_rule_t
    variant_rule(
        R0_ const& r0,
        Rn_ const&... rn) noexcept;
            
    [#]

    Function variant_rule

    Synopsis

                template<
        class R0,
        class... Rn>
    constexpr
    variant_rule_t
    variant_rule(
        R0 const& r0,
        Rn const&... rn) noexcept;
            
    [#]

    Function delim_rule

    Synopsis

                constexpr
    ch_delim_rule
    delim_rule(char ch) noexcept;
            
    [#]

    Function delim_rule

    Synopsis

                template
    constexpr
    cs_delim_rule
    delim_rule(CharSet const& cs) noexcept;
            
    [#]

    Function optional_rule

    Synopsis

                template
    constexpr
    optional_rule_t
    optional_rule(R_ const& r);
            
    [#]

    Function optional_rule

    Synopsis

                template
    constexpr
    optional_rule_t
    optional_rule(Rule const& r);
            
    [#]

    Function tuple_rule

    Synopsis

                template<
        class R0_,
        class... Rn_>
    constexpr
    tuple_rule_t
    tuple_rule(
        R0_ const& r0,
        Rn_ const&... rn) noexcept;
            
    [#]

    Function tuple_rule

    Synopsis

                template<
        class R0,
        class... Rn>
    constexpr
    tuple_rule_t
    tuple_rule(
        R0 const& r0,
        Rn const&... rn) noexcept;
            
    [#]

    Function recycled_ptr:: operator=

    Assignment

    Synopsis

                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.

    Effects

    this->release()

    Postconditions

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

    Exception Safety

    Throws nothing.

    [#]

    Function recycled_ptr:: operator=

    Assignment

    Synopsis

                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.

    Effects

    this->release()

    Postconditions

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

    Exception Safety

    Throws nothing.

    [#]

    Function recycled_ptr:: recycled_ptr

    Constructor

    Synopsis

                recycled_ptr(recycled& 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.

    Example

    static recycled< std::string > bin; recycled_ptr< std::string > ps( bin ); // Put the string into a known state ps->clear();

    Postconditions

    &this->bin() == &bin && ! this->empty()
    [#]

    Function recycled_ptr:: recycled_ptr

    Constructor

    Synopsis

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

    Description

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

    Example

    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();

    Postconditions

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

    Exception Safety

    Throws nothing.

    [#]

    Function recycled_ptr:: recycled_ptr

    Constructor

    Synopsis

                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.

    Example

    recycled_ptr< std::string > ps; // Put the string into a known state ps->clear();

    Postconditions

    &this->bin() != nullptr && ! this->empty()
    [#]

    Function recycled_ptr:: recycled_ptr

    Constructor

    Synopsis

                recycled_ptr(std::nullptr_t) noexcept;
            

    Description

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

    Example

    recycled_ptr< std::string > ps( nullptr ); // Acquire a string and put it into a known state ps->acquire(); ps->clear();

    Postconditions

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

    Exception Safety

    Throws nothing.

    [#]

    Function recycled_ptr:: recycled_ptr

    Constructor

    Synopsis

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

    Postconditions

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

    Exception Safety

    Throws nothing.

    [#]

    Function recycled_ptr:: recycled_ptr

    Constructor

    Synopsis

                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.

    Postconditions

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

    Exception Safety

    Throws nothing.

    [#]

    Function range:: iterator:: iterator

    Synopsis

                iterator() = default;
            
    [#]

    Function range:: iterator:: iterator

    Synopsis

                iterator(iterator const&) = default;
            
    [#]

    Function range:: iterator:: operator++

    Synopsis

                iterator&
    operator++() noexcept;
            
    [#]

    Function range:: iterator:: operator++

    Synopsis

                iterator
    operator++(int) noexcept;
            
    [#]

    Function range:: range

    Constructor

    Synopsis

                range() noexcept;
            

    Description

    Default-constructed ranges have zero elements.

    Exception Safety

    Throws nothing.

    [#]

    Function range:: range

    Constructor

    Synopsis

                range(range&& other) noexcept;
            

    Description

    The new range 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.

    Exception Safety

    Throws nothing.

    [#]

    Function range:: range

    Constructor

    Synopsis

                range(range const& other) noexcept;
            

    Description

    The copy 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.

    Exception Safety

    Throws nothing.

    [#]

    Function range:: operator=

    Assignment

    Synopsis

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

    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.

    Exception Safety

    Throws nothing.

    [#]

    Function range:: operator=

    Assignment

    Synopsis

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

    Description

    The copy 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.

    Exception Safety

    Throws nothing.

    [#]

    Function range_rule

    Synopsis

                template
    constexpr
    range_rule_t
    range_rule(
        Rule const& next,
        std::size_t N = 0,
        std::size_t M = std::size_t(-1)) noexcept;
            
    [#]

    Function range_rule

    Synopsis

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

    Function not_empty_rule

    Synopsis

                template
    constexpr
    not_empty_rule_t
    not_empty_rule(R_ const& r);
            
    [#]

    Function not_empty_rule

    Synopsis

                template
    constexpr
    not_empty_rule_t
    not_empty_rule(Rule const& r);
            
    [#]

    Function decode_view:: iterator:: iterator

    Synopsis

                constexpr
    iterator() = default;
            
    [#]

    Function decode_view:: iterator:: iterator

    Synopsis

                constexpr
    iterator(iterator const&) = default;
            
    [#]

    Function decode_view:: iterator:: operator++

    Synopsis

                iterator&
    operator++() noexcept;
            
    [#]

    Function decode_view:: iterator:: operator++

    Synopsis

                iterator
    operator++(int) noexcept;
            
    [#]

    Function decode_view:: iterator:: operator--

    Synopsis

                iterator&
    operator--() noexcept;
            
    [#]

    Function decode_view:: iterator:: operator--

    Synopsis

                iterator
    operator--(int) noexcept;
            
    [#]

    Function decode_view:: decode_view

    Constructor

    Synopsis

                constexpr
    decode_view() noexcept = default;
            

    Description

    Default-constructed views represent empty strings.

    Example

    decode_view ds;

    Postconditions

    this->empty() == true

    Complexity

    Constant.

    Exception Safety

    Throws nothing.

    [#]

    Function decode_view:: decode_view

    Constructor

    Synopsis

                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.

    Example

    decode_view ds( "Program%20Files" );

    Postconditions

    this->encoded() == s

    Complexity

    Linear in `s.size()`.

    Exception Safety

    Exceptions thrown on invalid input.

    [#]

    Function decode_view:: starts_with

    Checks if the string begins with the given prefix

    Synopsis

                bool
    starts_with(core::string_view s) const noexcept;
            

    Description

    Example

    assert( decode_view( "Program%20Files" ).starts_with("Program") );

    Complexity

    Linear.

    Exception Safety

    Throws nothing.

    [#]

    Function decode_view:: starts_with

    Checks if the string begins with the given prefix

    Synopsis

                bool
    starts_with(char ch) const noexcept;
            

    Description

    Example

    assert( decode_view( "Program%20Files" ).starts_with('P') );

    Complexity

    Constant.

    Exception Safety

    Throws nothing.

    [#]

    Function decode_view:: ends_with

    Checks if the string ends with the given prefix

    Synopsis

                bool
    ends_with(core::string_view s) const noexcept;
            

    Description

    Example

    assert( decode_view( "Program%20Files" ).ends_with("Files") );

    Complexity

    Linear.

    Exception Safety

    Throws nothing.

    [#]

    Function decode_view:: ends_with

    Checks if the string ends with the given prefix

    Synopsis

                bool
    ends_with(char ch) const noexcept;
            

    Description

    Example

    assert( decode_view( "Program%20Files" ).ends_with('s') );

    Complexity

    Constant.

    Exception Safety

    Throws nothing.

    [#]

    Function decode_view:: compare

    Return the result of comparing to another string

    Synopsis

                int
    compare(core::string_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.data(), rlen)`. This means the comparison is performed with percent-decoding applied to the current string.

    [#]

    Function decode_view:: compare

    Return the result of comparing to another string

    Synopsis

                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.

    [#]

    Function pct_string_view:: pct_string_view

    Constructor

    Synopsis

                constexpr
    pct_string_view() = default;
            

    Description

    Default constructed string are empty.

    Complexity

    Constant.

    Exception Safety

    Throws nothing.

    [#]

    Function pct_string_view:: pct_string_view

    Constructor

    Synopsis

                constexpr
    pct_string_view(pct_string_view const& other) = default;
            

    Description

    The copy references the same underlying character buffer. Ownership is not transferred.

    Postconditions

    this->data() == other.data()

    Complexity

    Constant.

    Exception Safety

    Throws nothing.

    other The string to copy.

    [#]

    Function pct_string_view:: pct_string_view

    Synopsis

                template<
        class String,
        class = void>
    pct_string_view(String const& s);
            
    [#]

    Function pct_string_view:: pct_string_view

    Constructor (deleted)

    Synopsis

                pct_string_view(std::nullptr_t) = delete;
            
    [#]

    Function pct_string_view:: pct_string_view

    Constructor

    Synopsis

                pct_string_view(
        char const* s,
        std::size_t len);
            

    Description

    The newly constructed string references the specified character buffer. Ownership is not transferred.

    Postconditions

    this->data() == s && this->size() == len

    Complexity

    Linear in `len`.

    Exception Safety

    Exceptions thrown on invalid input.

    [#]

    Function pct_string_view:: pct_string_view

    Constructor

    Synopsis

                pct_string_view(core::string_view s);
            

    Description

    The newly constructed string references the specified character buffer. Ownership is not transferred.

    Postconditions

    this->data() == s.data() && this->size() == s.size()

    Complexity

    Linear in `s.size()`.

    Exception Safety

    Exceptions thrown on invalid input.

    [#]

    Function operator<

    Synopsis

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

    Function operator<

    Return the result of comparing two authorities The authorities are compared component by component as if they were first normalized.

    Synopsis

                bool
    operator<(
        authority_view const& a0,
        authority_view const& a1) noexcept;
            

    Description

    Complexity

    Linear in `min( a0.size(), a1.size() )`

    Exception Safety

    Throws nothing

    [#]

    Function operator<

    Return the result of comparing two URLs

    Synopsis

                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.

    Example

    url_view u0( "http://www.a.com/index.htm" ); url_view u1( "http://www.b.com/index.htm" ); assert( u0 < u1 );

    Effects

    url a(u0); a.normalize(); url b(u1); b.normalize(); return std::make_tuple( a.scheme(), a.user(), a.password(), a.host(), a.port(), a.path(), a.query(), a.fragment()) < std::make_tuple( b.scheme(), b.user(), b.password(), b.host(), b.port(), b.path(), b.query(), b.fragment());

    Complexity

    Linear in `min( u0.size(), u1.size() )`

    Exception Safety

    Throws nothing

    Specification

  • 6.2.2 Syntax-Based Normalization (rfc3986)
  • [#]

    Function operator<=

    Synopsis

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

    Function operator<=

    Return the result of comparing two authorities The authorities are compared component by component as if they were first normalized.

    Synopsis

                bool
    operator<=(
        authority_view const& a0,
        authority_view const& a1) noexcept;
            

    Description

    Complexity

    Linear in `min( a0.size(), a1.size() )`

    Exception Safety

    Throws nothing

    [#]

    Function operator<=

    Return the result of comparing two URLs

    Synopsis

                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.

    Example

    url_view u0( "http://www.b.com/index.htm" ); url_view u1( "http://www.b.com/index.htm" ); assert( u0 <= u1 );

    Effects

    url a(u0); a.normalize(); url b(u1); b.normalize(); return std::make_tuple( a.scheme(), a.user(), a.password(), a.host(), a.port(), a.path(), a.query(), a.fragment()) <= std::make_tuple( b.scheme(), b.user(), b.password(), b.host(), b.port(), b.path(), b.query(), b.fragment());

    Complexity

    Linear in `min( u0.size(), u1.size() )`

    Exception Safety

    Throws nothing

    Specification

  • 6.2.2 Syntax-Based Normalization (rfc3986)
  • [#]

    Function operator==

    Synopsis

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

    Function operator==

    Return true if two addresses are equal

    Synopsis

                bool
    operator==(
        ipv4_address const& a1,
        ipv4_address const& a2) noexcept;
            
    [#]

    Function operator==

    Return true if two addresses are equal

    Synopsis

                bool
    operator==(
        ipv6_address const& a1,
        ipv6_address const& a2) noexcept;
            
    [#]

    Function operator==

    Return the result of comparing two authorities The authorities are compared component by component as if they were first normalized.

    Synopsis

                bool
    operator==(
        authority_view const& a0,
        authority_view const& a1) noexcept;
            

    Description

    Complexity

    Linear in `min( a0.size(), a1.size() )`

    Exception Safety

    Throws nothing

    [#]

    Function operator==

    Synopsis

                bool
    operator==(
        iterator const& it0,
        iterator const& it1) noexcept;
            
    [#]

    Function operator==

    Return the result of comparing two URLs

    Synopsis

                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.

    Example

    url_view u0( "http://www.a.com/index.htm" ); url_view u1( "http://www.a.com/index.htm" ); assert( u0 == u1 );

    Effects

    url a(u0); a.normalize(); url b(u1); b.normalize(); return std::make_tuple( a.scheme(), a.user(), a.password(), a.host(), a.port(), a.path(), a.query(), a.fragment()) == std::make_tuple( b.scheme(), b.user(), b.password(), b.host(), b.port(), b.path(), b.query(), b.fragment());

    Complexity

    Linear in `min( u0.size(), u1.size() )`

    Exception Safety

    Throws nothing

    Specification

  • 6.2.2 Syntax-Based Normalization (rfc3986)
  • [#]

    Function operator!=

    Synopsis

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

    Function operator!=

    Return true if two addresses are not equal

    Synopsis

                bool
    operator!=(
        ipv4_address const& a1,
        ipv4_address const& a2) noexcept;
            
    [#]

    Function operator!=

    Return true if two addresses are not equal

    Synopsis

                bool
    operator!=(
        ipv6_address const& a1,
        ipv6_address const& a2) noexcept;
            
    [#]

    Function operator!=

    Return the result of comparing two authorities The authorities are compared component by component as if they were first normalized.

    Synopsis

                bool
    operator!=(
        authority_view const& a0,
        authority_view const& a1) noexcept;
            

    Description

    Complexity

    Linear in `min( a0.size(), a1.size() )`

    Exception Safety

    Throws nothing

    [#]

    Function operator!=

    Synopsis

                bool
    operator!=(
        iterator const& it0,
        iterator const& it1) noexcept;
            
    [#]

    Function operator!=

    Return the result of comparing two URLs

    Synopsis

                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.

    Example

    url_view u0( "http://www.a.com/index.htm" ); url_view u1( "http://www.b.com/index.htm" ); assert( u0 != u1 );

    Effects

    url a(u0); a.normalize(); url b(u1); b.normalize(); return std::make_tuple( a.scheme(), a.user(), a.password(), a.host(), a.port(), a.path(), a.query(), a.fragment()) != std::make_tuple( b.scheme(), b.user(), b.password(), b.host(), b.port(), b.path(), b.query(), b.fragment());

    Complexity

    Linear in `min( u0.size(), u1.size() )`

    Exception Safety

    Throws nothing

    Specification

  • 6.2.2 Syntax-Based Normalization (rfc3986)
  • [#]

    Function operator>

    Synopsis

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

    Function operator>

    Return the result of comparing two authorities The authorities are compared component by component as if they were first normalized.

    Synopsis

                bool
    operator>(
        authority_view const& a0,
        authority_view const& a1) noexcept;
            

    Description

    Complexity

    Linear in `min( a0.size(), a1.size() )`

    Exception Safety

    Throws nothing

    [#]

    Function operator>

    Return the result of comparing two URLs

    Synopsis

                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.

    Example

    url_view u0( "http://www.b.com/index.htm" ); url_view u1( "http://www.a.com/index.htm" ); assert( u0 > u1 );

    Effects

    url a(u0); a.normalize(); url b(u1); b.normalize(); return std::make_tuple( a.scheme(), a.user(), a.password(), a.host(), a.port(), a.path(), a.query(), a.fragment()) > std::make_tuple( b.scheme(), b.user(), b.password(), b.host(), b.port(), b.path(), b.query(), b.fragment());

    Complexity

    Linear in `min( u0.size(), u1.size() )`

    Exception Safety

    Throws nothing

    Specification

  • 6.2.2 Syntax-Based Normalization (rfc3986)
  • [#]

    Function operator>=

    Synopsis

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

    Function operator>=

    Return the result of comparing two authorities The authorities are compared component by component as if they were first normalized.

    Synopsis

                bool
    operator>=(
        authority_view const& a0,
        authority_view const& a1) noexcept;
            

    Description

    Complexity

    Linear in `min( a0.size(), a1.size() )`

    Exception Safety

    Throws nothing

    [#]

    Function operator>=

    Return the result of comparing two URLs

    Synopsis

                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.

    Example

    url_view u0( "http://www.a.com/index.htm" ); url_view u1( "http://www.a.com/index.htm" ); assert( u0 >= u1 );

    Effects

    url a(u0); a.normalize(); url b(u1); b.normalize(); return std::make_tuple( a.scheme(), a.user(), a.password(), a.host(), a.port(), a.path(), a.query(), a.fragment()) >= std::make_tuple( b.scheme(), b.user(), b.password(), b.host(), b.port(), b.path(), b.query(), b.fragment());

    Complexity

    Linear in `min( u0.size(), u1.size() )`

    Exception Safety

    Throws nothing

    Specification

  • 6.2.2 Syntax-Based Normalization (rfc3986)
  • [#]

    Function encode

    Apply percent-encoding to a string

    Synopsis

                template
    std::size_t
    encode(
        char* dest,
        std::size_t size,
        core::string_view s,
        CharSet const& unreserved,
        encoding_opts opt = = {});
            

    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.

    Example

    char buf[100]; assert( encode( buf, sizeof(buf), "Program Files", pchars ) == 15 );

    Exception Safety

    Throws nothing.

    Specification

  • 2.1. Percent-Encoding (rfc3986)
  • [#]

    Function encode

    Return a percent-encoded string

    Synopsis

                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.

    Example

    encoding_opts opt; opt.space_as_plus = true; std::string s = encode( "My Stuff", opt, pchars ); assert( s == "My+Stuff" );

    Exception Safety

    Calls to allocate may throw.

    Specification

  • 2.1. Percent-Encoding (rfc3986)
  • [#]

    Function param_pct_view:: param_pct_view

    Constructor

    Synopsis

                constexpr
    param_pct_view() = default;
            

    Description

    Default constructed query parameters have an empty key and no value.

    Example

    param_pct_view qp;

    Postconditions

    this->key == "" && this->value == "" && this->has_value == false

    Complexity

    Constant.

    Exception Safety

    Throws nothing.

    [#]

    Function param_pct_view:: param_pct_view

    Constructor

    Synopsis

                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.

    Example

    param_pct_view qp( "key", "value" );

    Postconditions

    this->key.data() == key.data() && this->value.data() == value.data() && this->has_value == true

    Complexity

    Linear in `key.size() + value.size()`.

    Exception Safety

    Exceptions thrown on invalid input.

    [#]

    Function param_pct_view:: param_pct_view

    Constructor

    Synopsis

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

    Example

    param_pct_view qp( "key", optional("value") );

    Postconditions

    this->key.data() == key.data() && this->value->data() == value->data() && this->has_value == true

    Complexity

    Linear in `key.size() + value->size()`.

    Exception Safety

    Exceptions thrown on invalid input.

    [#]

    Function param_pct_view:: param_pct_view

    Construction

    Synopsis

                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.

    Example

    param_pct_view qp( param_view( "key", "value" ) );

    Complexity

    Linear in `key.size() + value.size()`.

    Exception Safety

    Exceptions thrown on invalid input.

    [#]

    Function param_pct_view:: param_pct_view

    Synopsis

                param_pct_view(
        pct_string_view key,
        pct_string_view value,
        bool has_value) noexcept;
            
    [#]

    Function param_view:: param_view

    Constructor

    Synopsis

                constexpr
    param_view() = default;
            

    Description

    Default constructed query parameters have an empty key and no value.

    Example

    param_view qp;

    Postconditions

    this->key == "" && this->value == "" && this->has_value == false

    Complexity

    Constant.

    Exception Safety

    Throws nothing.

    [#]

    Function param_view:: param_view

    Constructor

    Synopsis

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

    Example

    param_view qp( "key", "value" );

    Postconditions

    this->key.data() == key.data() && this->value.data() == value.data() && this->has_value == true

    Complexity

    Constant.

    Exception Safety

    Throws nothing.

    [#]

    Function param_view:: param_view

    Constructor

    Synopsis

                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.

    Example

    param qp( "key", "value" ); param_view qpv( qp );

    Postconditions

    this->key == key && this->value == value && this->has_value == other.has_value

    Complexity

    Constant.

    Exception Safety

    Throws nothing.

    [#]

    Function param_view:: param_view

    Synopsis

                param_view(
        core::string_view key_,
        core::string_view value_,
        bool has_value_) noexcept;
            
    [#]

    Function operator<<

    Format the string with percent-decoding applied to the output stream

    Synopsis

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

    Description

    This function serializes the decoded view to the output stream.

    [#]

    Function operator<<

    Format the address to an output stream.

    Synopsis

                std::ostream&
    operator<<(
        std::ostream& os,
        ipv4_address const& addr);
            

    Description

    IPv4 addresses written to output streams are written in their dotted decimal format.

    [#]

    Function operator<<

    Format the address to an output stream

    Synopsis

                std::ostream&
    operator<<(
        std::ostream& os,
        ipv6_address const& addr);
            

    Description

    This function writes the address to an output stream using standard notation.

    [#]

    Function operator<<

    Format the encoded authority to the output stream

    Synopsis

                std::ostream&
    operator<<(
        std::ostream& os,
        authority_view const& a);
            

    Description

    This function serializes the encoded URL to the output stream.

    Example

    authority_view a( "www.example.com" ); std::cout << a << std::endl;
    [#]

    Function operator<<

    Format to an output stream

    Synopsis

                std::ostream&
    operator<<(
        std::ostream& os,
        segments_encoded_base const& ps);
            

    Description

    Any percent-escapes are emitted as-is; no decoding is performed.

    Complexity

    Linear in `ps.buffer().size()`.

    Effects

    return os << ps.buffer();
    [#]

    Function operator<<

    Format to an output stream

    Synopsis

                std::ostream&
    operator<<(
        std::ostream& os,
        segments_base const& ps);
            

    Description

    Any percent-escapes are emitted as-is; no decoding is performed.

    Complexity

    Linear in `ps.buffer().size()`.

    Effects

    return os << ps.buffer();
    [#]

    Function operator<<

    Format to an output stream

    Synopsis

                std::ostream&
    operator<<(
        std::ostream& os,
        params_encoded_base const& qp);
            

    Description

    Any percent-escapes are emitted as-is; no decoding is performed.

    Complexity

    Linear in `ps.buffer().size()`.

    Effects

    return os << ps.buffer();
    [#]

    Function operator<<

    Format to an output stream

    Synopsis

                std::ostream&
    operator<<(
        std::ostream& os,
        params_base const& qp);
            

    Description

    Any percent-escapes are emitted as-is; no decoding is performed.

    Complexity

    Linear in `ps.buffer().size()`.

    Effects

    return os << ps.buffer();
    [#]

    Function operator<<

    Format the url to the output stream

    Synopsis

                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.

    Example

    url_view u( "http://www.example.com/index.htm" ); std::stringstream ss; ss << u; assert( ss.str() == "http://www.example.com/index.htm" );

    Effects

    return os << u.buffer();

    Complexity

    Linear in `u.buffer().size()`

    Exception Safety

    Basic guarantee.

    [#]

    Function param:: param

    Constructor

    Synopsis

                param() = default;
            

    Description

    Default constructed query parameters have an empty key and no value.

    Example

    param qp;

    Postconditions

    this->key == "" && this->value == "" && this->has_value == false

    Complexity

    Constant.

    Exception Safety

    Throws nothing.

    [#]

    Function param:: param

    Constructor

    Synopsis

                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.

    Complexity

    Constant.

    Exception Safety

    Throws nothing.

    other The object to construct from.

    [#]

    Function param:: param

    Constructor

    Synopsis

                param(param const& other) = default;
            

    Description

    Upon construction, this becomes a copy of `other`.

    Postconditions

    this->key == other.key && this->value == other.value && this->has_value == other.has_value

    Complexity

    Linear in `other.key.size() + other.value.size()`.

    Exception Safety

    Calls to allocate may throw.

    other The object to construct from.

    [#]

    Function param:: param

    Constructor

    Synopsis

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

    Example

    param qp( "key", "value" ); param qp( "key", optional("value") ); param qp( "key", boost::none ); param qp( "key", nullptr ); param qp( "key", no_value );

    Postconditions

    this->key == key && this->value == value && this->has_value == true

    Complexity

    Linear in `key.size() + value.size()`.

    Exception Safety

    Calls to allocate may throw.

    [#]

    Function param:: param

    Synopsis

                param(
        core::string_view key,
        core::string_view value,
        bool has_value) noexcept;
            
    [#]

    Function param:: operator=

    Assignment

    Synopsis

                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.

    Complexity

    Constant.

    Exception Safety

    Throws nothing.

    other The object to assign from.

    [#]

    Function param:: operator=

    Assignment

    Synopsis

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

    Description

    Upon assignment, this becomes a copy of `other`.

    Postconditions

    this->key == other.key && this->value == other.value && this->has_value == other.has_value

    Complexity

    Linear in `other.key.size() + other.value.size()`.

    Exception Safety

    Calls to allocate may throw.

    other The object to assign from.

    [#]

    Function param:: operator=

    Assignment

    Synopsis

                param&
    operator=(param_view const& other);
            

    Description

    The members of `other` are copied, re-using already existing string capacity.

    Postconditions

    this->key == other.key && this->value == other.value && this->has_value == other.has_value

    Complexity

    Linear in `other.key.size() + other.value.size()`.

    Exception Safety

    Calls to allocate may throw.

    [#]

    Function param:: operator=

    Assignment

    Synopsis

                param&
    operator=(param_pct_view const& other);
            

    Description

    The members of `other` are copied, re-using already existing string capacity.

    Postconditions

    this->key == other.key && this->value == other.value && this->has_value == other.has_value

    Complexity

    Linear in `other.key.size() + other.value.size()`.

    Exception Safety

    Calls to allocate may throw.

    [#]

    Function ipv4_address:: ipv4_address

    Constructor.

    Synopsis

                constexpr
    ipv4_address() = default;
            
    [#]

    Function ipv4_address:: ipv4_address

    Constructor.

    Synopsis

                constexpr
    ipv4_address(ipv4_address const&) = default;
            
    [#]

    Function ipv4_address:: ipv4_address

    Construct from an unsigned integer.

    Synopsis

                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.

    [#]

    Function ipv4_address:: ipv4_address

    Construct from an array of bytes.

    Synopsis

                ipv4_address(bytes_type const& bytes) noexcept;
            

    Description

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

    [#]

    Function ipv4_address:: ipv4_address

    Construct from a string.

    Synopsis

                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 .

    Exception Safety

    Exceptions thrown on invalid input.

    Specification

  • 3.2.2. Host (rfc3986)
  • [#]

    Function ipv6_address:: ipv6_address

    Constructor.

    Synopsis

                constexpr
    ipv6_address() = default;
            

    Description

    Default constructed objects represent the unspecified address.

  • 2.5.2. The Unspecified Address
  • [#]

    Function ipv6_address:: ipv6_address

    Constructor.

    Synopsis

                constexpr
    ipv6_address(ipv6_address const&) = default;
            
    [#]

    Function ipv6_address:: ipv6_address

    Construct from an array of bytes.

    Synopsis

                ipv6_address(bytes_type const& bytes) noexcept;
            

    Description

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

    [#]

    Function ipv6_address:: ipv6_address

    Construct from an IPv4 address.

    Synopsis

                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.

    Specification

  • 2.5.5.2. IPv4-Mapped IPv6 Address (rfc4291)
  • [#]

    Function ipv6_address:: ipv6_address

    Construct from a string.

    Synopsis

                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 .

    Exception Safety

    Exceptions thrown on invalid input.

    Specification

  • 3.2.2. Host (rfc3986)
  • [#]

    Function url_view:: operator=

    Assignment

    Synopsis

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

    Description

    After assignment, both views reference the same underlying character buffer. Ownership is not transferred.

    Postconditions

    this->buffer().data() == other.buffer().data()

    Complexity

    Constant.

    Exception Safety

    Throws nothing.

    [#]

    Function url_view:: operator=

    Assignment

    Synopsis

                url_view&
    operator=(url_view_base const& other) noexcept;
            

    Description

    After assignment, both views reference the same underlying character buffer. Ownership is not transferred.

    Postconditions

    this->buffer().data() == other.buffer().data()

    Complexity

    Constant.

    Exception Safety

    Throws nothing.

    [#]

    Function authority_view:: authority_view

    Constructor

    Synopsis

                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.

    Exception Safety

    Throws nothing.

    Specification

    [#]

    Function authority_view:: authority_view

    Construct from a string.

    Synopsis

                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.

    BNF

    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

    Specification

  • 3.2. Authority (rfc3986)
  • [#]

    Function authority_view:: authority_view

    Constructor

    Synopsis

                authority_view(authority_view const&) noexcept;
            
    [#]

    Function url_view:: url_view

    Constructor

    Synopsis

                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.

    Example

    url_view u;

    Postconditions

    this->empty() == true

    Complexity

    Constant.

    Exception Safety

    Throws nothing.

    BNF

    relative-ref = relative-part [ "?" query ] [ "#" fragment ]

    Specification

    4.2. Relative Reference (rfc3986)

    [#]

    Function url_view:: url_view

    Constructor

    Synopsis

                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.

    Example

    url_view u( "http://www.example.com/index.htm" );

    Effects

    return parse_uri_reference( s ).value();

    Complexity

    Linear in `s.size()`.

    Exception Safety

    Exceptions thrown on invalid input.

    BNF

    URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ] relative-ref = relative-part [ "?" query ] [ "#" fragment ]

    Specification

  • 4.1. URI Reference
  • [#]

    Function url_view:: url_view

    Synopsis

                template<
        class String,
        class = void>
    url_view(String const& s);
            
    [#]

    Function url_view:: url_view

    Constructor

    Synopsis

                url_view(url_view const& other) noexcept;
            

    Description

    After construction, both views reference the same underlying character buffer. Ownership is not transferred.

    Postconditions

    this->buffer().data() == other.buffer().data()

    Complexity

    Constant.

    Exception Safety

    Throws nothing.

    [#]

    Function url_view:: url_view

    Constructor

    Synopsis

                url_view(url_view_base const& other) noexcept;
            

    Description

    After construction, both views reference the same underlying character buffer. Ownership is not transferred.

    Postconditions

    this->buffer().data() == other.buffer().data()

    Complexity

    Constant.

    Exception Safety

    Throws nothing.

    [#]

    Function ignore_case_param:: ignore_case_param

    Constructor

    Synopsis

                constexpr
    ignore_case_param() noexcept = default;
            

    Description

    By default, comparisons are case-sensitive.

    Example

    This function performs case-sensitive comparisons when called with no arguments:

    void f( ignore_case_param = {} );
    [#]

    Function ignore_case_param:: ignore_case_param

    Constructor

    Synopsis

                constexpr
    ignore_case_param(ignore_case_t) noexcept;
            

    Description

    Construction from ignore_case indicates that comparisons should be case-insensitive.

    Example

    When ignore_case is passed as an argument, this function ignores case when performing comparisons:

    void f( ignore_case_param = {} );
    [#]

    Function segments_encoded_base:: iterator:: iterator

    Synopsis

                constexpr
    iterator() = default;
            
    [#]

    Function segments_encoded_base:: iterator:: iterator

    Synopsis

                constexpr
    iterator(iterator const&) = default;
            
    [#]

    Function segments_encoded_base:: iterator:: operator++

    Synopsis

                iterator&
    operator++() noexcept;
            
    [#]

    Function segments_encoded_base:: iterator:: operator++

    Synopsis

                iterator
    operator++(int) noexcept;
            
    [#]

    Function segments_encoded_base:: iterator:: operator--

    Synopsis

                iterator&
    operator--() noexcept;
            
    [#]

    Function segments_encoded_base:: iterator:: operator--

    Synopsis

                iterator
    operator--(int) noexcept;
            
    [#]

    Function segments_base:: iterator:: iterator

    Synopsis

                constexpr
    iterator() = default;
            
    [#]

    Function segments_base:: iterator:: iterator

    Synopsis

                constexpr
    iterator(iterator const&) = default;
            
    [#]

    Function segments_base:: iterator:: operator++

    Synopsis

                iterator&
    operator++() noexcept;
            
    [#]

    Function segments_base:: iterator:: operator++

    Synopsis

                iterator
    operator++(int) noexcept;
            
    [#]

    Function segments_base:: iterator:: operator--

    Synopsis

                iterator&
    operator--() noexcept;
            
    [#]

    Function segments_base:: iterator:: operator--

    Synopsis

                iterator
    operator--(int) noexcept;
            
    [#]

    Function segments_view:: segments_view

    Constructor

    Synopsis

                constexpr
    segments_view() = default;
            

    Description

    Default-constructed segments have zero elements.

    Example

    segments_view ps;

    Effects

    return segments_view( "" );

    Complexity

    Constant.

    Exception Safety

    Throws nothing.

    [#]

    Function segments_view:: segments_view

    Constructor

    Synopsis

                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.

    Postconditions

    this->buffer().data() == other.buffer().data()

    Complexity

    Constant

    Exception Safety

    Throws nothing

    [#]

    Function segments_view:: segments_view

    Constructor

    Synopsis

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

    Example

    segments_view ps( "/path/to/file.txt" );

    Effects

    return parse_path( s ).value();

    Postconditions

    this->buffer().data() == s.data()

    Complexity

    Linear in `s`.

    Exception Safety

    Exceptions thrown on invalid input.

    BNF

    path = [ "/" ] [ segment *( "/" segment ) ] segment = *pchar

    Specification

  • 3.3. Path
  • [#]

    Function segments_encoded_view:: segments_encoded_view

    Constructor

    Synopsis

                constexpr
    segments_encoded_view() = default;
            

    Description

    Default-constructed segments have zero elements.

    Example

    segments_encoded_view ps;

    Effects

    return segments_encoded_view( "" );

    Complexity

    Constant.

    Exception Safety

    Throws nothing.

    [#]

    Function segments_encoded_view:: segments_encoded_view

    Constructor

    Synopsis

                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.

    Postconditions

    this->buffer().data() == other.buffer().data()

    Complexity

    Constant.

    Exception Safety

    Throws nothing

    [#]

    Function segments_encoded_view:: segments_encoded_view

    Constructor

    Synopsis

                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.

    Example

    segments_encoded_view ps( "/path/to/file.txt" );

    Effects

    return parse_path( s ).value();

    Postconditions

    this->buffer().data() == s.data()

    Complexity

    Linear in `s`.

    Exception Safety

    Exceptions thrown on invalid input.

    BNF

    path = [ "/" ] [ segment *( "/" segment ) ] segment = *pchar

    Specification

  • 3.3. Path
  • [#]

    Function pct_encoded_rule

    Synopsis

                template
    constexpr
    pct_encoded_rule_t
    pct_encoded_rule(CharSet_ const& cs) noexcept;
            
    [#]

    Function pct_encoded_rule

    Synopsis

                template
    constexpr
    pct_encoded_rule_t
    pct_encoded_rule(CharSet const& cs) noexcept;
            
    [#]

    Function params_encoded_base:: iterator:: iterator

    Synopsis

                iterator() = default;
            
    [#]

    Function params_encoded_base:: iterator:: iterator

    Synopsis

                constexpr
    iterator(iterator const&) = default;
            
    [#]

    Function params_encoded_base:: iterator:: operator++

    Synopsis

                iterator&
    operator++() noexcept;
            
    [#]

    Function params_encoded_base:: iterator:: operator++

    Synopsis

                iterator
    operator++(int) noexcept;
            
    [#]

    Function params_encoded_base:: iterator:: operator--

    Synopsis

                iterator&
    operator--() noexcept;
            
    [#]

    Function params_encoded_base:: iterator:: operator--

    Synopsis

                iterator
    operator--(int) noexcept;
            
    [#]

    Function params_encoded_base:: find_last

    Find a matching key

    Synopsis

                iterator
    find_last(
        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.

    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.

    Example

    assert( url_view( "?first=John&last=Doe" ).encoded_params().find_last( "last" )->value == "Doe" );

    Complexity

    Linear in `this->buffer().size()`.

    Exception Safety

    Exceptions thrown on invalid input.

    [#]

    Function params_encoded_base:: find_last

    Find a matching key

    Synopsis

                iterator
    find_last(
        iterator before,
        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.

    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.

    Example

    url_view u( "?First=John&Last=Doe" ); assert( u.encoded_params().find_last( "last" ) != u.encoded_params().find_last( "last", ignore_case ) );

    Complexity

    Linear in `this->buffer().size()`.

    [#]

    Function params_encoded_base:: find

    Find a matching key

    Synopsis

                iterator
    find(
        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.

    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.

    Example

    assert( url_view( "?first=John&last=Doe" ).encoded_params().find( "First", ignore_case )->value == "John" );

    Effects

    return this->find( this->begin(), key, ic );

    Complexity

    Linear in `this->buffer().size()`.

    Exception Safety

    Exceptions thrown on invalid input.

    [#]

    Function params_encoded_base:: find

    Find a matching key

    Synopsis

                iterator
    find(
        iterator from,
        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.

    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.

    Example

    url_view u( "?First=John&Last=Doe" ); assert( u.encoded_params().find( "first" ) != u.encoded_params().find( "first", ignore_case ) );

    Complexity

    Linear in `this->buffer().size()`.

    Exception Safety

    Exceptions thrown on invalid input.

    [#]

    Function params_ref:: params_ref

    Constructor

    Synopsis

                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.

    Postconditions

    &this->url() == &other.url()

    Complexity

    Constant.

    Exception Safety

    Throws nothing.

    [#]

    Function params_ref:: params_ref

    Constructor

    Synopsis

                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.

    Postconditions

    &this->url() == &other.url()

    Complexity

    Constant.

    Exception Safety

    Throws nothing.

    [#]

    Function params_ref:: operator=

    Assignment

    Synopsis

                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.

    Effects

    this->assign( other.begin(), other.end() );

    Complexity

    Linear in `other.buffer().size()`.

    Exception Safety

    Strong guarantee. Calls to allocate may throw.

    [#]

    Function params_ref:: operator=

    Assignment

    Synopsis

                params_ref&
    operator=(std::initializer_list init);
            

    Description

    After assignment, the previous contents of the query parameters are replaced by the contents of the initializer-list.

    Preconditions

    None of character buffers referenced by `init` may overlap the character buffer of the underlying url, or else the behavior is undefined.

    Effects

    this->assign( init );

    Complexity

    Linear in `init.size()`.

    Exception Safety

    Strong guarantee. Calls to allocate may throw.

    [#]

    Function params_ref:: assign

    Assign elements

    Synopsis

                void
    assign(std::initializer_list 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.

    Example

    url u; u.params().assign( {{ "first", "John" }, { "last", "Doe" }} );

    Complexity

    Linear in `init.size()`.

    Exception Safety

    Strong guarantee. Calls to allocate may throw.

    [#]

    Function params_ref:: assign

    Assign elements

    Synopsis

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

    Mandates

    std::is_convertible< std::iterator_traits< FwdIt >::reference_type, param_view >::value == true

    Complexity

    Linear in the size of the range.

    Exception Safety

    Strong guarantee. Calls to allocate may throw.

    [#]

    Function params_ref:: append

    Append elements

    Synopsis

                iterator
    append(param_view const& p);
            

    Description

    This function appends a param to the view.

    The `end()` iterator is invalidated.

    Example

    url u; u.params().append( { "first", "John" } );

    Complexity

    Linear in `this->url().encoded_query().size()`.

    Exception Safety

    Strong guarantee. Calls to allocate may throw.

    [#]

    Function params_ref:: append

    Append elements

    Synopsis

                iterator
    append(std::initializer_list init);
            

    Description

    This function appends the params in an initializer-list to the view.

    The `end()` iterator is invalidated.

    Example

    url u; u.params().append({ { "first", "John" }, { "last", "Doe" } });

    Complexity

    Linear in `this->url().encoded_query().size()`.

    Exception Safety

    Strong guarantee. Calls to allocate may throw.

    [#]

    Function params_ref:: append

    Append elements

    Synopsis

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

    Mandates

    std::is_convertible< std::iterator_traits< FwdIt >::reference_type, param_view >::value == true

    Complexity

    Linear in `this->url().encoded_query().size()`.

    Exception Safety

    Strong guarantee. Calls to allocate may throw.

    [#]

    Function params_ref:: erase

    Erase elements

    Synopsis

                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.

    Example

    url u( "?first=John&last=Doe" ); params_ref::iterator it = u.params().erase( u.params().begin() ); assert( u.encoded_query() == "last=Doe" );

    Complexity

    Linear in `this->url().encoded_query().size()`.

    Exception Safety

    Throws nothing.

    [#]

    Function params_ref:: erase

    Erase elements

    Synopsis

                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.

    Complexity

    Linear in `this->url().encoded_query().size()`.

    Exception Safety

    Throws nothing.

    [#]

    Function params_ref:: erase

    Erase elements

    Synopsis

                std::size_t
    erase(
        core::string_view key,
        ignore_case_param ic = = {}) noexcept;
            

    Description

    All iterators are invalidated.

    Postconditions

    this->count( key, ic ) == 0

    Complexity

    Linear in `this->url().encoded_query().size()`.

    Exception Safety

    Throws nothing.

    [#]

    Function params_ref:: insert

    Insert elements

    Synopsis

                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.

    Complexity

    Linear in `this->url().encoded_query().size()`.

    Exception Safety

    Strong guarantee. Calls to allocate may throw.

    [#]

    Function params_ref:: insert

    Insert elements

    Synopsis

                iterator
    insert(
        iterator before,
        std::initializer_list 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.

    Complexity

    Linear in `this->url().encoded_query().size()`.

    Exception Safety

    Strong guarantee. Calls to allocate may throw.

    [#]

    Function params_ref:: insert

    Insert elements

    Synopsis

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

    Mandates

    std::is_convertible< std::iterator_traits< FwdIt >::reference_type, param_view >::value == true

    Complexity

    Linear in `this->url().encoded_query().size()`.

    Exception Safety

    Strong guarantee. Calls to allocate may throw.

    [#]

    Function params_ref:: set

    Set a value

    Synopsis

                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.

    Example

    url u( "?id=42&id=69" ); u.params().set( u.params().begin(), "none" ); assert( u.encoded_query() == "id=none&id=69" );

    Complexity

    Linear in `this->url().encoded_query().size()`.

    Exception Safety

    Strong guarantee. Calls to allocate may throw.

    [#]

    Function params_ref:: set

    Set a value

    Synopsis

                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.

    Example

    url u( "?id=42&id=69" ); u.params().set( "id", "none" ); assert( u.params().count( "id" ) == 1 );

    Postconditions

    this->count( key, ic ) == 1 && this->find( key, ic )->value == value

    Complexity

    Linear in `this->url().encoded_query().size()`.

    Exception Safety

    Strong guarantee. Calls to allocate may throw.

    [#]

    Function params_ref:: replace

    Replace elements

    Synopsis

                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.

    Example

    url u( "?first=John&last=Doe" ); u.params().replace( u.params().begin(), { "title", "Mr" }); assert( u.encoded_query() == "title=Mr&last=Doe" );

    Complexity

    Linear in `this->url().encoded_query().size()`.

    Exception Safety

    Strong guarantee. Calls to allocate may throw.

    [#]

    Function params_ref:: replace

    Replace elements

    Synopsis

                iterator
    replace(
        iterator from,
        iterator to,
        std::initializer_list 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.

    Complexity

    Linear in `this->url().encoded_query().size()`.

    Exception Safety

    Strong guarantee. Calls to allocate may throw.

    [#]

    Function params_ref:: replace

    Replace elements

    Synopsis

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

    Mandates

    std::is_convertible< std::iterator_traits< FwdIt >::reference_type, param_view >::value == true

    Complexity

    Linear in `this->url().encoded_query().size()`.

    Exception Safety

    Strong guarantee. Calls to allocate may throw.

    [#]

    Function params_base:: iterator:: iterator

    Synopsis

                iterator() = default;
            
    [#]

    Function params_base:: iterator:: iterator

    Synopsis

                constexpr
    iterator(iterator const&) = default;
            
    [#]

    Function params_base:: iterator:: operator++

    Synopsis

                iterator&
    operator++() noexcept;
            
    [#]

    Function params_base:: iterator:: operator++

    Synopsis

                iterator
    operator++(int) noexcept;
            
    [#]

    Function params_base:: iterator:: operator--

    Synopsis

                iterator&
    operator--() noexcept;
            
    [#]

    Function params_base:: iterator:: operator--

    Synopsis

                iterator
    operator--(int) noexcept;
            
    [#]

    Function params_base:: find

    Find a matching key

    Synopsis

                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.

    Example

    assert( (*url_view( "?first=John&last=Doe" ).params().find( "First", ignore_case )).value == "John" );

    Effects

    return this->find( this->begin(), key, ic );

    Complexity

    Linear in `this->buffer().size()`.

    [#]

    Function params_base:: find

    Find a matching key

    Synopsis

                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.

    Example

    url_view u( "?First=John&Last=Doe" ); assert( u.params().find( "first" ) != u.params().find( "first", ignore_case ) );

    Complexity

    Linear in `this->buffer().size()`.

    [#]

    Function params_base:: find_last

    Find a matching key

    Synopsis

                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.

    Example

    assert( (*url_view( "?first=John&last=Doe" ).params().find_last( "last" )).value == "Doe" );

    Complexity

    Linear in `this->buffer().size()`.

    [#]

    Function params_base:: find_last

    Find a matching key

    Synopsis

                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.

    Example

    url_view u( "?First=John&Last=Doe" ); assert( u.params().find_last( "last" ) != u.params().find_last( "last", ignore_case ) );

    Complexity

    Linear in `this->buffer().size()`.

    [#]

    Function params_encoded_view:: params_encoded_view

    Constructor

    Synopsis

                constexpr
    params_encoded_view() = default;
            

    Description

    Default-constructed params have zero elements.

    Example

    params_encoded_view qp;

    Effects

    return params_encoded_view( "" );

    Complexity

    Constant.

    Exception Safety

    Throws nothing.

    [#]

    Function params_encoded_view:: params_encoded_view

    Constructor

    Synopsis

                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.

    Postconditions

    this->buffer().data() == other.buffer().data()

    Complexity

    Constant.

    Exception Safety

    Throws nothing

    [#]

    Function params_encoded_view:: params_encoded_view

    Constructor

    Synopsis

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

    Example

    params_encoded_view qp( "first=John&last=Doe" );

    Effects

    return parse_query( s ).value();

    Postconditions

    this->buffer().data() == s.data()

    Complexity

    Linear in `s`.

    Exception Safety

    Exceptions thrown on invalid input.

    BNF

    query-params = [ query-param ] *( "&" query-param ) query-param = key [ "=" value ]

    Specification

  • 3.4. Query
  • [#]

    Function params_view:: params_view

    Constructor

    Synopsis

                params_view() = default;
            

    Description

    Default-constructed params have zero elements.

    Example

    params_view qp;

    Effects

    return params_view( "" );

    Complexity

    Constant.

    Exception Safety

    Throws nothing.

    [#]

    Function params_view:: params_view

    Constructor

    Synopsis

                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.

    Postconditions

    this->buffer().data() == other.buffer().data()

    Complexity

    Constant.

    Exception Safety

    Throws nothing

    [#]

    Function params_view:: params_view

    Constructor

    Synopsis

                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.

    Postconditions

    this->buffer().data() == other.buffer().data()

    Complexity

    Constant.

    Exception Safety

    Throws nothing

    [#]

    Function params_view:: params_view

    Constructor

    Synopsis

                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.

    Example

    params_view qp( "first=John&last=Doe" );

    Effects

    return parse_query( s ).value();

    Postconditions

    this->buffer().data() == s.data()

    Complexity

    Linear in `s`.

    Exception Safety

    Exceptions thrown on invalid input.

    BNF

    query-params = [ query-param ] *( "&" query-param ) query-param = key [ "=" value ]

    Specification

  • 3.4. Query
  • [#]

    Function params_view:: params_view

    Constructor

    Synopsis

                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.

    Example

    encoding_opts opt; opt.space_as_plus = true; params_view qp( "name=John+Doe", opt );

    Effects

    return params_view(parse_query( s ).value(), opt);

    Postconditions

    this->buffer().data() == s.data()

    Complexity

    Linear in `s`.

    Exception Safety

    Exceptions thrown on invalid input.

    BNF

    query-params = [ query-param ] *( "&" query-param ) query-param = key [ "=" value ]

    Specification

  • 3.4. Query
  • [#]

    Function url_base:: segments

    Return the path as a container of segments

    Synopsis

                segments_ref
    segments() noexcept;
            

    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.

    Example

    url u( "http://example.com/path/to/file.txt" ); segments sv = u.segments();

    Complexity

    Constant.

    Exception Safety

    Throws nothing.

    BNF

    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

    Specification

  • 3.3. Path (rfc3986)
  • [#]

    Function url_base:: segments

    Return the path as a container of segments

    Synopsis

                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.

    Example

    segments_view sv = url_view( "/path/to/file.txt" ).segments();

    Complexity

    Constant.

    Exception Safety

    Throws nothing.

    BNF

    path = [ "/" ] segment *( "/" segment )

    Specification

  • 3.3. Path (rfc3986)
  • [#]

    Function url_base:: encoded_segments

    Return the path as a container of segments

    Synopsis

                segments_encoded_ref
    encoded_segments() noexcept;
            

    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.

    Example

    url u( "http://example.com/path/to/file.txt" ); segments_encoded_ref sv = u.encoded_segments();

    Complexity

    Constant.

    Exception Safety

    Throws nothing.

    BNF

    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

    Specification

  • 3.3. Path (rfc3986)
  • [#]

    Function url_base:: encoded_segments

    Return the path as a container of segments

    Synopsis

                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.

    Example

    segments_encoded_view sv = url_view( "/path/to/file.txt" ).encoded_segments();

    Complexity

    Constant.

    Exception Safety

    Throws nothing.

    BNF

    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

    Specification

  • 3.3. Path (rfc3986)
  • [#]

    Function url_base:: encoded_params

    Return the query as a container of parameters

    Synopsis

                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.

    Example

    params_encoded_view pv = url_view( "/sql?id=42&name=jane%2Ddoe&page+size=20" ).encoded_params();

    Complexity

    Constant.

    Exception Safety

    Throws nothing.

    Specification

  • 3.4. Query (rfc3986)
  • BNF

    query = *( pchar / "/" / "?" ) query-param = key [ "=" value ] query-params = [ query-param ] *( "&" query-param )

    Specification

  • ://en.wikipedia.org/wiki/Query_string" >Query string (Wikipedia)
  • [#]

    Function url_base:: encoded_params

    Return the query as a container of parameters

    Synopsis

                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.

    Example

    params_encoded_ref pv = url( "/sql?id=42&name=jane%2Ddoe&page+size=20" ).encoded_params();

    Complexity

    Constant.

    Exception Safety

    Throws nothing.

    BNF

    query = *( pchar / "/" / "?" ) query-param = key [ "=" value ] query-params = [ query-param ] *( "&" query-param )

    Specification

  • 3.4. Query (rfc3986)
  • Query string (Wikipedia)
  • [#]

    Function url_base:: params

    Return the query as a container of parameters

    Synopsis

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

    Example

    params_ref pv = url( "/sql?id=42&name=jane%2Ddoe&page+size=20" ).params();

    Complexity

    Constant.

    Exception Safety

    Throws nothing.

    BNF

    query = *( pchar / "/" / "?" ) query-param = key [ "=" value ] query-params = [ query-param ] *( "&" query-param )

    Specification

  • 3.4. Query (rfc3986)
  • Query string (Wikipedia)
  • [#]

    Function url_base:: params

    url_view_base::params

    Synopsis

                params_view
    params() const noexcept;
            
    [#]

    Function url_base:: params

    Return the query as a container of parameters

    Synopsis

                params_ref
    params(encoding_opts opt) 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. 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.

    Example

    encoding_opts opt; opt.space_as_plus = true; params_ref pv = url( "/sql?id=42&name=jane+doe&page+size=20" ).params(opt);

    Complexity

    Constant.

    Exception Safety

    Throws nothing.

    BNF

    query = *( pchar / "/" / "?" ) query-param = key [ "=" value ] query-params = [ query-param ] *( "&" query-param )

    Specification

  • 3.4. Query (rfc3986)
  • Query string (Wikipedia)
  • [#]

    Function params_encoded_ref:: operator=

    Assignment

    Synopsis

                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.

    Effects

    this->assign( other.begin(), other.end() );

    Complexity

    Linear in `other.buffer().size()`.

    Exception Safety

    Strong guarantee. Calls to allocate may throw.

    [#]

    Function params_encoded_ref:: operator=

    Assignment

    Synopsis

                params_encoded_ref&
    operator=(std::initializer_list init);
            

    Description

    After assignment, the previous contents of the query parameters are replaced by the contents of the initializer-list.

    All iterators are invalidated.

    Preconditions

    None of character buffers referenced by `init` may overlap the character buffer of the underlying url, or else the behavior is undefined.

    Effects

    this->assign( init.begin(), init.end() );

    Complexity

    Linear in `init.size()`.

    Exception Safety

    Strong guarantee. Calls to allocate may throw. Exceptions thrown on invalid input.

    [#]

    Function params_encoded_ref:: assign

    Assign params

    Synopsis

                void
    assign(std::initializer_list 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.

    Example

    url u; u.encoded_params().assign({ { "first", "John" }, { "last", "Doe" } });

    Complexity

    Linear in `init.size()`.

    Exception Safety

    Strong guarantee. Calls to allocate may throw. Exceptions thrown on invalid input.

    [#]

    Function params_encoded_ref:: assign

    Assign params

    Synopsis

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

    Mandates

    std::is_convertible< std::iterator_traits< FwdIt >::reference_type, param_pct_view >::value == true

    Complexity

    Linear in the size of the range.

    Exception Safety

    Strong guarantee. Calls to allocate may throw. Exceptions thrown on invalid input.

    [#]

    Function params_encoded_ref:: append

    Append params

    Synopsis

                iterator
    append(param_pct_view const& p);
            

    Description

    This function appends a param to the view.

    The `end()` iterator is invalidated.

    Example

    url u; u.encoded_params().append( { "first", "John" } );

    Complexity

    Linear in `this->url().encoded_query().size()`.

    Exception Safety

    Strong guarantee. Calls to allocate may throw. Exceptions thrown on invalid input.

    [#]

    Function params_encoded_ref:: append

    Append params

    Synopsis

                iterator
    append(std::initializer_list init);
            

    Description

    This function appends the params in an initializer-list to the view.

    The `end()` iterator is invalidated.

    Example

    url u; u.encoded_params().append({ {"first", "John"}, {"last", "Doe"} });

    Complexity

    Linear in `this->url().encoded_query().size()`.

    Exception Safety

    Strong guarantee. Calls to allocate may throw. Exceptions thrown on invalid input.

    [#]

    Function params_encoded_ref:: append

    Append params

    Synopsis

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

    Mandates

    std::is_convertible< std::iterator_traits< FwdIt >::reference_type, param_pct_view >::value == true

    Complexity

    Linear in `this->url().encoded_query().size()`.

    Exception Safety

    Strong guarantee. Calls to allocate may throw. Exceptions thrown on invalid input.

    [#]

    Function params_encoded_ref:: erase

    Erase params

    Synopsis

                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.

    Example

    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" );

    Complexity

    Linear in `this->url().encoded_query().size()`.

    Exception Safety

    Throws nothing.

    [#]

    Function params_encoded_ref:: erase

    Erase params

    Synopsis

                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.

    Complexity

    Linear in `this->url().encoded_query().size()`.

    Exception Safety

    Throws nothing.

    [#]

    Function params_encoded_ref:: erase

    Erase params

    Synopsis

                std::size_t
    erase(
        pct_string_view key,
        ignore_case_param ic = = {}) noexcept;
            

    Description

    All iterators are invalidated.

    Postconditions

    this->count( key, ic ) == 0

    Complexity

    Linear in `this->url().encoded_query().size()`.

    Exception Safety

    Exceptions thrown on invalid input.

    [#]

    Function params_encoded_ref:: insert

    Insert params

    Synopsis

                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.

    Complexity

    Linear in `this->url().encoded_query().size()`.

    Exception Safety

    Strong guarantee. Calls to allocate may throw. Exceptions thrown on invalid input.

    [#]

    Function params_encoded_ref:: insert

    Insert params

    Synopsis

                iterator
    insert(
        iterator before,
        std::initializer_list 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.

    Complexity

    Linear in `this->url().encoded_query().size()`.

    Exception Safety

    Strong guarantee. Calls to allocate may throw. Exceptions thrown on invalid input.

    [#]

    Function params_encoded_ref:: insert

    Insert params

    Synopsis

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

    Mandates

    std::is_convertible< std::iterator_traits< FwdIt >::reference_type, param_pct_view >::value == true

    Complexity

    Linear in `this->url().encoded_query().size()`.

    Exception Safety

    Strong guarantee. Calls to allocate may throw. Exceptions thrown on invalid input.

    [#]

    Function params_encoded_ref:: set

    Set a value

    Synopsis

                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.

    Example

    url u( "?id=42&id=69" ); u.encoded_params().set( u.encoded_params().begin(), "none" ); assert( u.encoded_query() == "id=none&id=69" );

    Complexity

    Linear in `this->url().encoded_query().size()`.

    Exception Safety

    Strong guarantee. Calls to allocate may throw. Exceptions thrown on invalid input.

    [#]

    Function params_encoded_ref:: set

    Set a value

    Synopsis

                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.

    Example

    url u( "?id=42&id=69" ); u.encoded_params().set( "id", "none" ); assert( u.encoded_params().count( "id" ) == 1 );

    Postconditions

    this->count( key, ic ) == 1 && this->find( key, ic )->value == value

    Complexity

    Linear in `this->url().encoded_query().size()`.

    Exception Safety

    Strong guarantee. Calls to allocate may throw. Exceptions thrown on invalid input.

    [#]

    Function params_encoded_ref:: replace

    Replace params

    Synopsis

                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.

    Example

    url u( "?first=John&last=Doe" ); u.encoded_params().replace( u.encoded_params().begin(), { "title", "Mr" }); assert( u.encoded_query() == "title=Mr&last=Doe" );

    Complexity

    Linear in `this->url().encoded_query().size()`.

    Exception Safety

    Strong guarantee. Calls to allocate may throw. Exceptions thrown on invalid input.

    [#]

    Function params_encoded_ref:: replace

    Replace params

    Synopsis

                iterator
    replace(
        iterator from,
        iterator to,
        std::initializer_list 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.

    Complexity

    Linear in `this->url().encoded_query().size()`.

    Exception Safety

    Strong guarantee. Calls to allocate may throw. Exceptions thrown on invalid input.

    [#]

    Function params_encoded_ref:: replace

    Replace params

    Synopsis

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

    Mandates

    std::is_convertible< std::iterator_traits< FwdIt >::reference_type, param_pct_view >::value == true

    Complexity

    Linear in `this->url().encoded_query().size()`.

    Exception Safety

    Strong guarantee. Calls to allocate may throw. Exceptions thrown on invalid input.

    [#]

    Function segments_encoded_ref:: operator=

    Assignment

    Synopsis

                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.

    Effects

    this->assign( other.begin(), other.end() );

    Complexity

    Linear in `other.buffer().size()`.

    Exception Safety

    Strong guarantee. Calls to allocate may throw.

    @{

    [#]

    Function segments_encoded_ref:: operator=

    Synopsis

                segments_encoded_ref&
    operator=(segments_encoded_view const& other);
            
    [#]

    Function segments_encoded_ref:: operator=

    Assignment

    Synopsis

                segments_encoded_ref&
    operator=(std::initializer_list 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.

    Example

    url u; u.encoded_segments() = {"path", "to", "file.txt"};

    Preconditions

    None of the character buffers referenced by the list may overlap the character buffer of the underlying url, or else the behavior is undefined.

    Effects

    this->assign( init.begin(), init.end() );

    Complexity

    Linear in `init.size() + this->url().encoded_query().size() + this->url().encoded_fragment().size()`.

    Exception Safety

    Strong guarantee. Calls to allocate may throw. Exceptions thrown on invalid input.

    [#]

    Function segments_encoded_ref:: assign

    Assign segments

    Synopsis

                void
    assign(std::initializer_list 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.

    Example

    url u; u.segments().assign( {"path", "to", "file.txt"} );

    Complexity

    Linear in `init.size() + this->url().encoded_query().size() + this->url().encoded_fragment().size()`.

    Exception Safety

    Strong guarantee. Calls to allocate may throw. Exceptions thrown on invalid input.

    [#]

    Function segments_encoded_ref:: assign

    Assign segments

    Synopsis

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

    Mandates

    std::is_convertible< std::iterator_traits< FwdIt >::reference_type, pct_string_view >::value == true

    Complexity

    Linear in `std::distance( first, last ) + this->url().encoded_query().size() + this->url().encoded_fragment().size()`.

    Exception Safety

    Strong guarantee. Calls to allocate may throw. Exceptions thrown on invalid input.

    [#]

    Function segments_encoded_ref:: erase

    Erase segments

    Synopsis

                iterator
    erase(iterator pos) noexcept;
            

    Description

    This function removes a segment.

    All iterators that are equal to `pos` or come after are invalidated.

    Complexity

    Linear in `this->url().encoded_resource().size()`.

    Exception Safety

    Throws nothing.

    [#]

    Function segments_encoded_ref:: erase

    Erase segments

    Synopsis

                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.

    Complexity

    Linear in `this->url().encoded_resource().size()`.

    Exception Safety

    Throws nothing.

    [#]

    Function segments_encoded_ref:: insert

    Insert segments

    Synopsis

                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.

    Complexity

    Linear in `s.size() + this->url().encoded_resource().size()`.

    Exception Safety

    Strong guarantee. Calls to allocate may throw. Exceptions thrown on invalid input.

    [#]

    Function segments_encoded_ref:: insert

    Insert segments

    Synopsis

                iterator
    insert(
        iterator before,
        std::initializer_list 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.

    Example

    url u( "/file.txt" ); u.encoded_segments().insert( u.encoded_segments().begin(), { "path", "to" } );

    Complexity

    Linear in `init.size() + this->url().encoded_resource().size()`.

    Exception Safety

    Strong guarantee. Calls to allocate may throw. Exceptions thrown on invalid input.

    [#]

    Function segments_encoded_ref:: insert

    Insert segments

    Synopsis

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

    Mandates

    std::is_convertible< std::iterator_traits< FwdIt >::reference_type, pct_string_view >::value == true

    Complexity

    Linear in `std::distance( first, last ) + this->url().encoded_resource().size()`.

    Exception Safety

    Strong guarantee. Calls to allocate may throw. Exceptions thrown on invalid input.

    [#]

    Function segments_ref:: assign

    Assign segments

    Synopsis

                void
    assign(std::initializer_list 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.

    Example

    url u; u.segments().assign( { "path", "to", "file.txt" } );

    Complexity

    Linear in `init.size() + this->url().encoded_query().size() + this->url().encoded_fragment().size()`.

    Exception Safety

    Strong guarantee. Calls to allocate may throw.

    [#]

    Function segments_ref:: assign

    Assign segments

    Synopsis

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

    Mandates

    std::is_convertible< std::iterator_traits< FwdIt >::reference_type, core::string_view >::value == true

    Complexity

    Linear in `std::distance( first, last ) + this->url().encoded_query().size() + this->url().encoded_fragment().size()`.

    Exception Safety

    Strong guarantee. Calls to allocate may throw.

    [#]

    Function segments_ref:: operator=

    Assignment

    Synopsis

                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.

    Effects

    this->assign( other.begin(), other.end() );

    Complexity

    Linear in `other.buffer().size()`.

    Exception Safety

    Strong guarantee. Calls to allocate may throw.

    @{

    [#]

    Function segments_ref:: operator=

    Synopsis

                segments_ref&
    operator=(segments_view const& other);
            
    [#]

    Function segments_ref:: operator=

    Assignment

    Synopsis

                segments_ref&
    operator=(std::initializer_list 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.

    Example

    url u; u.segments() = { "path", "to", "file.txt" };

    Preconditions

    None of the character buffers referenced by the list may overlap the character buffer of the underlying url, or else the behavior is undefined.

    Effects

    this->assign( init.begin(), init.end() );

    Complexity

    Linear in `init.size() + this->url().encoded_query().size() + this->url().encoded_fragment().size()`.

    Exception Safety

    Strong guarantee. Calls to allocate may throw.

    [#]

    Function segments_encoded_ref:: replace

    Replace segments

    Synopsis

                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.

    Complexity

    Linear in `s.size() + this->url().encoded_resouce().size()`.

    Exception Safety

    Strong guarantee. Calls to allocate may throw.

    [#]

    Function segments_encoded_ref:: replace

    Replace segments

    Synopsis

                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.

    Complexity

    Linear in `s.size() + this->url().encoded_resouce().size()`.

    Exception Safety

    Strong guarantee. Calls to allocate may throw. Exceptions thrown on invalid input.

    [#]

    Function segments_encoded_ref:: replace

    Replace segments

    Synopsis

                iterator
    replace(
        iterator from,
        iterator to,
        std::initializer_list 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.

    Preconditions

    None of the character buffers referenced by the list may overlap the character buffer of the underlying url, or else the behavior is undefined.

    Complexity

    Linear in `init.size() + this->url().encoded_resouce().size()`.

    Exception Safety

    Strong guarantee. Calls to allocate may throw. Exceptions thrown on invalid input.

    [#]

    Function segments_encoded_ref:: replace

    Replace segments

    Synopsis

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

    Preconditions

    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.

    Complexity

    Linear in `std::distance( first, last ) + this->url().encoded_resouce().size()`.

    Exception Safety

    Strong guarantee. Calls to allocate may throw. Exceptions thrown on invalid input.

    [#]

    Function segments_ref:: erase

    Erase segments

    Synopsis

                iterator
    erase(iterator pos) noexcept;
            

    Description

    This function removes a segment.

    All iterators that are equal to `pos` or come after are invalidated.

    Complexity

    Linear in `this->url().encoded_resource().size()`.

    Exception Safety

    Throws nothing.

    [#]

    Function segments_ref:: erase

    Erase segments

    Synopsis

                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.

    Complexity

    Linear in `this->url().encoded_resource().size()`.

    Exception Safety

    Throws nothing.

    [#]

    Function segments_ref:: insert

    Insert segments

    Synopsis

                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.

    Complexity

    Linear in `s.size() + this->url().encoded_resource().size()`.

    Exception Safety

    Strong guarantee. Calls to allocate may throw.

    [#]

    Function segments_ref:: insert

    Insert segments

    Synopsis

                iterator
    insert(
        iterator before,
        std::initializer_list 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.

    Example

    url u( "/file.txt" ); u.segments().insert( u.segments().begin(), { "path", "to" } );

    Complexity

    Linear in `init.size() + this->url().encoded_resource().size()`.

    Exception Safety

    Strong guarantee. Calls to allocate may throw.

    [#]

    Function segments_ref:: insert

    Insert segments

    Synopsis

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

    Mandates

    std::is_convertible< std::iterator_traits< FwdIt >::reference_type, core::string_view >::value == true

    Complexity

    Linear in `std::distance( first, last ) + this->url().encoded_resource().size()`.

    Exception Safety

    Strong guarantee. Calls to allocate may throw.

    [#]

    Function segments_ref:: replace

    Replace segments

    Synopsis

                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.

    Complexity

    Linear in `s.size() + this->url().encoded_resouce().size()`.

    Exception Safety

    Strong guarantee. Calls to allocate may throw.

    [#]

    Function segments_ref:: replace

    Replace segments

    Synopsis

                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.

    Complexity

    Linear in `s.size() + this->url().encoded_resouce().size()`.

    Exception Safety

    Strong guarantee. Calls to allocate may throw.

    [#]

    Function segments_ref:: replace

    Replace segments

    Synopsis

                iterator
    replace(
        iterator from,
        iterator to,
        std::initializer_list 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.

    Preconditions

    None of the character buffers referenced by the list may overlap the character buffer of the underlying url, or else the behavior is undefined.

    Complexity

    Linear in `init.size() + this->url().encoded_resouce().size()`.

    Exception Safety

    Strong guarantee. Calls to allocate may throw.

    [#]

    Function segments_ref:: replace

    Replace segments

    Synopsis

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

    Preconditions

    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.

    Complexity

    Linear in `std::distance( first, last ) + this->url().encoded_resouce().size()`.

    Exception Safety

    Strong guarantee. Calls to allocate may throw.

    [#]

    Function url_view_base:: params

    Return the query as a container of parameters

    Synopsis

                params_view
    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. Any percent-escapes in strings returned when iterating the view are decoded first.

    Example

    params_view pv = url_view( "/sql?id=42&name=jane%2Ddoe&page+size=20" ).params();

    Complexity

    Constant.

    Exception Safety

    Throws nothing.

    BNF

    query = *( pchar / "/" / "?" ) query-param = key [ "=" value ] query-params = [ query-param ] *( "&" query-param )

    Specification

  • ://en.wikipedia.org/wiki/Query_string" >Query string (Wikipedia)
  • [#]

    Function url_view_base:: params

    Synopsis

                params_view
    params(encoding_opts opt) const noexcept;
            
    [#]

    Function url:: url

    Constructor

    Synopsis

                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.

    Example

    url u;

    Postconditions

    this->empty() == true

    Complexity

    Constant.

    Exception Safety

    Throws nothing.

    BNF

    relative-ref = relative-part [ "?" query ] [ "#" fragment ]

    Specification

    4.2. Relative Reference (rfc3986)

    [#]

    Function url:: url

    Constructor

    Synopsis

                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.

    Example

    url u( "https://www.example.com" );

    Effects

    return url( parse_uri_reference( s ).value() );

    Postconditions

    this->buffer().data() != s.data()

    Complexity

    Linear in `s.size()`.

    Exception Safety

    Calls to allocate may throw. Exceptions thrown on invalid input.

    BNF

    URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ] relative-ref = relative-part [ "?" query ] [ "#" fragment ]

    Specification

  • 4.1. URI Reference
  • [#]

    Function url:: url

    Constructor

    Synopsis

                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.

    Postconditions

    u.empty() == true

    Complexity

    Constant.

    Exception Safety

    Throws nothing.

    [#]

    Function url:: url

    Constructor

    Synopsis

                url(url_view_base const& u);
            

    Description

    The newly constructed object contains a copy of `u`.

    Postconditions

    this->buffer() == u.buffer() && this->buffer().data() != u.buffer().data()

    Complexity

    Linear in `u.size()`.

    Exception Safety

    Strong guarantee. Calls to allocate may throw.

    [#]

    Function url:: url

    Constructor

    Synopsis

                url(url const& u);
            

    Description

    The newly constructed object contains a copy of `u`.

    Postconditions

    this->buffer() == u.buffer() && this->buffer().data() != u.buffer().data()

    Complexity

    Linear in `u.size()`.

    Exception Safety

    Strong guarantee. Calls to allocate may throw.

    [#]

    Function url:: operator=

    Assignment

    Synopsis

                url&
    operator=(url&& u) noexcept;
            

    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.

    Postconditions

    u.empty() == true

    Complexity

    Constant.

    Exception Safety

    Throws nothing.

    [#]

    Function url:: operator=

    Assignment

    Synopsis

                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.

    Postconditions

    this->buffer() == u.buffer() && this->buffer().data() != u.buffer().data()

    Complexity

    Linear in `u.size()`.

    Exception Safety

    Strong guarantee. Calls to allocate may throw.

    [#]

    Function url:: operator=

    Assignment

    Synopsis

                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.

    Postconditions

    this->buffer() == u.buffer() && this->buffer().data() != u.buffer().data()

    Complexity

    Linear in `u.size()`.

    Exception Safety

    Strong guarantee. Calls to allocate may throw.

    [#]

    Function static_url:: operator=

    Assignment

    Synopsis

                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.

    Postconditions

    this->buffer() == u.buffer() && this->buffer().data() != u.buffer().data()

    Complexity

    Linear in `u.size()`.

    Exception Safety

    Throws nothing.

    [#]

    Function static_url:: operator=

    Assignment

    Synopsis

                static_url&
    operator=(url_view_base const& u);
            

    Description

    The contents of `u` are copied and the previous contents of `this` are discarded.

    Postconditions

    this->buffer() == u.buffer() && this->buffer().data() != u.buffer().data()

    Complexity

    Linear in `u.size()`.

    Exception Safety

    Strong guarantee. Exception thrown if capacity exceeded.

    [#]

    Function static_url:: static_url

    Constructor

    Synopsis

                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.

    Example

    static_url< 1024 > u;

    Postconditions

    this->empty() == true

    Complexity

    Constant.

    Exception Safety

    Throws nothing.

    BNF

    relative-ref = relative-part [ "?" query ] [ "#" fragment ]

    Specification

    4.2. Relative Reference (rfc3986)

    [#]

    Function static_url:: static_url

    Constructor

    Synopsis

                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.

    Example

    static_url< 1024 > u( "https://www.example.com" );

    Effects

    return static_url( parse_uri_reference( s ).value() );

    Postconditions

    this->buffer().data() != s.data()

    Complexity

    Linear in `s.size()`.

    Exception Safety

    Exceptions thrown on invalid input.

    BNF

    URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ] relative-ref = relative-part [ "?" query ] [ "#" fragment ]

    Specification

  • 4.1. URI Reference
  • [#]

    Function static_url:: static_url

    Constructor

    Synopsis

                static_url(static_url const& u) noexcept;
            

    Description

    The newly constructed object contains a copy of `u`.

    Postconditions

    this->buffer() == u.buffer() && this->buffer.data() != u.buffer().data()

    Complexity

    Linear in `u.size()`.

    Exception Safety

    Exception thrown if maximum size exceeded.

    [#]

    Function static_url:: static_url

    Constructor

    Synopsis

                static_url(url_view_base const& u);
            

    Description

    The newly constructed object contains a copy of `u`.

    Postconditions

    this->buffer() == u.buffer() && this->buffer.data() != u.buffer().data()

    Complexity

    Linear in `u.size()`.

    Exception Safety

    Exception thrown if capacity exceeded.

    [#]

    Function format

    Format arguments into a URL

    Synopsis

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

    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.

    Example

    assert(format("{}", "Hello world!").buffer() == "Hello%20world%21");

    Preconditions

    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.

    BNF

    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

    Specification

  • Format String Syntax
  • [#]

    Function format

    Format arguments into a URL

    Synopsis

                url
    format(
        core::string_view fmt,
        std::initializer_list 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.

    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.

    Example

    assert(format("user/{id}", {{"id", 1}}).buffer() == "user/1");

    Preconditions

    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.

    BNF

    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

    Specification

  • Format String Syntax
  • [#]

    Function format_to

    Format arguments into a URL

    Synopsis

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

    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.

    Example

    static_url<30> u; format(u, "{}", "Hello world!"); assert(u.buffer() == "Hello%20world%21");

    Preconditions

    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.

    Exception Safety

    Strong guarantee.

    BNF

    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

    Specification

  • Format String Syntax
  • [#]

    Function format_to

    Format arguments into a URL

    Synopsis

                void
    format_to(
        url_base& u,
        core::string_view fmt,
        std::initializer_list 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.

    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.

    Example

    static_url<30> u; format_to(u, "user/{id}", {{"id", 1}}) assert(u.buffer() == "user/1");

    Preconditions

    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.

    Exception Safety

    Strong guarantee.

    BNF

    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

    Specification

  • Format String Syntax
  • [#]

    Function hash:: hash

    Synopsis

                constexpr
    hash() = default;
            
    [#]

    Function hash:: hash

    Synopsis

                constexpr
    hash(hash const&) = default;
            
    [#]

    Function hash:: hash

    Synopsis

                hash(size_t salt) noexcept;
            
    [#]

    Function hash:: hash

    Synopsis

                constexpr
    hash() = default;
            
    [#]

    Function hash:: hash

    Synopsis

                constexpr
    hash(hash const&) = default;
            
    [#]

    Function hash:: hash

    Synopsis

                hash(size_t salt) noexcept;
            
    [#]

    Function hash:: hash

    Synopsis

                hash() = default;
            
    [#]

    Function hash:: hash

    Synopsis

                hash(hash const&) = default;
            
    [#]

    Function hash:: hash

    Synopsis

                hash(size_t salt) noexcept;
            

    Created with MrDocs