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_PARAMS_REF_HPP

#ifndef BOOST_URL_PARAMS_REF_HPP

#define BOOST_URL_PARAMS_REF_HPP

#define BOOST_URL_PARAMS_REF_HPP

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

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

#include <boost/url/ignore_case.hpp>

#include <boost/url/ignore_case.hpp>

#include <boost/url/params_base.hpp>

#include <boost/url/params_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 params_view;

class params_view;

#endif

#endif

/** Mutable decoded query parameter proxy

/** Mutable decoded query parameter proxy

    This container presents the decoded query

    This container presents the decoded query

    parameters of a @ref url_base as a bidirectional

    parameters of a @ref url_base as a bidirectional

    range whose modifying operations update the

    range whose modifying operations update the

    underlying URL in-place. It references (but

    underlying URL in-place. It references (but

    does not own) the character buffer, so the

    does not own) the character buffer, so the

    referenced URL must stay alive while the proxy

    referenced URL must stay alive while the proxy

    is used.

    is used.

    <br>

    <br>

    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 Example

    @par Example

    @code

    @code

    url u( "?first=John&last=Doe" );

    url u( "?first=John&last=Doe" );

    params_ref p = u.params();

    params_ref p = u.params();

    @endcode

    @endcode

    @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 append : Only `end()`.

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

    @li @ref assign, @ref clear,

    @li @ref assign, @ref clear,

        `operator=` : All elements.

        `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, @ref set : Modified

    @li @ref replace, @ref set : Modified

        elements and all elements

        elements and all elements

        after (including `end()`).

        after (including `end()`).

    @par Reads vs. writes

    @par Reads vs. writes

    Although this is a mutable proxy, all

    Although this is a mutable proxy, all

    observer helpers inherited from

    observer helpers inherited from

    @ref params_base (such as @ref contains,

    @ref params_base (such as @ref contains,

    @ref find, and @ref get_or) operate in the

    @ref find, and @ref get_or) operate in the

    same way as they do on @ref params_view:

    same way as they do on @ref params_view:

    they perform their lookup against the

    they perform their lookup against the

    current contents of the referenced URL

    current contents of the referenced URL

    without modifying it.

    without modifying it.

*/

*/

class BOOST_URL_DECL params_ref

class BOOST_URL_DECL params_ref

    : public params_base

    : public params_base

{

{

    friend class url_base;

    friend class url_base;

    url_base* u_ = nullptr;

    url_base* u_ = nullptr;

    params_ref(

    params_ref(

        url_base& u,

        url_base& u,

        encoding_opts opt) noexcept;

        encoding_opts opt) 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.

    */

    */

    params_ref(

    params_ref(

        params_ref const& other) = default;

        params_ref const& other) = default;

    /** Constructor

    /** Constructor

        After construction, both views will

        After construction, both views will

        reference the same url but this

        reference the same url but this

        instance will use the specified

        instance will use the specified

        @ref encoding_opts when the values

        @ref encoding_opts when the values

        are decoded.

        are decoded.

        Ownership is not transferred; the

        Ownership is not transferred; the

        caller is responsible for ensuring

        caller is responsible for ensuring

        the lifetime of the url extends

        the lifetime of the url extends

        until it is no longer referenced.

        until it is no longer 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.

        @param opt The options for decoding. If

        @param opt The options for decoding. If

        this parameter is omitted, `space_as_plus`

        this parameter is omitted, `space_as_plus`

        is used.

        is used.

    */

    */

    params_ref(

    params_ref(

        params_ref const& other,

        params_ref const& other,

        encoding_opts opt) noexcept;

        encoding_opts opt) noexcept;

    /** Assignment

    /** Assignment

        The previous contents of this are

        The previous contents of this are

        replaced by the contents of `other.

        replaced by the contents of `other.

        <br>

        <br>

        All iterators are invalidated.

        All iterators are invalidated.

        @note

        @note

        The strings referenced by `other`

        The strings referenced by `other`

        must not come from the underlying url,

        must not come from the underlying url,

        or else the behavior is undefined.

        or else the behavior 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 params to assign.

        @param other The params to assign.

        @return `*this`

        @return `*this`

    */

    */

    params_ref&

    params_ref&

    operator=(

    operator=(

        params_ref const& other);

        params_ref const& other);

    /** Assignment

    /** Assignment

        After assignment, the previous contents

        After assignment, the previous contents

        of the query parameters are replaced by

        of the query parameters are replaced by

        the contents of the initializer-list.

        the contents of the initializer-list.

        @par Preconditions

        @par Preconditions

        None of character buffers referenced by

        None of character buffers referenced by

        `init` may overlap the character buffer of

        `init` may overlap the character buffer of

        the underlying url, or else the behavior

        the underlying url, or else the behavior

        is undefined.

        is undefined.

        @par Effects

        @par Effects

        @code

        @code

        this->assign( init );

        this->assign( init );

        @endcode

        @endcode

        @par Complexity

        @par Complexity

        Linear in `init.size()`.

        Linear in `init.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 params to assign.

        @param init The list of params to assign.

        @return `*this`

        @return `*this`

    */

    */

    params_ref&

    params_ref&

    operator=(

    operator=(

        std::initializer_list<

        std::initializer_list<

            param_view> init);

            param_view> init);

    /** Conversion

    /** Conversion

        @return A view of the query parameters.

        @return A view of the query parameters.

    */

    */

    operator

    operator

    params_view() const noexcept;

    params_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( "?key=value" );

        url u( "?key=value" );

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

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

        @endcode

        @endcode

        @par Exception Safety

        @par Exception Safety

        @code

        @code

        Throws nothing.

        Throws nothing.

        @endcode

        @endcode

        @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().remove_query();

        this->url().remove_query();

        @endcode

        @endcode

        @par Postconditions

        @par Postconditions

        @code

        @code

        this->empty() == true && this->url().has_query() == false

        this->empty() == true && this->url().has_query() == false

        @endcode

        @endcode

        @par Complexity

        @par Complexity

        Constant.

        Constant.

        @par Exception Safety

        @par Exception Safety

        Throws nothing.

        Throws nothing.

    */

    */

    void

    void

    clear() noexcept;

    clear() noexcept;

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

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

    /** Assign elements

    /** Assign elements

        This function replaces the entire

        This function replaces the entire

        contents of the view with the params

        contents of the view with the params

        in the <em>initializer-list</em>.

        in the <em>initializer-list</em>.

        <br>

        <br>

        All iterators are invalidated.

        All iterators are invalidated.

        @note

        @note

        The strings referenced by the inputs

        The strings referenced by the inputs

        must not come from the underlying url,

        must not come from the underlying url,

        or else the behavior is undefined.

        or else the behavior is undefined.

        @par Example

        @par Example

        @code

        @code

        url u;

        url u;

        u.params().assign( {{ "first", "John" }, { "last", "Doe" }} );

        u.params().assign( {{ "first", "John" }, { "last", "Doe" }} );

        @endcode

        @endcode

        @par Complexity

        @par Complexity

        Linear in `init.size()`.

        Linear in `init.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 params to assign.

        @param init The list of params to assign.

    */

    */

    void

    void

    assign(

    assign(

        std::initializer_list<

        std::initializer_list<

            param_view> init);

            param_view> init);

    /** Assign elements

    /** Assign elements

        This function replaces the entire

        This function replaces the entire

        contents of the view with the params

        contents of the view with the params

        in the range.

        in the range.

        <br>

        <br>

        All iterators are invalidated.

        All iterators are invalidated.

        @note

        @note

        The strings referenced by the inputs

        The strings referenced by the inputs

        must not come from the underlying url,

        must not come from the underlying url,

        or else the behavior is undefined.

        or else the behavior is undefined.

        @par Mandates

        @par Mandates

        @code

        @code

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

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

        @endcode

        @endcode

        @par Complexity

        @par Complexity

        Linear in the size of the range.

        Linear in the size of the range.

        @par Exception Safety

        @par Exception Safety

        Strong guarantee.

        Strong guarantee.

        Calls to allocate may throw.

        Calls to allocate may throw.

        @param first The first element to assign.

        @param first The first element to assign.

        @param last One past the last element to assign.

        @param last One past the last element to assign.

    */

    */

    template<class FwdIt>

    template<class FwdIt>

    void

    void

    assign(FwdIt first, FwdIt last);

    assign(FwdIt first, FwdIt last);

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

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

    /** Append elements

    /** Append elements

        This function appends a param to the view.

        This function appends a param to the view.

        <br>

        <br>

        The `end()` iterator is invalidated.

        The `end()` iterator is invalidated.

        @par Example

        @par Example

        @code

        @code

        url u;

        url u;

        u.params().append( { "first", "John" } );

        u.params().append( { "first", "John" } );

        @endcode

        @endcode

        @par Complexity

        @par Complexity

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

        Linear in `this->url().encoded_query().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 new element.

        @return An iterator to the new element.

        @param p The param to append.

        @param p The param to append.

    */

    */

    iterator

    iterator

    append(

    append(

        param_view const& p);

        param_view const& p);

    /** Append elements

    /** Append elements

        This function appends the params in

        This function appends the params in

        an <em>initializer-list</em> to the view.

        an <em>initializer-list</em> to the view.

        <br>

        <br>

        The `end()` iterator is invalidated.

        The `end()` iterator is invalidated.

        @par Example

        @par Example

        @code

        @code

        url u;

        url u;

        u.params().append({ { "first", "John" }, { "last", "Doe" } });

        u.params().append({ { "first", "John" }, { "last", "Doe" } });

        @endcode

        @endcode

        @par Complexity

        @par Complexity

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

        Linear in `this->url().encoded_query().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 new element.

        @return An iterator to the first new element.

        @param init The list of params to append.

        @param init The list of params to append.

    */

    */

    iterator

    iterator

    append(

    append(

        std::initializer_list<

        std::initializer_list<

            param_view> init);

            param_view> init);

    /** Append elements

    /** Append elements

        This function appends a range of params

        This function appends a range of params

        to the view.

        to the view.

        <br>

        <br>

        The `end()` iterator is invalidated.

        The `end()` iterator is invalidated.

        @note

        @note

        The strings referenced by the inputs

        The strings referenced by the inputs

        must not come from the underlying url,

        must not come from the underlying url,

        or else the behavior is undefined.

        or else the behavior is undefined.

        @par Mandates

        @par Mandates

        @code

        @code

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

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

        @endcode

        @endcode

        @par Complexity

        @par Complexity

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

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

        @par Exception Safety

        @par Exception Safety

        Strong guarantee.

        Strong guarantee.

        Calls to allocate may throw.

        Calls to allocate may throw.

        @param first The first element to append.

        @param first The first element to append.

        @param last One past the last element to append.

        @param last One past the last element to append.

        @return An iterator to the first new element.

        @return An iterator to the first new element.

    */

    */

    template<class FwdIt>

    template<class FwdIt>

    iterator

    iterator

    append(

    append(

        FwdIt first, FwdIt last);

        FwdIt first, FwdIt last);

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

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

    /** Insert elements

    /** Insert elements

        This function inserts a param

        This function inserts a param

        before the specified position.

        before the specified position.

        <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 `this->url().encoded_query().size()`.

        Linear in `this->url().encoded_query().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

        element.

        element.

        @param before An iterator before which

        @param before An iterator before which

        the param is inserted. This may

        the param is inserted. This may

        be equal to `end()`.

        be equal to `end()`.

        @param p The param to insert.

        @param p The param to insert.

    */

    */

    iterator

    iterator

    insert(

    insert(

        iterator before,

        iterator before,

        param_view const& p);

        param_view const& p);

    /** Insert elements

    /** Insert elements

        This function inserts the params in

        This function inserts the params in

        an <em>initializer-list</em> before

        an <em>initializer-list</em> before

        the specified position.

        the specified position.

        <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

        The strings referenced by the inputs

        The strings referenced by the inputs

        must not come from the underlying url,

        must not come from the underlying url,

        or else the behavior is undefined.

        or else the behavior is undefined.

        @par Complexity

        @par Complexity

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

        Linear in `this->url().encoded_query().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 element is inserted. This may

        the element is inserted. This may

        be equal to `end()`.

        be equal to `end()`.

        @param init The list of params to insert.

        @param init The list of params to insert.

    */

    */

    iterator

    iterator

    insert(

    insert(

        iterator before,

        iterator before,

        std::initializer_list<

        std::initializer_list<

            param_view> init);

            param_view> init);

    /** Insert elements

    /** Insert elements

        This function inserts a range of

        This function inserts a range of