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_SEGMENTS_ENCODED_REF_HPP

#ifndef BOOST_URL_SEGMENTS_ENCODED_REF_HPP

#define BOOST_URL_SEGMENTS_ENCODED_REF_HPP

#define BOOST_URL_SEGMENTS_ENCODED_REF_HPP

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

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

#include <boost/url/segments_encoded_base.hpp>

#include <boost/url/segments_encoded_base.hpp>

#include <initializer_list>

#include <initializer_list>

#include <iterator>

#include <iterator>

namespace boost {

namespace boost {

namespace urls {

namespace urls {

#ifndef BOOST_URL_DOCS

#ifndef BOOST_URL_DOCS

class url_base;

class url_base;

class segments_encoded_view;

class segments_encoded_view;

#endif

#endif

/** Mutable encoded path segment proxy

/** Mutable encoded path segment proxy

    Exposes the percent-encoded segments of a

    Exposes the percent-encoded segments of a

    @ref url_base as a bidirectional range that

    @ref url_base as a bidirectional range that

    can modify the underlying URL. The proxy uses

    can modify the underlying URL. The proxy uses

    the URL’s storage directly, so the url must

    the URL’s storage directly, so the url must

    outlive any references.

    outlive any references.

    @par Example

    @par Example

    @code

    @code

    url u( "/path/to/file.txt" );

    url u( "/path/to/file.txt" );

    segments_encoded_ref ps = u.encoded_segments();

    segments_encoded_ref ps = u.encoded_segments();

    @endcode

    @endcode

    The strings returned when iterators are

    The strings returned when iterators are

    dereferenced have type @ref pct_string_view

    dereferenced have type @ref pct_string_view

    and may contain percent-escapes.

    and may contain percent-escapes.

    Reserved characters in inputs are

    Reserved characters in inputs are

    automatically escaped.

    automatically escaped.

    Escapes in inputs are preserved.

    Escapes in inputs are preserved.

    Exceptions are thrown on invalid inputs.

    Exceptions are thrown on invalid inputs.

    @par Iterator Invalidation

    @par Iterator Invalidation

    Changes to the underlying character buffer

    Changes to the underlying character buffer

    can invalidate iterators which reference it.

    can invalidate iterators which reference it.

    Modifications made through the container

    Modifications made through the container

    invalidate some or all iterators:

    invalidate some or all iterators:

    <br>

    <br>

    @li @ref push_back : Only `end()`.

    @li @ref push_back : Only `end()`.

    @li @ref assign, @ref clear,

    @li @ref assign, @ref clear,

        @ref operator= : All elements.

        @ref operator= : All elements.

    @li @ref erase : Erased elements and all

    @li @ref erase : Erased elements and all

        elements after (including `end()`).

        elements after (including `end()`).

    @li @ref insert : All elements at or after

    @li @ref insert : All elements at or after

        the insertion point (including `end()`).

        the insertion point (including `end()`).

    @li @ref replace : Modified

    @li @ref replace : Modified

        elements and all elements

        elements and all elements

        after (including `end()`).

        after (including `end()`).

    @see

    @see

        @ref segments_encoded_view,

        @ref segments_encoded_view,

        @ref segments_view,

        @ref segments_view,

        @ref segments_ref.

        @ref segments_ref.

*/

*/

class BOOST_SYMBOL_VISIBLE segments_encoded_ref

class BOOST_SYMBOL_VISIBLE segments_encoded_ref

    : public segments_encoded_base

    : public segments_encoded_base

{

{

    friend class url_base;

    friend class url_base;

    url_base* u_ = nullptr;

    url_base* u_ = nullptr;

    segments_encoded_ref(

    segments_encoded_ref(

        url_base& u) noexcept;

        url_base& u) noexcept;

public:

public:

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

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

    //

    //

    // Special Members

    // Special Members

    //

    //

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

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

    /** Constructor

    /** Constructor

        After construction, both views

        After construction, both views

        reference the same url. Ownership is not

        reference the same url. Ownership is not

        transferred; the caller is responsible

        transferred; the caller is responsible

        for ensuring the lifetime of the url

        for ensuring the lifetime of the url

        extends until it is no longer

        extends until it is no longer

        referenced.

        referenced.

        @par Postconditions

        @par Postconditions

        @code

        @code

        &this->url() == &other.url();

        &this->url() == &other.url();

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

    */

    */

    segments_encoded_ref(

    segments_encoded_ref(

        segments_encoded_ref const& other) = default;

        segments_encoded_ref const& other) = default;

    /** Assignment

    /** Assignment

        The existing contents are replaced

        The existing contents are replaced

        by a copy of the other segments.

        by a copy of the other segments.

        <br>

        <br>

        All iterators are invalidated.

        All iterators are invalidated.

        @note

        @note

        None of the character buffers referenced

        None of the character buffers referenced

        by `other` may overlap the buffer of the

        by `other` may overlap the buffer of the

        underlying url, or else the behavior

        underlying url, or else the behavior

        is undefined.

        is undefined.

        @par Effects

        @par Effects

        @code

        @code

        this->assign( other.begin(), other.end() );

        this->assign( other.begin(), other.end() );

        @endcode

        @endcode

        @par Complexity

        @par Complexity

        Linear in `other.buffer().size()`.

        Linear in `other.buffer().size()`.

        @par Exception Safety

        @par Exception Safety

        Strong guarantee.

        Strong guarantee.

        Calls to allocate may throw.

        Calls to allocate may throw.

        @param other The segments to assign.

        @param other The segments to assign.

        @return A reference to this object.

        @return A reference to this object.

    */

    */

    segments_encoded_ref&

    segments_encoded_ref&

    operator=(segments_encoded_ref const& other);

    operator=(segments_encoded_ref const& other);

    /// @copydoc operator=(segments_encoded_ref const&)

    /// @copydoc operator=(segments_encoded_ref const&)

    segments_encoded_ref&

    segments_encoded_ref&

    operator=(segments_encoded_view const& other);

    operator=(segments_encoded_view const& other);

    /** Assignment

    /** Assignment

        The existing contents are replaced

        The existing contents are replaced

        by a copy of the contents of the

        by a copy of the contents of the

        initializer list.

        initializer list.

        Reserved characters in the list are

        Reserved characters in the list are

        automatically escaped.

        automatically escaped.

        Escapes in the list are preserved.

        Escapes in the list are preserved.

        <br>

        <br>

        All iterators are invalidated.

        All iterators are invalidated.

        @par Example

        @par Example

        @code

        @code

        url u;

        url u;

        u.encoded_segments() = {"path", "to", "file.txt"};

        u.encoded_segments() = {"path", "to", "file.txt"};

        @endcode

        @endcode

        @par Preconditions

        @par Preconditions

        None of the character buffers referenced

        None of the character buffers referenced

        by the list may overlap the character buffer

        by the list may overlap the character buffer

        of the underlying url, or else the behavior

        of the underlying url, or else the behavior

        is undefined.

        is undefined.

        @par Effects

        @par Effects

        @code

        @code

        this->assign( init.begin(), init.end() );

        this->assign( init.begin(), init.end() );

        @endcode

        @endcode

        @par Complexity

        @par Complexity

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

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

        @par Exception Safety

        @par Exception Safety

        Strong guarantee.

        Strong guarantee.

        Calls to allocate may throw.

        Calls to allocate may throw.

        Exceptions thrown on invalid input.

        Exceptions thrown on invalid input.

        @throw system_error

        @throw system_error

        The list contains an invalid percent-encoding.

        The list contains an invalid percent-encoding.

        @param init The list of segments to assign.

        @param init The list of segments to assign.

        @return A reference to this.

        @return A reference to this.

    */

    */

    segments_encoded_ref&

    segments_encoded_ref&

    operator=(std::initializer_list<

    operator=(std::initializer_list<

        pct_string_view> init);

        pct_string_view> init);

    /** Conversion

    /** Conversion

        @see

        @see

            @ref segments_encoded_view.

            @ref segments_encoded_view.

        @return A view of the segments.

        @return A view of the segments.

    */

    */

    operator

    operator

    segments_encoded_view() const noexcept;

    segments_encoded_view() const noexcept;

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

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

    //

    //

    // Observers

    // Observers

    //

    //

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

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

    /** Return the referenced url

    /** Return the referenced url

        This function returns the url referenced

        This function returns the url referenced

        by the view.

        by the view.

        @par Example

        @par Example

        @code

        @code

        url u( "/path/to/file.txt" );

        url u( "/path/to/file.txt" );

        assert( &u.encoded_segments().url() == &u );

        assert( &u.encoded_segments().url() == &u );

        @endcode

        @endcode

        @par Exception Safety

        @par Exception Safety

        Throws nothing.

        Throws nothing.

        @return A reference to the url.

        @return A reference to the url.

    */

    */

    url_base&

    url_base&

    {

    {

    }

    }

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

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

    //

    //

    // Modifiers

    // Modifiers

    //

    //

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

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

    /** Clear the contents of the container

    /** Clear the contents of the container

        <br>

        <br>

        All iterators are invalidated.

        All iterators are invalidated.

        @par Effects

        @par Effects

        @code

        @code

        this->url().set_encoded_path( "" );

        this->url().set_encoded_path( "" );

        @endcode

        @endcode

        @par Postconditions

        @par Postconditions

        @code

        @code

        this->empty() == true

        this->empty() == true

        @endcode

        @endcode

        @par Complexity

        @par Complexity

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

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

        @par Exception Safety

        @par Exception Safety

        Throws nothing.

        Throws nothing.

    */

    */

    void

    void

    clear() noexcept;

    clear() noexcept;

    /** Assign segments

    /** Assign segments

        The existing contents are replaced

        The existing contents are replaced

        by a copy of the contents of the

        by a copy of the contents of the

        initializer list.

        initializer list.

        Reserved characters in the list are

        Reserved characters in the list are

        automatically escaped.

        automatically escaped.

        Escapes in the list are preserved.

        Escapes in the list are preserved.

        <br>

        <br>

        All iterators are invalidated.

        All iterators are invalidated.

        @note

        @note

        None of the character buffers referenced

        None of the character buffers referenced

        by the list may overlap the character

        by the list may overlap the character

        buffer of the underlying url, or else

        buffer of the underlying url, or else

        the behavior is undefined.

        the behavior is undefined.

        @par Example

        @par Example

        @code

        @code

        url u;

        url u;

        u.segments().assign( {"path", "to", "file.txt"} );

        u.segments().assign( {"path", "to", "file.txt"} );

        @endcode

        @endcode

        @par Complexity

        @par Complexity

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

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

        @par Exception Safety

        @par Exception Safety

        Strong guarantee.

        Strong guarantee.

        Calls to allocate may throw.

        Calls to allocate may throw.

        Exceptions thrown on invalid input.

        Exceptions thrown on invalid input.

        @throw system_error

        @throw system_error

        The list contains an invalid percent-encoding.

        The list contains an invalid percent-encoding.

        @param init The list of segments to assign.

        @param init The list of segments to assign.

    */

    */

    void

    void

    assign(std::initializer_list<

    assign(std::initializer_list<

        pct_string_view> init);

        pct_string_view> init);

    /** Assign segments

    /** Assign segments

        The existing contents are replaced

        The existing contents are replaced

        by a copy of the contents of the range.

        by a copy of the contents of the range.

        Reserved characters in the range are

        Reserved characters in the range are

        automatically escaped.

        automatically escaped.

        Escapes in the range are preserved.

        Escapes in the range are preserved.

        <br>

        <br>

        All iterators are invalidated.

        All iterators are invalidated.

        @note

        @note

        None of the character buffers referenced

        None of the character buffers referenced

        by the range may overlap the character

        by the range may overlap the character

        buffer of the underlying url, or else

        buffer of the underlying url, or else

        the behavior is undefined.

        the behavior is undefined.

        @par Mandates

        @par Mandates

        @code

        @code

        std::is_convertible< std::iterator_traits< FwdIt >::reference_type, pct_string_view >::value == true

        std::is_convertible< std::iterator_traits< FwdIt >::reference_type, pct_string_view >::value == true

        @endcode

        @endcode

        @par Complexity

        @par Complexity

        Linear in `std::distance( first, last ) + this->url().encoded_query().size() + this->url().encoded_fragment().size()`.

        Linear in `std::distance( first, last ) + this->url().encoded_query().size() + this->url().encoded_fragment().size()`.

        @par Exception Safety

        @par Exception Safety

        Strong guarantee.

        Strong guarantee.

        Calls to allocate may throw.

        Calls to allocate may throw.

        Exceptions thrown on invalid input.

        Exceptions thrown on invalid input.

        @throw system_error

        @throw system_error

        The range contains an invalid percent-encoding.

        The range contains an invalid percent-encoding.

        @param first The first element in the range.

        @param first The first element in the range.

        @param last One past the last element in the range.

        @param last One past the last element in the range.

    */

    */

    template<class FwdIt>

    template<class FwdIt>

    void

    void

    assign(FwdIt first, FwdIt last);

    assign(FwdIt first, FwdIt last);

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

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

    /** Insert segments

    /** Insert segments

        This function inserts a segment

        This function inserts a segment

        before the specified position.

        before the specified position.

        Reserved characters in the segment are

        Reserved characters in the segment are

        automatically escaped.

        automatically escaped.

        Escapes in the segment are preserved.

        Escapes in the segment are preserved.

        <br>

        <br>

        All iterators that are equal to

        All iterators that are equal to

        `before` or come after are invalidated.

        `before` or come after are invalidated.

        @par Complexity

        @par Complexity

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

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

        @par Exception Safety

        @par Exception Safety

        Strong guarantee.

        Strong guarantee.

        Calls to allocate may throw.

        Calls to allocate may throw.

        Exceptions thrown on invalid input.

        Exceptions thrown on invalid input.

        @throw system_error

        @throw system_error

        The segment contains an invalid percent-encoding.

        The segment contains an invalid percent-encoding.

        @return An iterator to the inserted

        @return An iterator to the inserted

        segment.

        segment.

        @param before An iterator before which

        @param before An iterator before which

        the segment is inserted. This may

        the segment is inserted. This may

        be equal to `end()`.

        be equal to `end()`.

        @param s The segment to insert.

        @param s The segment to insert.

    */

    */

    iterator

    iterator

    insert(

    insert(

        iterator before,

        iterator before,

        pct_string_view s);

        pct_string_view s);

    /** Insert segments

    /** Insert segments

        This function inserts the segments

        This function inserts the segments

        in an initializer list before the

        in an initializer list before the

        specified position.

        specified position.

        Reserved characters in the list are

        Reserved characters in the list are

        automatically escaped.

        automatically escaped.

        Escapes in the list are preserved.

        Escapes in the list are preserved.

        <br>

        <br>

        All iterators that are equal to

        All iterators that are equal to

        `before` or come after are invalidated.

        `before` or come after are invalidated.

        @note

        @note

        None of the character buffers referenced

        None of the character buffers referenced

        by the list may overlap the character

        by the list may overlap the character

        buffer of the underlying url, or else

        buffer of the underlying url, or else

        the behavior is undefined.

        the behavior is undefined.

        @par Example

        @par Example

        @code

        @code

        url u( "/file.txt" );

        url u( "/file.txt" );

        u.encoded_segments().insert( u.encoded_segments().begin(), { "path", "to" } );

        u.encoded_segments().insert( u.encoded_segments().begin(), { "path", "to" } );

        @endcode

        @endcode

        @par Complexity

        @par Complexity

        Linear in `init.size() + this->url().encoded_resource().size()`.

        Linear in `init.size() + this->url().encoded_resource().size()`.

        @par Exception Safety

        @par Exception Safety

        Strong guarantee.

        Strong guarantee.

        Calls to allocate may throw.

        Calls to allocate may throw.

        Exceptions thrown on invalid input.

        Exceptions thrown on invalid input.

        @throw system_error

        @throw system_error

        The list contains an invalid percent-encoding.

        The list contains an invalid percent-encoding.

        @return An iterator to the first

        @return An iterator to the first

        element inserted, or `before` if

        element inserted, or `before` if

        `init.size() == 0`.

        `init.size() == 0`.

        @param before An iterator before which

        @param before An iterator before which

        the list is inserted. This may

        the list is inserted. This may

        be equal to `end()`.

        be equal to `end()`.

        @param init The list of segments to insert.

        @param init The list of segments to insert.

    */

    */

    iterator

    iterator

    insert(

    insert(

        iterator before,

        iterator before,

        std::initializer_list<

        std::initializer_list<

            pct_string_view> init);

            pct_string_view> init);

    /** Insert segments

    /** Insert segments

        This function inserts the segments in

        This function inserts the segments in

        a range before the specified position.

        a range before the specified position.

        Reserved characters in the range are

        Reserved characters in the range are

        automatically escaped.

        automatically escaped.

        Escapes in the range are preserved.

        Escapes in the range are preserved.

        <br>

        <br>

        All iterators that are equal to

        All iterators that are equal to

        `before` or come after are invalidated.

        `before` or come after are invalidated.

        @note

        @note

        None of the character buffers referenced

        None of the character buffers referenced

        by the range may overlap the character

        by the range may overlap the character

        buffer of the underlying url, or else

        buffer of the underlying url, or else

        the behavior is undefined.

        the behavior is undefined.

        @par Mandates

        @par Mandates

        @code

        @code

        std::is_convertible< std::iterator_traits< FwdIt >::reference_type, pct_string_view >::value == true

        std::is_convertible< std::iterator_traits< FwdIt >::reference_type, pct_string_view >::value == true

        @endcode

        @endcode

        @par Complexity

        @par Complexity

        Linear in `std::distance( first, last ) + this->url().encoded_resource().size()`.

        Linear in `std::distance( first, last ) + this->url().encoded_resource().size()`.

        @par Exception Safety

        @par Exception Safety

        Strong guarantee.

        Strong guarantee.

        Calls to allocate may throw.

        Calls to allocate may throw.

        Exceptions thrown on invalid input.

        Exceptions thrown on invalid input.

        @throw system_error

        @throw system_error

        The range contains an invalid percent-encoding.

        The range contains an invalid percent-encoding.

        @return An iterator to the first

        @return An iterator to the first

        segment inserted, or `before` if

        segment inserted, or `before` if

        `init.empty()`.

        `init.empty()`.

        @param before An iterator before which

        @param before An iterator before which

        the range is inserted. This may

        the range is inserted. This may

        be equal to `end()`.

        be equal to `end()`.

        @param first The first element in the range to insert.

        @param first The first element in the range to insert.

        @param last One past the last element in the range to insert.

        @param last One past the last element in the range to insert.

    */

    */

    template<class FwdIt>

    template<class FwdIt>

    iterator

    iterator

    insert(

    insert(

        iterator before,

        iterator before,

        FwdIt first,

        FwdIt first,

        FwdIt last);

        FwdIt last);

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

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

    /** Erase segments

    /** Erase segments

        This function removes a segment.

        This function removes a segment.

        <br>

        <br>

        All iterators that are equal to

        All iterators that are equal to

        `pos` or come after are invalidated.

        `pos` or come after are invalidated.

        @par Complexity

        @par Complexity

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

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

        @par Exception Safety

        @par Exception Safety

        Throws nothing.

        Throws nothing.

        @return An iterator to one past

        @return An iterator to one past

        the removed segment.

        the removed segment.

        @param pos An iterator to the element.

        @param pos An iterator to the element.

    */

    */

    iterator

    iterator

    erase(

    erase(

        iterator pos) noexcept;

        iterator pos) noexcept;

    /** Erase segments

    /** Erase segments

        This function removes a range of segments

        This function removes a range of segments

        from the container.

        from the container.

        <br>

        <br>

        All iterators that are equal to

        All iterators that are equal to

        `first` or come after are invalidated.

        `first` or come after are invalidated.