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_VIEW_HPP

#ifndef BOOST_URL_PARAMS_VIEW_HPP

#define BOOST_URL_PARAMS_VIEW_HPP

#define BOOST_URL_PARAMS_VIEW_HPP

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

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

#include <boost/url/params_base.hpp>

#include <boost/url/params_base.hpp>

namespace boost {

namespace boost {

namespace urls {

namespace urls {

/** Non-owning decoded query parameter view

/** Non-owning decoded query parameter view

    This read-only range interprets the query

    This read-only range interprets the query

    string of a URL as bidirectional key/value

    string of a URL as bidirectional key/value

    pairs with percent-decoding applied on

    pairs with percent-decoding applied on

    access. It merely references the original

    access. It merely references the original

    character buffer; callers must keep that

    character buffer; callers must keep that

    buffer alive while the view is used.

    buffer alive while the view is used.

    @par Example

    @par Example

    @code

    @code

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

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

    params_view p = u.params();

    params_view p = u.params();

    @endcode

    @endcode

    Strings retrieved from the iterators are

    Strings retrieved from the iterators are

    automatically percent-decoded.

    automatically percent-decoded.

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

*/

*/

class params_view

class params_view

    : public params_base

    : public params_base

{

{

    friend class url_view_base;

    friend class url_view_base;

    friend class params_encoded_view;

    friend class params_encoded_view;

    friend class params_ref;

    friend class params_ref;

    params_view(

    params_view(

        detail::query_ref const& ref,

        detail::query_ref const& ref,

        encoding_opts opt) noexcept;

        encoding_opts opt) noexcept;

public:

public:

    /** Constructor

    /** Constructor

        Default-constructed params have

        Default-constructed params have

        zero elements.

        zero elements.

        @par Example

        @par Example

        @code

        @code

        params_view qp;

        params_view qp;

        @endcode

        @endcode

        @par Effects

        @par Effects

        @code

        @code

        return params_view( "" );

        return params_view( "" );

        @endcode

        @endcode

        @par Complexity

        @par Complexity

        Constant.

        Constant.

        @par Exception Safety

        @par Exception Safety

        Throws nothing.

        Throws nothing.

    */

    */

    /** Constructor

    /** Constructor

        After construction both views reference

        After construction both views reference

        the same character buffer.

        the same character buffer.

        Ownership is not transferred; the caller

        Ownership is not transferred; the caller

        is responsible for ensuring the lifetime

        is responsible for ensuring the lifetime

        of the buffer extends until it is no

        of the buffer extends until it is no

        longer referenced.

        longer referenced.

        @par Postconditions

        @par Postconditions

        @code

        @code

        this->buffer().data() == other.buffer().data()

        this->buffer().data() == other.buffer().data()

        @endcode

        @endcode

        @par Complexity

        @par Complexity

        Constant.

        Constant.

        @par Exception Safety

        @par Exception Safety

        Throws nothing

        Throws nothing

        @param other The object to copy

        @param other The object to copy

    */

    */

    params_view(

    params_view(

        params_view const& other) = default;

        params_view const& other) = default;

    /** Constructor

    /** Constructor

        After construction both views will

        After construction both views will

        reference the same character buffer

        reference the same character buffer

        but this instance will use the specified

        but this 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 caller

        Ownership is not transferred; the caller

        is responsible for ensuring the lifetime

        is responsible for ensuring the lifetime

        of the buffer extends until it is no

        of the buffer extends until it is no

        longer referenced.

        longer referenced.

        @par Postconditions

        @par Postconditions

        @code

        @code

        this->buffer().data() == other.buffer().data()

        this->buffer().data() == other.buffer().data()

        @endcode

        @endcode

        @par Complexity

        @par Complexity

        Constant.

        Constant.

        @par Exception Safety

        @par Exception Safety

        Throws nothing

        Throws nothing

        @param other The object to copy

        @param other The object to copy

        @param opt The options for decoding

        @param opt The options for decoding

    */

    */

    params_view(

    params_view(

        params_view const& other,

        params_view const& other,

        encoding_opts opt) noexcept;

        encoding_opts opt) noexcept;

    /** Constructor

    /** Constructor

        This function constructs params from

        This function constructs params from

        a valid query parameter string, which

        a valid query parameter string, which

        can contain percent escapes. Unlike

        can contain percent escapes. Unlike

        the parameters in URLs, the string

        the parameters in URLs, the string

        passed here should not start with "?".

        passed here should not start with "?".

        Upon construction, the view references

        Upon construction, the view references

        the character buffer pointed to by `s`.

        the character buffer pointed to by `s`.

        The caller is responsible for ensuring

        The caller is responsible for ensuring

        that the lifetime of the buffer extends

        that the lifetime of the buffer extends

        until it is no longer referenced.

        until it is no longer referenced.

        @par Example

        @par Example

        @code

        @code

        params_view qp( "first=John&last=Doe" );

        params_view qp( "first=John&last=Doe" );

        @endcode

        @endcode

        @par Effects

        @par Effects

        @code

        @code

        return parse_query( s ).value();

        return parse_query( s ).value();

        @endcode

        @endcode

        @par Postconditions

        @par Postconditions

        @code

        @code

        this->buffer().data() == s.data()

        this->buffer().data() == s.data()

        @endcode

        @endcode

        @par Complexity

        @par Complexity

        Linear in `s`.

        Linear in `s`.

        @par Exception Safety

        @par Exception Safety

        Exceptions thrown on invalid input.

        Exceptions thrown on invalid input.

        @throw system_error

        @throw system_error

        `s` contains an invalid query parameter

        `s` contains an invalid query parameter

        string.

        string.

        @param s The string to parse.

        @param s The string to parse.

        @par BNF

        @par BNF

        @code

        @code

        query-params    = [ query-param ] *( "&" query-param )

        query-params    = [ query-param ] *( "&" query-param )

        query-param     = key [ "=" value ]

        query-param     = key [ "=" value ]

        @endcode

        @endcode

        @par Specification

        @par Specification

        @li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.4"

        @li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.4"

            >3.4.  Query</a>

            >3.4.  Query</a>

    */

    */

    BOOST_URL_DECL

    BOOST_URL_DECL

    params_view(

    params_view(

        core::string_view s);

        core::string_view s);

    /** Constructor

    /** Constructor

        This function constructs params from

        This function constructs params from

        a valid query parameter string, which

        a valid query parameter string, which

        can contain percent escapes.

        can contain percent escapes.

        This instance will use the specified

        This instance will use the specified

        @ref encoding_opts when the values

        @ref encoding_opts when the values

        are decoded.

        are decoded.

        Unlike the parameters in URLs, the string

        Unlike the parameters in URLs, the string

        passed here should not start with "?".

        passed here should not start with "?".

        Upon construction, the view will

        Upon construction, the view will

        reference the character buffer pointed

        reference the character buffer pointed

        to by `s`. The caller is responsible

        to by `s`. The caller is responsible

        for ensuring that the lifetime of the

        for ensuring that the lifetime of the

        buffer extends until it is no longer

        buffer extends until it is no longer

        referenced.

        referenced.

        @par Example

        @par Example

        @code

        @code

        encoding_opts opt;

        encoding_opts opt;

        opt.space_as_plus = true;

        opt.space_as_plus = true;

        params_view qp( "name=John+Doe", opt );

        params_view qp( "name=John+Doe", opt );

        @endcode

        @endcode

        @par Effects

        @par Effects

        @code

        @code

        return params_view(parse_query( s ).value(), opt);

        return params_view(parse_query( s ).value(), opt);

        @endcode

        @endcode

        @par Postconditions

        @par Postconditions

        @code

        @code

        this->buffer().data() == s.data()

        this->buffer().data() == s.data()

        @endcode

        @endcode

        @par Complexity

        @par Complexity

        Linear in `s`.

        Linear in `s`.

        @par Exception Safety

        @par Exception Safety

        Exceptions thrown on invalid input.

        Exceptions thrown on invalid input.

        @throw system_error

        @throw system_error

        `s` contains an invalid query parameter

        `s` contains an invalid query parameter

        string.

        string.

        @param s The string to parse.

        @param s The string to parse.

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

        @par BNF

        @par BNF

        @code

        @code

        query-params    = [ query-param ] *( "&" query-param )

        query-params    = [ query-param ] *( "&" query-param )

        query-param     = key [ "=" value ]

        query-param     = key [ "=" value ]

        @endcode

        @endcode

        @par Specification

        @par Specification

        @li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.4"

        @li <a href="https://datatracker.ietf.org/doc/html/rfc3986#section-3.4"

            >3.4.  Query</a>

            >3.4.  Query</a>

    */

    */

    BOOST_URL_DECL

    BOOST_URL_DECL

    params_view(

    params_view(

        core::string_view s,

        core::string_view s,

        encoding_opts opt);

        encoding_opts opt);

    /** Assignment

    /** Assignment

        After assignment, both views reference

        After assignment, both views reference

        the same underlying character buffer.

        the same underlying character buffer.

        Ownership is not transferred; the caller

        Ownership is not transferred; the caller

        is responsible for ensuring the lifetime

        is responsible for ensuring the lifetime

        of the buffer extends until it is no

        of the buffer extends until it is no

        longer referenced.

        longer referenced.

        @par Postconditions

        @par Postconditions

        @code

        @code

        this->buffer().data() == other.buffer().data()

        this->buffer().data() == other.buffer().data()

        @endcode

        @endcode

        @par Complexity

        @par Complexity

        Constant

        Constant

        @par Exception Safety

        @par Exception Safety

        Throws nothing

        Throws nothing

        @param other The object to assign

        @param other The object to assign

        @return A reference to this object

        @return A reference to this object

    */

    */

    params_view&

    params_view&

    operator=(

    operator=(

        params_view const& other) = default;

        params_view const& other) = default;

};

};

} // urls

} // urls

} // boost

} // boost

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

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

//

//

// std::ranges::enable_borrowed_range

// std::ranges::enable_borrowed_range

//

//

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

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

#ifdef BOOST_URL_HAS_CONCEPTS

#ifdef BOOST_URL_HAS_CONCEPTS

#include <ranges>

#include <ranges>

namespace std::ranges {

namespace std::ranges {

    template<>

    template<>

    inline constexpr bool

    inline constexpr bool

        enable_borrowed_range<

        enable_borrowed_range<

            boost::urls::params_view> = true;

            boost::urls::params_view> = true;

} // std::ranges

} // std::ranges

#endif

#endif

#endif

#endif