Diff coverage report for

//

//

// 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_DECODE_VIEW_HPP

#ifndef BOOST_URL_DECODE_VIEW_HPP

#define BOOST_URL_DECODE_VIEW_HPP

#define BOOST_URL_DECODE_VIEW_HPP

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

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

#include <boost/core/detail/string_view.hpp>

#include <boost/core/detail/string_view.hpp>

#include <boost/url/encoding_opts.hpp>

#include <boost/url/encoding_opts.hpp>

#include <boost/url/pct_string_view.hpp>

#include <boost/url/pct_string_view.hpp>

#include <type_traits>

#include <type_traits>

#include <iterator>

#include <iterator>

#include <iosfwd>

#include <iosfwd>

namespace boost {

namespace boost {

namespace urls {

namespace urls {

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

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

class decode_view;

class decode_view;

namespace detail {

namespace detail {

// unchecked

// unchecked

template<class... Args>

template<class... Args>

decode_view

decode_view

make_decode_view(

make_decode_view(

    Args&&... args) noexcept;

    Args&&... args) noexcept;

} // detail

} // detail

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

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

/** A reference to a valid, percent-encoded string

/** A reference to a valid, percent-encoded string

    These views reference strings in parts of URLs

    These views reference strings in parts of URLs

    or other components that are percent-encoded.

    or other components that are percent-encoded.

    The special characters (those not in the

    The special characters (those not in the

    allowed character set) are stored as three

    allowed character set) are stored as three

    character escapes that consist of a percent

    character escapes that consist of a percent

    sign ('%%') followed by a two-digit hexadecimal

    sign ('%%') followed by a two-digit hexadecimal

    number of the corresponding unescaped character

    number of the corresponding unescaped character

    code, which may be part of a UTF-8 code point

    code, which may be part of a UTF-8 code point

    depending on the context.

    depending on the context.

    The view refers to the original character

    The view refers to the original character

    buffer and only decodes escaped sequences when

    buffer and only decodes escaped sequences when

    needed. In particular these operations perform

    needed. In particular these operations perform

    percent-decoding automatically without the

    percent-decoding automatically without the

    need to allocate memory:

    need to allocate memory:

    @li Iteration of the string

    @li Iteration of the string

    @li Accessing the encoded character buffer

    @li Accessing the encoded character buffer

    @li Comparison to encoded or plain strings

    @li Comparison to encoded or plain strings

    These objects can only be constructed from

    These objects can only be constructed from

    strings that have a valid percent-encoding,

    strings that have a valid percent-encoding,

    otherwise construction fails. The caller is

    otherwise construction fails. The caller is

    responsible for ensuring that the lifetime

    responsible for ensuring that the lifetime

    of the character buffer from which the view

    of the character buffer from which the view

    is constructed extends unmodified until the

    is constructed extends unmodified until the

    view is no longer accessed.

    view is no longer accessed.

*/

*/

class decode_view

class decode_view

{

{

    char const* p_ = nullptr;

    char const* p_ = nullptr;

    std::size_t n_ = 0;

    std::size_t n_ = 0;

    std::size_t dn_ = 0;

    std::size_t dn_ = 0;

    bool space_as_plus_ = true;

    bool space_as_plus_ = true;

    template<class... Args>

    template<class... Args>

    friend

    friend

    decode_view

    decode_view

    detail::make_decode_view(

    detail::make_decode_view(

        Args&&... args) noexcept;

        Args&&... args) noexcept;

    // unchecked

    // unchecked

    BOOST_CXX14_CONSTEXPR

    BOOST_CXX14_CONSTEXPR

    explicit

    explicit

        core::string_view s,

        core::string_view s,

        std::size_t n,

        std::size_t n,

        encoding_opts opt) noexcept

        encoding_opts opt) noexcept

public:

public:

    /** The value type

    /** The value type

    */

    */

    using value_type = char;

    using value_type = char;

    /** The reference type

    /** The reference type

    */

    */

    using reference = char;

    using reference = char;

    /// @copydoc reference

    /// @copydoc reference

    using const_reference = char;

    using const_reference = char;

    /** The unsigned integer type

    /** The unsigned integer type

    */

    */

    using size_type = std::size_t;

    using size_type = std::size_t;

    /** The signed integer type

    /** The signed integer type

    */

    */

    using difference_type = std::ptrdiff_t;

    using difference_type = std::ptrdiff_t;

    /** An iterator of constant, decoded characters.

    /** An iterator of constant, decoded characters.

        This iterator is used to access the encoded

        This iterator is used to access the encoded

        string as a *bidirectional* range of characters

        string as a *bidirectional* range of characters

        with percent-decoding applied. Escape sequences

        with percent-decoding applied. Escape sequences

        are not decoded until the iterator is

        are not decoded until the iterator is

        dereferenced.

        dereferenced.

    */

    */

    class iterator;

    class iterator;

    /// @copydoc iterator

    /// @copydoc iterator

    using const_iterator = iterator;

    using const_iterator = iterator;

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

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

    //

    //

    // Special Members

    // Special Members

    //

    //

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

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

    /** Constructor

    /** Constructor

        Default-constructed views represent

        Default-constructed views represent

        empty strings.

        empty strings.

        @par Example

        @par Example

        @code

        @code

        decode_view ds;

        decode_view ds;

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

    */

    */

    BOOST_CXX14_CONSTEXPR

    BOOST_CXX14_CONSTEXPR

    decode_view() noexcept = default;

    decode_view() noexcept = default;

    /** Constructor

    /** Constructor

        This constructs a view from the character

        This constructs a view from the character

        buffer `s`, which must remain valid and

        buffer `s`, which must remain valid and

        unmodified until the view is no longer

        unmodified until the view is no longer

        accessed.

        accessed.

        @par Example

        @par Example

        @code

        @code

        decode_view ds( "Program%20Files" );

        decode_view ds( "Program%20Files" );

        @endcode

        @endcode

        @par Postconditions

        @par Postconditions

        @code

        @code

        this->encoded() == s

        this->encoded() == s

        @endcode

        @endcode

        @par Complexity

        @par Complexity

        Linear in `s.size()`.

        Linear in `s.size()`.

        @par Exception Safety

        @par Exception Safety

        Although this function does not throw exceptions,

        Although this function does not throw exceptions,

        implicitly constructing a @ref pct_string_view

        implicitly constructing a @ref pct_string_view

        for the first argument can throw exceptions

        for the first argument can throw exceptions

        on invalid input.

        on invalid input.

        @param s A percent-encoded string that has

        @param s A percent-encoded string that has

        already been validated. Implicit conversion

        already been validated. Implicit conversion

        from other string types is supported but

        from other string types is supported but

        may throw exceptions.

        may throw exceptions.

        @param opt The options for decoding. If

        @param opt The options for decoding. If

        this parameter is omitted, the default

        this parameter is omitted, the default

        options are used.

        options are used.

    */

    */

    BOOST_CXX14_CONSTEXPR

    BOOST_CXX14_CONSTEXPR

    explicit

    explicit

        pct_string_view s,

        pct_string_view s,

        encoding_opts opt = {}) noexcept

        encoding_opts opt = {}) noexcept

            detail::to_sv(s),

            detail::to_sv(s),

            s.decoded_size(),

            s.decoded_size(),

    {

    {

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

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

    //

    //

    // Observers

    // Observers

    //

    //

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

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

    /** Return true if the string is empty

    /** Return true if the string is empty

        @par Example

        @par Example

        @code

        @code

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

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

        @endcode

        @endcode

        @par Complexity

        @par Complexity

        Constant.

        Constant.

        @par Exception Safety

        @par Exception Safety

        Throws nothing.

        Throws nothing.

        @return `true` if the string is empty

        @return `true` if the string is empty

    */

    */

    bool

    bool

    {

    {

    }

    }

    /** Return the number of decoded characters

    /** Return the number of decoded characters

        @par Example

        @par Example

        @code

        @code

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

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

        @endcode

        @endcode

        @par Effects

        @par Effects

        @code

        @code

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

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

        @endcode

        @endcode

        @par Complexity

        @par Complexity

        Constant.

        Constant.

        @par Exception Safety

        @par Exception Safety

        Throws nothing.

        Throws nothing.

        @return The number of decoded characters

        @return The number of decoded characters

    */

    */

    size_type

    size_type

    {

    {

    }

    }

    /** Return an iterator to the beginning

    /** Return an iterator to the beginning

        @par Example

        @par Example

        @code

        @code

        auto it = this->begin();

        auto it = this->begin();

        @endcode

        @endcode

        @par Complexity

        @par Complexity

        Constant.

        Constant.

        @par Exception Safety

        @par Exception Safety

        Throws nothing.

        Throws nothing.

        @return An iterator to the first decoded character

        @return An iterator to the first decoded character

    */

    */

    iterator

    iterator

    begin() const noexcept;

    begin() const noexcept;

    /** Return an iterator to the end

    /** Return an iterator to the end

        @par Example

        @par Example

        @code

        @code

        auto it = this->end();

        auto it = this->end();

        @endcode

        @endcode

        @par Complexity

        @par Complexity

        Constant.

        Constant.

        @par Exception Safety

        @par Exception Safety

        Throws nothing.

        Throws nothing.

        @return An iterator to one past the last decoded character

        @return An iterator to one past the last decoded character

    */

    */

    iterator

    iterator

    end() const noexcept;

    end() const noexcept;

    /** Return the first character

    /** Return the first character

        @par Example

        @par Example

        @code

        @code

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

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

        @endcode

        @endcode

        @par Preconditions

        @par Preconditions

        @code

        @code

        not this->empty()

        not this->empty()

        @endcode

        @endcode

        @par Complexity

        @par Complexity

        Constant.

        Constant.

        @par Exception Safety

        @par Exception Safety

        Throws nothing.

        Throws nothing.

        @return The first decoded character

        @return The first decoded character

    */

    */

    reference

    reference

    front() const noexcept;

    front() const noexcept;

    /** Return the last character

    /** Return the last character

        @par Example

        @par Example

        @code

        @code

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

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

        @endcode

        @endcode

        @par Preconditions

        @par Preconditions

        @code

        @code

        not this->empty()

        not this->empty()

        @endcode

        @endcode

        @par Complexity

        @par Complexity

        Constant.

        Constant.

        @par Exception Safety

        @par Exception Safety

        Throws nothing.

        Throws nothing.

        @return The last decoded character

        @return The last decoded character

    */

    */

    reference

    reference

    back() const noexcept;

    back() const noexcept;

    /** Checks if the string begins with the given prefix

    /** Checks if the string begins with the given prefix

        @par Example

        @par Example

        @code

        @code

        assert( decode_view( "Program%20Files" ).starts_with("Program") );

        assert( decode_view( "Program%20Files" ).starts_with("Program") );

        @endcode

        @endcode

        @par Complexity

        @par Complexity

        Linear.

        Linear.

        @par Exception Safety

        @par Exception Safety

        Throws nothing.

        Throws nothing.

        @param s The string to search for

        @param s The string to search for

        @return `true` if the decoded string starts with `s`

        @return `true` if the decoded string starts with `s`

    */

    */

    BOOST_URL_DECL

    BOOST_URL_DECL

    bool

    bool

    starts_with( core::string_view s ) const noexcept;

    starts_with( core::string_view s ) const noexcept;

    /** Checks if the string ends with the given prefix

    /** Checks if the string ends with the given prefix

        @par Example

        @par Example

        @code

        @code

        assert( decode_view( "Program%20Files" ).ends_with("Files") );

        assert( decode_view( "Program%20Files" ).ends_with("Files") );

        @endcode

        @endcode

        @par Complexity

        @par Complexity

        Linear.

        Linear.

        @par Exception Safety

        @par Exception Safety

        Throws nothing.

        Throws nothing.

        @param s The string to search for

        @param s The string to search for

        @return `true` if the decoded string ends with `s`

        @return `true` if the decoded string ends with `s`

    */

    */

    BOOST_URL_DECL

    BOOST_URL_DECL

    bool

    bool

    ends_with( core::string_view s ) const noexcept;

    ends_with( core::string_view s ) const noexcept;

    /** Checks if the string begins with the given prefix

    /** Checks if the string begins with the given prefix

        @par Example

        @par Example

        @code

        @code

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

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

        @endcode

        @endcode

        @par Complexity

        @par Complexity

        Constant.

        Constant.

        @par Exception Safety

        @par Exception Safety

        Throws nothing.

        Throws nothing.

        @param ch The character to search for

        @param ch The character to search for

        @return `true` if the decoded string starts with `ch`

        @return `true` if the decoded string starts with `ch`

    */

    */

    BOOST_URL_DECL

    BOOST_URL_DECL

    bool

    bool

    starts_with( char ch ) const noexcept;

    starts_with( char ch ) const noexcept;

    /** Checks if the string ends with the given prefix

    /** Checks if the string ends with the given prefix

        @par Example

        @par Example

        @code

        @code

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

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

        @endcode

        @endcode

        @par Complexity

        @par Complexity

        Constant.

        Constant.

        @par Exception Safety

        @par Exception Safety

        Throws nothing.

        Throws nothing.

        @param ch The character to search for

        @param ch The character to search for

        @return `true` if the decoded string ends with `ch`

        @return `true` if the decoded string ends with `ch`

    */

    */

    BOOST_URL_DECL

    BOOST_URL_DECL

    bool

    bool

    ends_with( char ch ) const noexcept;

    ends_with( char ch ) const noexcept;

    /** Finds the first occurrence of character in this view

    /** Finds the first occurrence of character in this view

        @par Complexity

        @par Complexity

        Linear.

        Linear.

        @par Exception Safety

        @par Exception Safety

        Throws nothing.

        Throws nothing.

        @param ch The character to search for

        @param ch The character to search for

        @return An iterator to the first decoded occurrence of `ch` or `end()`

        @return An iterator to the first decoded occurrence of `ch` or `end()`

    */

    */

    BOOST_URL_DECL

    BOOST_URL_DECL

    const_iterator

    const_iterator

    find( char ch ) const noexcept;

    find( char ch ) const noexcept;

    /** Finds the first occurrence of character in this view

    /** Finds the first occurrence of character in this view

        @par Complexity

        @par Complexity

        Linear.

        Linear.

        @par Exception Safety

        @par Exception Safety

        Throws nothing.

        Throws nothing.

        @param ch The character to search for

        @param ch The character to search for

        @return An iterator to the last occurrence of `ch` or `end()`

        @return An iterator to the last occurrence of `ch` or `end()`

    */

    */

    BOOST_URL_DECL

    BOOST_URL_DECL

    const_iterator

    const_iterator

    rfind( char ch ) const noexcept;

    rfind( char ch ) const noexcept;

    /** Remove the first characters

    /** Remove the first characters

        @par Example

        @par Example

        @code

        @code

        decode_view d( "Program%20Files" );

        decode_view d( "Program%20Files" );

        d.remove_prefix( 8 );

        d.remove_prefix( 8 );

        assert( d == "Files" );

        assert( d == "Files" );

        @endcode

        @endcode

        @par Preconditions

        @par Preconditions

        @code

        @code

        not this->empty()

        not this->empty()

        @endcode

        @endcode

        @par Complexity

        @par Complexity

        Linear.

        Linear.

        @param n The number of characters to remove

        @param n The number of characters to remove

    */

    */

    BOOST_URL_DECL

    BOOST_URL_DECL

    void

    void

    remove_prefix( size_type n );

    remove_prefix( size_type n );

    /** Remove the last characters

    /** Remove the last characters

        @par Example

        @par Example

        @code

        @code

        decode_view d( "Program%20Files" );

        decode_view d( "Program%20Files" );

        d.remove_prefix( 6 );

        d.remove_prefix( 6 );

        assert( d == "Program" );

        assert( d == "Program" );

        @endcode

        @endcode

        @par Preconditions

        @par Preconditions

        @code

        @code

        not this->empty()

        not this->empty()

        @endcode

        @endcode

        @par Complexity

        @par Complexity

        Linear.

        Linear.

        @param n The number of characters to remove

        @param n The number of characters to remove

    */

    */

    BOOST_URL_DECL

    BOOST_URL_DECL

    void

    void

    remove_suffix( size_type n );

    remove_suffix( size_type n );

    /** Return the decoding options

    /** Return the decoding options

        @return The decoding options used by this view

        @return The decoding options used by this view

     */

     */

    encoding_opts

    encoding_opts

    options() const noexcept

    options() const noexcept

    {

    {

        encoding_opts opt;

        encoding_opts opt;

        opt.space_as_plus = space_as_plus_;

        opt.space_as_plus = space_as_plus_;

        return opt;

        return opt;

    }

    }

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

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

    //

    //

    // Comparison

    // Comparison

    //

    //

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

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

    /** Return the result of comparing to another string

    /** Return the result of comparing to another string

        The length of the sequences to compare is the smaller of

        The length of the sequences to compare is the smaller of

        `size()` and `other.size()`.

        `size()` and `other.size()`.

        The function compares the two strings as if by calling

        The function compares the two strings as if by calling

        `char_traits<char>::compare(to_string().data(), v.data(), rlen)`.

        `char_traits<char>::compare(to_string().data(), v.data(), rlen)`.

        This means the comparison is performed with

        This means the comparison is performed with

        percent-decoding applied to the current string.

        percent-decoding applied to the current string.

        @param other string to compare

        @param other string to compare

        @return Negative value if this string is less than the other

        @return Negative value if this string is less than the other

        character sequence, zero if the both character sequences are

        character sequence, zero if the both character sequences are

        equal, positive value if this string is greater than the other

        equal, positive value if this string is greater than the other

        character sequence

        character sequence

    */

    */

    BOOST_CXX14_CONSTEXPR

    BOOST_CXX14_CONSTEXPR