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_ENCODED_REF_HPP

#ifndef BOOST_URL_PARAMS_ENCODED_REF_HPP

#define BOOST_URL_PARAMS_ENCODED_REF_HPP

#define BOOST_URL_PARAMS_ENCODED_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_encoded_view.hpp>

#include <boost/url/params_encoded_view.hpp>

#include <initializer_list>

#include <initializer_list>

namespace boost {

namespace boost {

namespace urls {

namespace urls {

#ifndef BOOST_URL_DOCS

#ifndef BOOST_URL_DOCS

class url_base;

class url_base;

class params_encoded_view;

class params_encoded_view;

#endif

#endif

/** Mutable encoded query parameter proxy

/** Mutable encoded query parameter proxy

    This container exposes the percent-encoded

    This container exposes the percent-encoded

    query parameters of a @ref url_base as a

    query parameters of a @ref url_base as a

    bidirectional range while allowing mutation

    bidirectional range while allowing mutation

    of the underlying URL. It references the

    of the underlying URL. It references the

    URL’s buffer directly, so the url must stay

    URL’s buffer directly, so the url must stay

    alive for the lifetime of the proxy.

    alive for the lifetime of the proxy.

    @par Example

    @par Example

    @code

    @code

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

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

    params_encoded_ref p = u.encoded_params();

    params_encoded_ref p = u.encoded_params();

    @endcode

    @endcode

    Strings produced when elements are returned

    Strings produced when elements are returned

    have type @ref param_pct_view and represent

    have type @ref param_pct_view and represent

    encoded strings. Strings passed to member

    encoded strings. Strings passed to member

    functions may contain percent escapes, and

    functions may contain percent escapes, and

    throw exceptions on invalid inputs.

    throw exceptions 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 iterators to the underlying

    invalidate some iterators to the underlying

    character buffer:

    character buffer:

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

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

    @li @ref assign, @ref clear,

    @li @ref assign, @ref clear,

        `operator=` : All params.

        `operator=` : All params.

    @li @ref erase : Erased params and all

    @li @ref erase : Erased params and all

        params after (including `end()`).

        params after (including `end()`).

    @li @ref insert : All params at or after

    @li @ref insert : All params 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

        params and all params

        params and all params

        after (including `end()`).

        after (including `end()`).

    @par Reads vs. writes

    @par Reads vs. writes

    Even though this type can be used to mutate

    Even though this type can be used to mutate

    the referenced URL, this is still a proxy

    the referenced URL, this is still a proxy

    and every observer function inherited

    and every observer function inherited

    from @ref params_encoded_base (for example

    from @ref params_encoded_base (for example

    @ref contains, @ref find, and @ref get_or)

    @ref contains, @ref find, and @ref get_or)

    behaves like the corresponding function on

    behaves like the corresponding function on

    @ref params_encoded_view: it inspects the

    @ref params_encoded_view: it inspects the

    current encoded query and does not perform

    current encoded query and does not perform

    any modifications.

    any modifications.

*/

*/

class BOOST_URL_DECL params_encoded_ref

class BOOST_URL_DECL params_encoded_ref

    : public params_encoded_base

    : public params_encoded_base

{

{

    friend class url_base;

    friend class url_base;

    url_base* u_ = nullptr;

    url_base* u_ = nullptr;

    params_encoded_ref(

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

    */

    */

    params_encoded_ref(

    params_encoded_ref(

        params_encoded_ref const& other) = default;

        params_encoded_ref const& other) = default;

    /** 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_encoded_ref&

    params_encoded_ref&

    operator=(

    operator=(

        params_encoded_ref const& other);

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

        <br>

        <br>

        All iterators are invalidated.

        All iterators are invalidated.

        @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.begin(), init.end() );

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

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

        Exceptions thrown on invalid input.

        Exceptions thrown on invalid input.

        @throw system_error

        @throw system_error

        `init` contains an invalid percent-encoding.

        `init` contains an invalid percent-encoding.

        @param init The list of params to assign.

        @param init The list of params to assign.

        @return `*this`

        @return `*this`

    */

    */

    params_encoded_ref&

    params_encoded_ref&

    operator=(std::initializer_list<

    operator=(std::initializer_list<

        param_pct_view> init);

        param_pct_view> init);

    /** Conversion

    /** Conversion

        @par Complexity

        @par Complexity

        Constant.

        Constant.

        @par Exception Safety

        @par Exception Safety

        Throws nothing.

        Throws nothing.

        @return A view of the params.

        @return A view of the params.

    */

    */

    operator

    operator

    params_encoded_view() const noexcept;

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

        url u( "?key=value" );

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

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

    /** Assign params

        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.encoded_params().assign({ { "first", "John" }, { "last", "Doe" } });

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

        Exceptions thrown on invalid input.

        Exceptions thrown on invalid input.

        @throw system_error

        @throw system_error

        `init` contains an invalid percent-encoding.

        `init` contains an invalid percent-encoding.

        @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_pct_view> init);

            param_pct_view> init);

    /** Assign params

    /** Assign params

        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_pct_view >::value == true

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

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

    /** Append params

        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.encoded_params().append( { "first", "John" } );

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

        Exceptions thrown on invalid input.

        Exceptions thrown on invalid input.

        @throw system_error

        @throw system_error

        `p` contains an invalid percent-encoding.

        `p` contains an invalid percent-encoding.

        @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_pct_view const& p);

        param_pct_view const& p);

    /** Append params

    /** Append params

        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.encoded_params().append({ {"first", "John"}, {"last", "Doe"} });

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

        Exceptions thrown on invalid input.

        Exceptions thrown on invalid input.

        @throw system_error

        @throw system_error

        `init` contains an invalid percent-encoding.

        `init` contains an invalid percent-encoding.

        @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_pct_view> init);

            param_pct_view> init);

    /** Append params

    /** Append params

        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_pct_view >::value == true

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

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

        @return An iterator to the first new element.

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

    /** Insert params

        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.

        Exceptions thrown on invalid input.

        Exceptions thrown on invalid input.

        @throw system_error

        @throw system_error

        `p` contains an invalid percent-encoding.

        `p` contains an invalid percent-encoding.

        @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_pct_view const& p);

        param_pct_view const& p);

    /** Insert params

    /** Insert params

        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.

        Exceptions thrown on invalid input.

        Exceptions thrown on invalid input.

        @throw system_error

        @throw system_error

        `init` contains an invalid percent-encoding.

        `init` 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 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_pct_view> init);

            param_pct_view> init);

    /** Insert params

    /** Insert params

        This function inserts a range of

        This function inserts a range of

        params before the specified position.

        params before the specified position.