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_REF_HPP

#ifndef BOOST_URL_SEGMENTS_REF_HPP

#define BOOST_URL_SEGMENTS_REF_HPP

#define BOOST_URL_SEGMENTS_REF_HPP

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

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

#include <boost/url/segments_base.hpp>

#include <boost/url/segments_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_view;

class segments_view;

#endif

#endif

/** Mutable decoded path segment proxy

/** Mutable decoded path segment proxy

    Presents the decoded path segments of a

    Presents the decoded path segments of a

    @ref url_base as a bidirectional range whose

    @ref url_base as a bidirectional range whose

    modifiers update the underlying URL. The proxy

    modifiers update the underlying URL. The proxy

    references the URL’s storage directly, so the

    references the URL’s storage directly, so the

    owning URL must remain alive while the proxy

    owning URL must remain alive while the proxy

    is used.

    is used.

    @par Example

    @par Example

    @code

    @code

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

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

    segments_ref ps = u.segments();

    segments_ref ps = u.segments();

    @endcode

    @endcode

    Percent escapes in strings returned when

    Percent escapes in strings returned when

    dereferencing iterators are automatically

    dereferencing iterators are automatically

    decoded.

    decoded.

    Reserved characters in strings supplied

    Reserved characters in strings supplied

    to modifier functions are automatically

    to modifier functions are automatically

    percent-escaped.

    percent-escaped.

    @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_ref,

        @ref segments_encoded_ref,

        @ref segments_encoded_view,

        @ref segments_encoded_view,

        @ref segments_view.

        @ref segments_view.

*/

*/

class segments_ref

class segments_ref

    : public segments_base

    : public segments_base

{

{

    url_base* u_ = nullptr;

    url_base* u_ = nullptr;

    friend class url_base;

    friend class url_base;

    friend class segments_encoded_ref;

    friend class segments_encoded_ref;

    segments_ref(url_base& u) noexcept;

    segments_ref(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_ref(

    segments_ref(

        segments_ref const& other) = default;

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

    */

    */

    BOOST_URL_DECL

    BOOST_URL_DECL

    segments_ref&

    segments_ref&

    operator=(segments_ref const& other);

    operator=(segments_ref const& other);

    /// @copydoc segments_ref::operator=(segments_ref const&)

    /// @copydoc segments_ref::operator=(segments_ref const&)

    BOOST_URL_DECL

    BOOST_URL_DECL

    segments_ref&

    segments_ref&

    operator=(segments_view const& other);

    operator=(segments_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.

        <br>

        <br>

        All iterators are invalidated.

        All iterators are invalidated.

        @par Example

        @par Example

        @code

        @code

        url u;

        url u;

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

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

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

        @param init The list of segments to assign.

        @param init The list of segments to assign.

        @return A reference to this object.

        @return A reference to this object.

    */

    */

    BOOST_URL_DECL

    BOOST_URL_DECL

    segments_ref&

    segments_ref&

    operator=(std::initializer_list<

    operator=(std::initializer_list<

        core::string_view> init);

        core::string_view> init);

    /** Conversion

    /** Conversion

        @see

        @see

            @ref segments_view.

            @ref segments_view.

        @return A view of the segments.

        @return A view of the segments.

    */

    */

    BOOST_URL_DECL

    BOOST_URL_DECL

    operator

    operator

    segments_view() const noexcept;

    segments_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.segments().url() == &u );

        assert( &u.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.

        <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 `init` may overlap the character buffer

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

        @param init The list of segments to assign.

        @param init The list of segments to assign.

    */

    */

    BOOST_URL_DECL

    BOOST_URL_DECL

    void

    void

    assign(std::initializer_list<

    assign(std::initializer_list<

        core::string_view> init);

        core::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.

        <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, core::string_view >::value == true

        std::is_convertible< std::iterator_traits< FwdIt >::reference_type, core::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.

        @param first The beginning of the range of segments to assign.

        @param first The beginning of the range of segments to assign.

        @param last The end of the range of segments to assign.

        @param last The end of the range of segments to assign.

    */

    */

    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.

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

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

    */

    */

    BOOST_URL_DECL

    BOOST_URL_DECL

    iterator

    iterator

    insert(

    insert(

        iterator before,

        iterator before,

        core::string_view s);

        core::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

        percent-escaped in the result.

        percent-escaped in the result.

        <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.segments().insert( u.segments().begin(), { "path", "to" } );

        u.segments().insert( u.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.

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

    */

    */

    BOOST_URL_DECL

    BOOST_URL_DECL

    iterator

    iterator

    insert(

    insert(

        iterator before,

        iterator before,

        std::initializer_list<core::string_view> init);

        std::initializer_list<core::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 list are

        Reserved characters in the list are

        automatically escaped.

        automatically escaped.

        <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, core::string_view >::value == true

        std::is_convertible< std::iterator_traits< FwdIt >::reference_type, core::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.

        @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 beginning of the range of segments to insert.

        @param first The beginning of the range of segments to insert.

        @param last The end of the range of segments to insert.

        @param last The end of the range of segments 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 segment.

        @param pos An iterator to the segment.

    */

    */

    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.

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

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

        the removed range.

        @param first The beginning of the range to remove.

        @param first The beginning of the range to remove.

        @param last The end of the range to remove.

        @param last The end of the range to remove.

    */

    */

    BOOST_URL_DECL

    BOOST_URL_DECL

    iterator

    iterator

    erase(

    erase(

        iterator first,

        iterator first,

        iterator last) noexcept;

        iterator last) noexcept;

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

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

    /** Replace segments

    /** Replace segments

        This function replaces the segment at

        This function replaces the segment at

        the specified position.

        the specified position.

        Reserved characters in the string are

        Reserved characters in the string are

        automatically escaped.

        automatically escaped.