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_HPP

#ifndef BOOST_URL_URL_VIEW_HPP

#define BOOST_URL_URL_VIEW_HPP

#define BOOST_URL_URL_VIEW_HPP

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

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

#include <boost/url/url_view_base.hpp>

#include <boost/url/url_view_base.hpp>

#include <utility>

#include <utility>

namespace boost {

namespace boost {

namespace urls {

namespace urls {

/** A non-owning reference to a valid URL 

/** A non-owning reference to a valid URL 

    Objects of this type represent valid URL

    Objects of this type represent valid URL

    strings constructed from a parsed, external

    strings constructed from a parsed, external

    character buffer whose storage is managed

    character buffer whose storage is managed

    by the caller. That is, it acts like a

    by the caller. That is, it acts like a

    `core::string_view` in terms of ownership.

    `core::string_view` in terms of ownership.

    The caller is responsible for ensuring

    The caller is responsible for ensuring

    that the lifetime of the underlying

    that the lifetime of the underlying

    character buffer extends until it is no

    character buffer extends until it is no

    longer referenced.

    longer referenced.

    @par Example 1

    @par Example 1

    Construction from a string parses the input

    Construction from a string parses the input

    as a <em>URI-reference</em> and throws an

    as a <em>URI-reference</em> and throws an

    exception on error. Upon success, the

    exception on error. Upon success, the

    constructed object points to the passed

    constructed object points to the passed

    character buffer; ownership is not

    character buffer; ownership is not

    transferred.

    transferred.

    @code

    @code

    url_view u( "https://www.example.com/index.htm?text=none#a1" );

    url_view u( "https://www.example.com/index.htm?text=none#a1" );

    @endcode

    @endcode

    @par Example 2

    @par Example 2

    Parsing functions like @ref parse_uri_reference

    Parsing functions like @ref parse_uri_reference

    return a `boost::system::result` containing either a valid

    return a `boost::system::result` containing either a valid

    @ref url_view upon success, otherwise they

    @ref url_view upon success, otherwise they

    contain an error. The error can be converted to

    contain an error. The error can be converted to

    an exception by the caller if desired:

    an exception by the caller if desired:

    @code

    @code

    system::result< url_view > rv = parse_uri_reference( "https://www.example.com/index.htm?text=none#a1" );

    system::result< url_view > rv = parse_uri_reference( "https://www.example.com/index.htm?text=none#a1" );

    @endcode

    @endcode

    @par BNF

    @par BNF

    @code

    @code

    URI-reference = URI / relative-ref

    URI-reference = URI / relative-ref

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

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

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

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

    @endcode

    @endcode

    @par Specification

    @par Specification

    @li <a href="https://tools.ietf.org/html/rfc3986"

    @li <a href="https://tools.ietf.org/html/rfc3986"

        >Uniform Resource Identifier (URI): Generic Syntax (rfc3986)</a>

        >Uniform Resource Identifier (URI): Generic Syntax (rfc3986)</a>

    @see

    @see

        @ref parse_absolute_uri,

        @ref parse_absolute_uri,

        @ref parse_origin_form,

        @ref parse_origin_form,

        @ref parse_relative_ref,

        @ref parse_relative_ref,

        @ref parse_uri,

        @ref parse_uri,

        @ref parse_uri_reference.

        @ref parse_uri_reference.

*/

*/

class BOOST_URL_DECL url_view

class BOOST_URL_DECL url_view

    : public url_view_base

    : public url_view_base

{

{

    friend std::hash<url_view>;

    friend std::hash<url_view>;

    friend class url_view_base;

    friend class url_view_base;

    friend class params_base;

    friend class params_base;

    friend class params_encoded_base;

    friend class params_encoded_base;

#ifndef BOOST_URL_DOCS

#ifndef BOOST_URL_DOCS

    // VFALCO docca emits this erroneously

    // VFALCO docca emits this erroneously

    friend struct detail::url_impl;

    friend struct detail::url_impl;

#endif

#endif

    using url_view_base::digest;

    using url_view_base::digest;

    explicit

    explicit

        detail::url_impl const& impl) noexcept

        detail::url_impl const& impl) noexcept

    {

    {

public:

public:

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

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

    //

    //

    // Special Members

    // Special Members

    //

    //

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

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

    /** Destructor

    /** Destructor

        Any params, segments, iterators, or

        Any params, segments, iterators, or

        other views which reference the same

        other views which reference the same

        underlying character buffer remain

        underlying character buffer remain

        valid.

        valid.

    */

    */

    ~url_view() = default;

    ~url_view() = default;

    /** Constructor

    /** Constructor

        Default constructed views refer to

        Default constructed views refer to

        a string with zero length, which

        a string with zero length, which

        always remains valid. This matches

        always remains valid. This matches

        the grammar for a relative-ref with

        the grammar for a relative-ref with

        an empty path and no query or

        an empty path and no query or

        fragment.

        fragment.

        @par Example

        @par Example

        @code

        @code

        url_view u;

        url_view u;

        @endcode

        @endcode

        @par Postconditions

        @par Postconditions

        @code

        @code

        this->empty() == true

        this->empty() == true

        @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 ]

        @endcode

        @endcode

        @par Specification

        @par Specification

        <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-4.2"

        <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-4.2"

            >4.2. Relative Reference (rfc3986)</a>

            >4.2. Relative Reference (rfc3986)</a>

    */

    */

    url_view() noexcept;

    url_view() noexcept;

    /** Constructor

    /** Constructor

        This function constructs a URL from

        This function constructs a URL from

        the string `s`, which must contain a

        the string `s`, which must contain a

        valid <em>URI</em> or <em>relative-ref</em>

        valid <em>URI</em> or <em>relative-ref</em>

        or else an exception is thrown. Upon

        or else an exception is thrown. Upon

        successful construction, the view

        successful construction, the view

        refers to the characters in the

        refers to the characters in the

        buffer pointed to by `s`.

        buffer pointed to by `s`.

        Ownership is not transferred; The caller

        Ownership is not transferred; The caller

        is responsible for ensuring that the

        is responsible for ensuring that the

        lifetime of the buffer extends until

        lifetime of the buffer extends until

        it is no longer referenced.

        it is no longer referenced.

        @par Example

        @par Example

        @code

        @code

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

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

        @endcode

        @endcode

        @par Effects

        @par Effects

        @code

        @code

        return parse_uri_reference( s ).value();

        return parse_uri_reference( s ).value();

        @endcode

        @endcode

        @par Complexity

        @par Complexity

        Linear in `s.size()`.

        Linear in `s.size()`.

        @par Exception Safety

        @par Exception Safety

        Exceptions thrown on invalid input.

        Exceptions thrown on invalid input.

        @throw system_error

        @throw system_error

        The input failed to parse correctly.

        The input failed to parse correctly.

        @param s The string to parse.

        @param s The string to parse.

        @par BNF

        @par BNF

        @code

        @code

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

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

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

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

        @endcode

        @endcode

        @par Specification

        @par Specification

        @li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-4.1"

        @li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-4.1"

            >4.1. URI Reference</a>

            >4.1. URI Reference</a>

        @see

        @see

            @ref parse_uri_reference.

            @ref parse_uri_reference.

    */

    */

    url_view(core::string_view s);

    url_view(core::string_view s);

    /// @copydoc url_view(core::string_view)

    /// @copydoc url_view(core::string_view)

    template<

    template<

        class String

        class String

#ifndef BOOST_URL_DOCS

#ifndef BOOST_URL_DOCS

        , class = typename std::enable_if<

        , class = typename std::enable_if<

            std::is_convertible<

            std::is_convertible<

                String,

                String,

                core::string_view

                core::string_view

                    >::value &&

                    >::value &&

            !std::is_convertible<

            !std::is_convertible<

                String*,

                String*,

                url_view_base*

                url_view_base*

                    >::value

                    >::value

            >::type

            >::type

#endif

#endif

    >

    >

        String const& s)

        String const& s)

        : url_view(

        : url_view(

    {

    {

    /** Constructor

    /** Constructor

        After construction, both views

        After construction, both views

        reference the same underlying character

        reference the same underlying character

        buffer. Ownership is not transferred.

        buffer. Ownership is not transferred.

        @par Postconditions

        @par Postconditions

        @code

        @code

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

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

        @endcode

        @endcode

        @par Complexity

        @par Complexity

        Constant.

        Constant.

        @par Exception Safety

        @par Exception Safety

        Throws nothing.

        Throws nothing.

        @param other The other view.

        @param other The other view.

    */

    */

        url_view const& other) noexcept

        url_view const& other) noexcept

    {

    {

    /** Constructor

    /** Constructor

        After construction, both views

        After construction, both views

        reference the same underlying character

        reference the same underlying character

        buffer. Ownership is not transferred.

        buffer. Ownership is not transferred.

        @par Postconditions

        @par Postconditions

        @code

        @code

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

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

        @endcode

        @endcode

        @par Complexity

        @par Complexity

        Constant.

        Constant.

        @par Exception Safety

        @par Exception Safety

        Throws nothing.

        Throws nothing.

        @param other The other view.

        @param other The other view.

    */

    */

    url_view(

    url_view(

        url_view_base const& other) noexcept;

        url_view_base const& other) noexcept;

    /** Assignment

    /** Assignment

        After assignment, both views

        After assignment, both views

        reference the same underlying character

        reference the same underlying character

        buffer. Ownership is not transferred.

        buffer. Ownership is not transferred.

        @par Postconditions

        @par Postconditions

        @code

        @code

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

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

        @endcode

        @endcode

        @par Complexity

        @par Complexity

        Constant.

        Constant.

        @par Exception Safety

        @par Exception Safety

        Throws nothing.

        Throws nothing.

        @param other The other view.

        @param other The other view.

        @return A reference to this object.

        @return A reference to this object.

    */

    */

    url_view&

    url_view&

        url_view const& other) noexcept

        url_view const& other) noexcept

    {

    {

            *this = static_cast<

            *this = static_cast<

    }

    }

    /** Assignment

    /** Assignment

        After assignment, both views

        After assignment, both views

        reference the same underlying character

        reference the same underlying character

        buffer. Ownership is not transferred.

        buffer. Ownership is not transferred.

        @par Postconditions

        @par Postconditions

        @code

        @code

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

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

        @endcode

        @endcode

        @par Complexity

        @par Complexity

        Constant.

        Constant.

        @par Exception Safety

        @par Exception Safety

        Throws nothing.

        Throws nothing.

        @param other The other view.

        @param other The other view.

        @return A reference to this object.

        @return A reference to this object.

    */

    */

    url_view& operator=(

    url_view& operator=(

        url_view_base const& other) noexcept;

        url_view_base const& other) noexcept;

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

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

    //

    //

    // Observers

    // Observers

    //

    //

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

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

    /** Return the maximum number of characters possible

    /** Return the maximum number of characters possible

        This represents the largest number of

        This represents the largest number of

        characters that are possible in a url,

        characters that are possible in a url,

        not including any null terminator.

        not including any null terminator.

        @par Complexity

        @par Complexity

        Constant.

        Constant.

        @par Exception Safety

        @par Exception Safety

        Throws nothing.

        Throws nothing.

        @return The maximum number of characters possible.

        @return The maximum number of characters possible.

    */

    */

    static

    static

    constexpr

    constexpr

    std::size_t

    std::size_t

    max_size() noexcept

    max_size() noexcept

    {

    {

        return BOOST_URL_MAX_SIZE;

        return BOOST_URL_MAX_SIZE;

    }

    }

};

};

} // urls

} // urls

} // boost

} // boost

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

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

// std::hash specialization

// std::hash specialization

#ifndef BOOST_URL_DOCS

#ifndef BOOST_URL_DOCS

namespace std {

namespace std {

template<>

template<>

struct hash< ::boost::urls::url_view >

struct hash< ::boost::urls::url_view >

{

{

    hash() = default;

    hash() = default;

    hash(hash const&) = default;

    hash(hash const&) = default;

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

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

    explicit

    explicit

    {

    {

    std::size_t

    std::size_t

    {

    {

    }

    }

private:

private:

    std::size_t salt_ = 0;

    std::size_t salt_ = 0;

};

};

} // std

} // std

#endif

#endif

#endif

#endif