Diff coverage report for

//

//

// Copyright (c) 2019 Vinnie Falco (vinnie.falco@gmail.com)

// Copyright (c) 2019 Vinnie Falco (vinnie.falco@gmail.com)

// Copyright (c) 2022 Alan de Freitas (alandefreitas@gmail.com)

// Copyright (c) 2022 Alan de Freitas (alandefreitas@gmail.com)

//

//

// Distributed under the Boost Software License, Version 1.0. (See accompanying

// Distributed under the Boost Software License, Version 1.0. (See accompanying

// file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)

// file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)

//

//

// Official repository: https://github.com/boostorg/url

// Official repository: https://github.com/boostorg/url

//

//

#ifndef BOOST_URL_URL_VIEW_BASE_HPP

#ifndef BOOST_URL_URL_VIEW_BASE_HPP

#define BOOST_URL_URL_VIEW_BASE_HPP

#define BOOST_URL_URL_VIEW_BASE_HPP

#include <boost/url/detail/config.hpp>

#include <boost/url/detail/config.hpp>

#include <boost/url/authority_view.hpp>

#include <boost/url/authority_view.hpp>

#include <boost/url/host_type.hpp>

#include <boost/url/host_type.hpp>

#include <boost/url/ipv4_address.hpp>

#include <boost/url/ipv4_address.hpp>

#include <boost/url/ipv6_address.hpp>

#include <boost/url/ipv6_address.hpp>

#include <boost/url/params_view.hpp>

#include <boost/url/params_view.hpp>

#include <boost/url/params_encoded_view.hpp>

#include <boost/url/params_encoded_view.hpp>

#include <boost/url/pct_string_view.hpp>

#include <boost/url/pct_string_view.hpp>

#include <boost/url/scheme.hpp>

#include <boost/url/scheme.hpp>

#include <boost/url/segments_encoded_view.hpp>

#include <boost/url/segments_encoded_view.hpp>

#include <boost/url/segments_view.hpp>

#include <boost/url/segments_view.hpp>

#include <boost/url/detail/url_impl.hpp>

#include <boost/url/detail/url_impl.hpp>

#include <boost/url/grammar/string_token.hpp>

#include <boost/url/grammar/string_token.hpp>

#include <boost/assert.hpp>

#include <boost/assert.hpp>

#include <cstddef>

#include <cstddef>

#include <cstdint>

#include <cstdint>

#include <iosfwd>

#include <iosfwd>

#include <memory>

#include <memory>

#include <string>

#include <string>

#include <utility>

#include <utility>

namespace boost {

namespace boost {

namespace urls {

namespace urls {

#ifndef BOOST_URL_DOCS

#ifndef BOOST_URL_DOCS

namespace detail {

namespace detail {

struct pattern;

struct pattern;

}

}

#endif

#endif

/** Common functionality for containers

/** Common functionality for containers

    This base class is used by the library

    This base class is used by the library

    to provide common member functions for

    to provide common member functions for

    containers. This cannot be instantiated

    containers. This cannot be instantiated

    directly; Instead, use one of the

    directly; Instead, use one of the

    containers or functions:

    containers or functions:

    @par Containers

    @par Containers

        @li @ref url

        @li @ref url

        @li @ref url_view

        @li @ref url_view

        @li @ref static_url

        @li @ref static_url

    @par Functions

    @par Functions

        @li @ref parse_absolute_uri

        @li @ref parse_absolute_uri

        @li @ref parse_origin_form

        @li @ref parse_origin_form

        @li @ref parse_relative_ref

        @li @ref parse_relative_ref

        @li @ref parse_uri

        @li @ref parse_uri

        @li @ref parse_uri_reference

        @li @ref parse_uri_reference

*/

*/

class BOOST_URL_DECL

class BOOST_URL_DECL

    url_view_base

    url_view_base

    : private detail::parts_base

    : private detail::parts_base

{

{

    detail::url_impl impl_;

    detail::url_impl impl_;

    detail::url_impl const* pi_;

    detail::url_impl const* pi_;

    friend class url;

    friend class url;

    friend class url_base;

    friend class url_base;

    friend class url_view;

    friend class url_view;

    friend class static_url_base;

    friend class static_url_base;

    friend class params_base;

    friend class params_base;

    friend class params_encoded_base;

    friend class params_encoded_base;

    friend class params_encoded_ref;

    friend class params_encoded_ref;

    friend class params_encoded_view;

    friend class params_encoded_view;

    friend class params_ref;

    friend class params_ref;

    friend class params_view;

    friend class params_view;

    friend class segments_base;

    friend class segments_base;

    friend class segments_encoded_base;

    friend class segments_encoded_base;

    friend class segments_encoded_ref;

    friend class segments_encoded_ref;

    friend class segments_encoded_view;

    friend class segments_encoded_view;

    friend class segments_ref;

    friend class segments_ref;

    friend class segments_view;

    friend class segments_view;

    friend struct detail::pattern;

    friend struct detail::pattern;

    struct shared_impl;

    struct shared_impl;

    url_view_base() noexcept;

    url_view_base() noexcept;

    explicit url_view_base(

    explicit url_view_base(

        detail::url_impl const&) noexcept;

        detail::url_impl const&) noexcept;

    ~url_view_base() = default;

    ~url_view_base() = default;

    url_view_base(

    url_view_base(

        url_view_base const& o) noexcept

        url_view_base const& o) noexcept

        : impl_(o.impl_)

        : impl_(o.impl_)

        , pi_(o.pi_)

        , pi_(o.pi_)

    {

    {

        if (pi_ == &o.impl_)

        if (pi_ == &o.impl_)

            pi_ = &impl_;

            pi_ = &impl_;

    }

    }

    url_view_base& operator=(

    url_view_base& operator=(

        url_view_base const&) = delete;

        url_view_base const&) = delete;

protected:

protected:

    /** Calculate a hash of the url

    /** Calculate a hash of the url

        This function calculates a hash of the

        This function calculates a hash of the

        url as if it were always normalized.

        url as if it were always normalized.

        @par Complexity

        @par Complexity

        Linear in `this->size()`.

        Linear in `this->size()`.

        @par Exception Safety

        @par Exception Safety

        Throws nothing.

        Throws nothing.

        @param salt An initial value to add to

        @param salt An initial value to add to

        the hash

        the hash

        @return A hash value suitable for use

        @return A hash value suitable for use

        in hash-based containers.

        in hash-based containers.

    */

    */

    std::size_t

    std::size_t

    digest(std::size_t salt = 0) const noexcept;

    digest(std::size_t salt = 0) const noexcept;

public:

public:

    //--------------------------------------------

    //--------------------------------------------

    //

    //

    // Observers

    // Observers

    //

    //

    //--------------------------------------------

    //--------------------------------------------

    /** Return the maximum number of characters possible

    /** Return the maximum number of characters possible

        This represents the largest number

        This represents the largest number

        of characters that are theoretically

        of characters that are theoretically

        possible to represent in a url,

        possible to represent in a url,

        not including any null terminator.

        not including any null terminator.

        In practice the actual possible size

        In practice the actual possible size

        may be lower than this number.

        may be lower than this number.

        @par Complexity

        @par Complexity

        Constant.

        Constant.

        @par Exception Safety

        @par Exception Safety

        Throws nothing.

        Throws nothing.

        @return The maximum number of characters.

        @return The maximum number of characters.

    */

    */

    static

    static

    constexpr

    constexpr

    std::size_t

    std::size_t

    {

    {

    }

    }

    /** Return the number of characters in the url

    /** Return the number of characters in the url

        This function returns the number of

        This function returns the number of

        characters in the url's encoded string,

        characters in the url's encoded string,

        not including any null terminator,

        not including any null terminator,

        if present.

        if present.

        @par Example

        @par Example

        @code

        @code

        assert( url_view( "file:///Program%20Files" ).size() == 23 );

        assert( url_view( "file:///Program%20Files" ).size() == 23 );

        @endcode

        @endcode

        @par Complexity

        @par Complexity

        Constant.

        Constant.

        @par Exception Safety

        @par Exception Safety

        Throws nothing.

        Throws nothing.

        @return The number of characters in the url.

        @return The number of characters in the url.

    */

    */

    std::size_t

    std::size_t

    {

    {

    }

    }

    /** Return true if the url is empty

    /** Return true if the url is empty

        The empty string matches the

        The empty string matches the

        <em>relative-ref</em> grammar.

        <em>relative-ref</em> grammar.

        @par Example

        @par Example

        @code

        @code

        assert( url_view( "" ).empty() );

        assert( url_view( "" ).empty() );

        @endcode

        @endcode

        @par Complexity

        @par Complexity

        Constant.

        Constant.

        @par Exception Safety

        @par Exception Safety

        Throws nothing.

        Throws nothing.

        @par BNF

        @par BNF

        @code

        @code

        relative-ref  = relative-part [ "?" query ] [ "#" fragment ]

        relative-ref  = relative-part [ "?" query ] [ "#" fragment ]

        relative-part = "//" authority path-abempty

        relative-part = "//" authority path-abempty

                      / path-absolute

                      / path-absolute

                      / path-noscheme

                      / path-noscheme

                      / path-empty

                      / path-empty

        @endcode

        @endcode

        @par Specification

        @par Specification

        @li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-4.2">4.2.  Relative Reference (rfc3986)</a>

        @li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-4.2">4.2.  Relative Reference (rfc3986)</a>

        @return `true` if the url is empty.

        @return `true` if the url is empty.

    */

    */

    bool

    bool

    {

    {

    }

    }

    /** Return a pointer to the url's character buffer

    /** Return a pointer to the url's character buffer

        This function returns a pointer to

        This function returns a pointer to

        the first character of the url, which

        the first character of the url, which

        is not guaranteed to be null-terminated.

        is not guaranteed to be null-terminated.

        @par Complexity

        @par Complexity

        Constant.

        Constant.

        @par Exception Safety

        @par Exception Safety

        Throws nothing.

        Throws nothing.

        @return A pointer to the first character.

        @return A pointer to the first character.

    */

    */

    char const*

    char const*

    {

    {

    }

    }

    /** Return the url string

    /** Return the url string

        This function returns the entire url,

        This function returns the entire url,

        which may contain percent escapes.

        which may contain percent escapes.

        @par Example

        @par Example

        @code

        @code

        assert( url_view( "http://www.example.com" ).buffer() == "http://www.example.com" );

        assert( url_view( "http://www.example.com" ).buffer() == "http://www.example.com" );

        @endcode

        @endcode

        @par Complexity

        @par Complexity

        Constant.

        Constant.

        @par Exception Safety

        @par Exception Safety

        Throws nothing.

        Throws nothing.

        @return The url as a string.

        @return The url as a string.

    */

    */

    core::string_view

    core::string_view

    {

    {

    }

    }

    /** Return the URL as a core::string_view

    /** Return the URL as a core::string_view

        @par Complexity

        @par Complexity

        Constant.

        Constant.

        @par Exception Safety

        @par Exception Safety

        Throws nothing.

        Throws nothing.

        @return A string view of the URL.

        @return A string view of the URL.

    */

    */

    {

    {

    }

    }

    /** Return a shared, persistent copy of the url

    /** Return a shared, persistent copy of the url

        This function returns a read-only copy of

        This function returns a read-only copy of

        the url, with shared lifetime. The returned

        the url, with shared lifetime. The returned

        value owns (persists) the underlying string.

        value owns (persists) the underlying string.

        The algorithm used to create the value

        The algorithm used to create the value

        minimizes the number of individual memory

        minimizes the number of individual memory

        allocations, making it more efficient than

        allocations, making it more efficient than

        when using direct standard library functions.

        when using direct standard library functions.

        @par Example

        @par Example

        @code

        @code

        std::shared_ptr< url_view const > sp;

        std::shared_ptr< url_view const > sp;

        {

        {

            std::string s( "http://example.com" );

            std::string s( "http://example.com" );

            url_view u( s );                        // u references characters in s

            url_view u( s );                        // u references characters in s

            assert( u.data() == s.data() );         // same buffer

            assert( u.data() == s.data() );         // same buffer

            sp = u.persist();

            sp = u.persist();

            assert( sp->data() != s.data() );       // different buffer

            assert( sp->data() != s.data() );       // different buffer

            assert( sp->buffer() == s);             // same contents

            assert( sp->buffer() == s);             // same contents

            // s is destroyed and thus u

            // s is destroyed and thus u

            // becomes invalid, but sp remains valid.

            // becomes invalid, but sp remains valid.

        }

        }

        @endcode

        @endcode

        @par Complexity

        @par Complexity

        Linear in `this->size()`.

        Linear in `this->size()`.

        @par Exception Safety

        @par Exception Safety

        Calls to allocate may throw.

        Calls to allocate may throw.

        @return A shared pointer to a read-only url_view.

        @return A shared pointer to a read-only url_view.

    */

    */

    std::shared_ptr<

    std::shared_ptr<

        url_view const> persist() const;

        url_view const> persist() const;

    //--------------------------------------------

    //--------------------------------------------

    //

    //

    // Scheme

    // Scheme

    //

    //

    //--------------------------------------------

    //--------------------------------------------

    /** Return true a scheme is present

    /** Return true a scheme is present

        This function returns true if this

        This function returns true if this

        contains a scheme.

        contains a scheme.

        @par Example

        @par Example

        @code

        @code

        assert( url_view( "http://www.example.com" ).has_scheme() );

        assert( url_view( "http://www.example.com" ).has_scheme() );

        @endcode

        @endcode

        @par Complexity

        @par Complexity

        Constant.

        Constant.

        @par Exception Safety

        @par Exception Safety

        Throws nothing.

        Throws nothing.

        @par BNF

        @par BNF

        @code

        @code

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

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

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

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

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

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

        @endcode

        @endcode

        @par Specification

        @par Specification

        @li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.1">3.1. Scheme (rfc3986)</a>

        @li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.1">3.1. Scheme (rfc3986)</a>

        @see

        @see

            @ref scheme,

            @ref scheme,

            @ref scheme_id.

            @ref scheme_id.

        @return `true` if the url contains a scheme.

        @return `true` if the url contains a scheme.

    */

    */

    bool

    bool

    has_scheme() const noexcept;

    has_scheme() const noexcept;

    /** Return the scheme

    /** Return the scheme

        This function returns the scheme if it

        This function returns the scheme if it

        exists, without a trailing colon (':').

        exists, without a trailing colon (':').

        Otherwise it returns an empty string.

        Otherwise it returns an empty string.

        Note that schemes are case-insensitive,

        Note that schemes are case-insensitive,

        and the canonical form is lowercased.

        and the canonical form is lowercased.

        @par Example

        @par Example

        @code

        @code

        assert( url_view( "http://www.example.com" ).scheme() == "http" );

        assert( url_view( "http://www.example.com" ).scheme() == "http" );

        @endcode

        @endcode

        @par Exception Safety

        @par Exception Safety

        Throws nothing.

        Throws nothing.

        @par BNF

        @par BNF

        @code

        @code

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

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

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

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

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

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

        @endcode

        @endcode

        @par Specification

        @par Specification

        @li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.1">3.1. Scheme (rfc3986)</a>

        @li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.1">3.1. Scheme (rfc3986)</a>

        @see

        @see

            @ref has_scheme,

            @ref has_scheme,

            @ref scheme_id.

            @ref scheme_id.

        @return The scheme as a string.

        @return The scheme as a string.

    */

    */

    core::string_view

    core::string_view

    scheme() const noexcept;

    scheme() const noexcept;

    /** Return the scheme

    /** Return the scheme

        This function returns a value which

        This function returns a value which

        depends on the scheme in the url:

        depends on the scheme in the url:

        @li If the scheme is a well-known

        @li If the scheme is a well-known

        scheme, corresponding value from

        scheme, corresponding value from

        the enumeration @ref urls::scheme

        the enumeration @ref urls::scheme

        is returned.

        is returned.

        @li If a scheme is present but is not

        @li If a scheme is present but is not

        a well-known scheme, the value

        a well-known scheme, the value

        returned is @ref urls::scheme::unknown.

        returned is @ref urls::scheme::unknown.

        @li Otherwise, if the scheme is absent

        @li Otherwise, if the scheme is absent

        the value returned is

        the value returned is

        @ref urls::scheme::none.

        @ref urls::scheme::none.

        @par Example

        @par Example

        @code

        @code

        assert( url_view( "wss://www.example.com/crypto.cgi" ).scheme_id() == scheme::wss );

        assert( url_view( "wss://www.example.com/crypto.cgi" ).scheme_id() == scheme::wss );

        @endcode

        @endcode

        @par Complexity

        @par Complexity

        Constant.

        Constant.

        @par Exception Safety

        @par Exception Safety

        Throws nothing.

        Throws nothing.

        @par BNF

        @par BNF

        @code

        @code

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

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

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

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

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

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

        @endcode

        @endcode

        @par Specification

        @par Specification

        @li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.1">3.1. Scheme (rfc3986)</a>

        @li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.1">3.1. Scheme (rfc3986)</a>

        @see

        @see

            @ref has_scheme,

            @ref has_scheme,

            @ref scheme.

            @ref scheme.

        @return The scheme as an enumeration value.

        @return The scheme as an enumeration value.

    */

    */

    urls::scheme

    urls::scheme

    scheme_id() const noexcept;

    scheme_id() const noexcept;

    //--------------------------------------------

    //--------------------------------------------

    //

    //

    // Authority

    // Authority

    //

    //

    //--------------------------------------------

    //--------------------------------------------

    /** Return true if an authority is present

    /** Return true if an authority is present

        This function returns true if the url

        This function returns true if the url

        contains an authority. The presence of

        contains an authority. The presence of

        an authority is denoted by a double

        an authority is denoted by a double

        slash ("//") at the beginning or after

        slash ("//") at the beginning or after

        the scheme.

        the scheme.

        @par Example

        @par Example

        @code

        @code

        assert( url_view( "http://www.example.com/index.htm" ).has_authority() );

        assert( url_view( "http://www.example.com/index.htm" ).has_authority() );

        @endcode

        @endcode

        @par Complexity

        @par Complexity

        Constant.

        Constant.

        @par Exception Safety

        @par Exception Safety

        Throws nothing.

        Throws nothing.

        @par BNF

        @par BNF

        @code

        @code

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

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

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

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

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

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

        URI-reference   = URI / relative-ref

        URI-reference   = URI / relative-ref

        relative-ref    = relative-part [ "?" query ] [ "#" fragment ]

        relative-ref    = relative-part [ "?" query ] [ "#" fragment ]

        hier-part       = "//" authority path-abempty

        hier-part       = "//" authority path-abempty

                        ; (more...)

                        ; (more...)

        relative-part   = "//" authority path-abempty

        relative-part   = "//" authority path-abempty

                        ; (more...)

                        ; (more...)

        @endcode

        @endcode

        @par Specification

        @par Specification

        @li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.2">3.2. Authority (rfc3986)</a>

        @li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.2">3.2. Authority (rfc3986)</a>

        @see

        @see

            @ref authority,

            @ref authority,

            @ref encoded_authority.

            @ref encoded_authority.

        @return `true` if the url contains an authority.

        @return `true` if the url contains an authority.

    */

    */

    bool

    bool

    {

    {

    }

    }

    /** Return the authority

    /** Return the authority

        This function returns the authority as

        This function returns the authority as

        an @ref authority_view.

        an @ref authority_view.

        @par Example

        @par Example

        @code

        @code

        authority_view a = url_view( "https://www.example.com:8080/index.htm" ).authority();

        authority_view a = url_view( "https://www.example.com:8080/index.htm" ).authority();

        @endcode

        @endcode

        @par Complexity

        @par Complexity

        Constant.

        Constant.

        @par Exception Safety

        @par Exception Safety

        Throws nothing.

        Throws nothing.

        @par BNF

        @par BNF