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_PARAM_HPP

#ifndef BOOST_URL_PARAM_HPP

#define BOOST_URL_PARAM_HPP

#define BOOST_URL_PARAM_HPP

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

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

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

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

#include <boost/url/pct_string_view.hpp>

#include <boost/url/pct_string_view.hpp>

#include <cstddef>

#include <cstddef>

#include <string>

#include <string>

namespace boost {

namespace boost {

namespace urls {

namespace urls {

#ifndef BOOST_URL_DOCS

#ifndef BOOST_URL_DOCS

struct param_pct_view;

struct param_pct_view;

struct param_view;

struct param_view;

#endif

#endif

/** The type of @ref no_value

/** The type of @ref no_value

*/

*/

struct no_value_t

struct no_value_t

{

{

};

};

/** Constant indicating no value in a param

/** Constant indicating no value in a param

*/

*/

constexpr no_value_t no_value{};

constexpr no_value_t no_value{};

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

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

/** A query parameter

/** A query parameter

    Objects of this type represent a single key

    Objects of this type represent a single key

    and value pair in a query string where a key

    and value pair in a query string where a key

    is always present and may be empty, while the

    is always present and may be empty, while the

    presence of a value is indicated by

    presence of a value is indicated by

    @ref has_value equal to true.

    @ref has_value equal to true.

    An empty value is distinct from no value.

    An empty value is distinct from no value.

    Depending on where the object was obtained,

    Depending on where the object was obtained,

    the strings may or may not contain percent

    the strings may or may not contain percent

    escapes.

    escapes.

    For most usages, key comparisons are

    For most usages, key comparisons are

    case-sensitive and duplicate keys in

    case-sensitive and duplicate keys in

    a query are possible. However, it is

    a query are possible. However, it is

    the authority that has final control

    the authority that has final control

    over how the query is interpreted.

    over how the query is interpreted.

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

    key             = *qpchar

    key             = *qpchar

    value           = *( qpchar / "=" )

    value           = *( qpchar / "=" )

    @endcode

    @endcode

    @par Specification

    @par Specification

    @li <a href="https://en.wikipedia.org/wiki/Query_string"

    @li <a href="https://en.wikipedia.org/wiki/Query_string"

        >Query string (Wikipedia)</a>

        >Query string (Wikipedia)</a>

    @see

    @see

        @ref param_view,

        @ref param_view,

        @ref param_pct_view.

        @ref param_pct_view.

*/

*/

struct param

struct param

{

{

    /** The key

    /** The key

        For most usages, key comparisons are

        For most usages, key comparisons are

        case-sensitive and duplicate keys in

        case-sensitive and duplicate keys in

        a query are possible. However, it is

        a query are possible. However, it is

        the authority that has final control

        the authority that has final control

        over how the query is interpreted.

        over how the query is interpreted.

    */

    */

    std::string key;

    std::string key;

    /** The value

    /** The value

        The presence of a value is indicated by

        The presence of a value is indicated by

        @ref has_value equal to true.

        @ref has_value equal to true.

        An empty value is distinct from no value.

        An empty value is distinct from no value.

    */

    */

    std::string value;

    std::string value;

    /** True if a value is present

    /** True if a value is present

        The presence of a value is indicated by

        The presence of a value is indicated by

        `has_value == true`.

        `has_value == true`.

        An empty value is distinct from no value.

        An empty value is distinct from no value.

    */

    */

    bool has_value = false;

    bool has_value = false;

    /** Constructor

    /** Constructor

        Default constructed query parameters

        Default constructed query parameters

        have an empty key and no value.

        have an empty key and no value.

        @par Example

        @par Example

        @code

        @code

        param qp;

        param qp;

        @endcode

        @endcode

        @par Postconditions

        @par Postconditions

        @code

        @code

        this->key == "" && this->value == "" && this->has_value == false

        this->key == "" && this->value == "" && this->has_value == false

        @endcode

        @endcode

        @par Complexity

        @par Complexity

        Constant.

        Constant.

        @par Exception Safety

        @par Exception Safety

        Throws nothing.

        Throws nothing.

    */

    */

    /** Constructor

    /** Constructor

        Upon construction, this acquires

        Upon construction, this acquires

        ownership of the members of other

        ownership of the members of other

        via move construction. The moved

        via move construction. The moved

        from object is as if default

        from object is as if default

        constructed.

        constructed.

        @par Complexity

        @par Complexity

        Constant.

        Constant.

        @par Exception Safety

        @par Exception Safety

        Throws nothing.

        Throws nothing.

        @param other The object to construct from.

        @param other The object to construct from.

    */

    */

    {

    {

    #ifdef BOOST_URL_COW_STRINGS

    #ifdef BOOST_URL_COW_STRINGS

        // for copy-on-write std::string

        // for copy-on-write std::string

        other.key.clear();

        other.key.clear();

        other.value.clear();

        other.value.clear();

    #endif

    #endif

    /** Constructor

    /** Constructor

        Upon construction, this becomes a copy

        Upon construction, this becomes a copy

        of `other`.

        of `other`.

        @par Postconditions

        @par Postconditions

        @code

        @code

        this->key == other.key && this->value == other.value && this->has_value == other.has_value

        this->key == other.key && this->value == other.value && this->has_value == other.has_value

        @endcode

        @endcode

        @par Complexity

        @par Complexity

        Linear in `other.key.size() + other.value.size()`.

        Linear in `other.key.size() + other.value.size()`.

        @par Exception Safety

        @par Exception Safety

        Calls to allocate may throw.

        Calls to allocate may throw.

        @param other The object to construct from.

        @param other The object to construct from.

        @return A reference to this object.

        @return A reference to this object.

    */

    */

    /** Assignment

    /** Assignment

        Upon assignment, this acquires

        Upon assignment, this acquires

        ownership of the members of other

        ownership of the members of other

        via move assignment. The moved

        via move assignment. The moved

        from object is as if default

        from object is as if default

        constructed.

        constructed.

        @par Complexity

        @par Complexity

        Constant.

        Constant.

        @par Exception Safety

        @par Exception Safety

        Throws nothing.

        Throws nothing.

        @param other The object to assign from.

        @param other The object to assign from.

        @return A reference to this object.

        @return A reference to this object.

    */

    */

    param&

    param&

    {

    {

    #ifdef BOOST_URL_COW_STRINGS

    #ifdef BOOST_URL_COW_STRINGS

        // for copy-on-write std::string

        // for copy-on-write std::string

        other.key.clear();

        other.key.clear();

        other.value.clear();

        other.value.clear();

    #endif

    #endif

    }

    }

    /** Assignment

    /** Assignment

        Upon assignment, this becomes a copy

        Upon assignment, this becomes a copy

        of `other`.

        of `other`.

        @par Postconditions

        @par Postconditions

        @code

        @code

        this->key == other.key && this->value == other.value && this->has_value == other.has_value

        this->key == other.key && this->value == other.value && this->has_value == other.has_value

        @endcode

        @endcode

        @par Complexity

        @par Complexity

        Linear in `other.key.size() + other.value.size()`.

        Linear in `other.key.size() + other.value.size()`.

        @par Exception Safety

        @par Exception Safety

        Calls to allocate may throw.

        Calls to allocate may throw.

        @param other The object to assign from.

        @param other The object to assign from.

        @return A reference to this object.

        @return A reference to this object.

    */

    */

        param const& other) = default;

        param const& other) = default;

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

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

    /** Constructor

    /** Constructor

        This constructs a parameter with a key

        This constructs a parameter with a key

        and value.

        and value.

        No validation is performed on the strings.

        No validation is performed on the strings.

        Ownership of the key and value is acquired

        Ownership of the key and value is acquired

        by making copies.

        by making copies.

        @par Example

        @par Example

        @code

        @code

        param qp( "key", "value" );

        param qp( "key", "value" );

        @endcode

        @endcode

        @code

        @code

        param qp( "key", optional<core::string_view>("value") );

        param qp( "key", optional<core::string_view>("value") );

        @endcode

        @endcode

        @code

        @code

        param qp( "key", boost::none );

        param qp( "key", boost::none );

        @endcode

        @endcode

        @code

        @code

        param qp( "key", nullptr );

        param qp( "key", nullptr );

        @endcode

        @endcode

        @code

        @code

        param qp( "key", no_value );

        param qp( "key", no_value );

        @endcode

        @endcode

        @par Postconditions

        @par Postconditions

        @code

        @code

        this->key == key && this->value == value && this->has_value == true

        this->key == key && this->value == value && this->has_value == true

        @endcode

        @endcode

        @par Complexity

        @par Complexity

        Linear in `key.size() + value.size()`.

        Linear in `key.size() + value.size()`.

        @par Exception Safety

        @par Exception Safety

        Calls to allocate may throw.

        Calls to allocate may throw.

        @tparam OptionalString An optional string

        @tparam OptionalString An optional string

        type, such as `core::string_view`,

        type, such as `core::string_view`,

        `std::nullptr`, @ref no_value_t, or

        `std::nullptr`, @ref no_value_t, or

        `optional<core::string_view>`.

        `optional<core::string_view>`.

        @param key The key to set.

        @param key The key to set.

        @param value The value to set.

        @param value The value to set.

    */

    */

    template <class OptionalString>

    template <class OptionalString>

        core::string_view key,

        core::string_view key,

        OptionalString const& value)

        OptionalString const& value)

    {

    {

    /** Assignment

    /** Assignment

        The members of `other` are copied,

        The members of `other` are copied,

        re-using already existing string capacity.

        re-using already existing string capacity.

        @par Postconditions

        @par Postconditions

        @code

        @code

        this->key == other.key && this->value == other.value && this->has_value == other.has_value

        this->key == other.key && this->value == other.value && this->has_value == other.has_value

        @endcode

        @endcode

        @par Complexity

        @par Complexity

        Linear in `other.key.size() + other.value.size()`.

        Linear in `other.key.size() + other.value.size()`.

        @par Exception Safety

        @par Exception Safety

        Calls to allocate may throw.

        Calls to allocate may throw.

        @param other The parameter to copy.

        @param other The parameter to copy.

        @return A reference to this object.

        @return A reference to this object.

    */

    */

    param&

    param&

    operator=(param_view const& other);

    operator=(param_view const& other);

    /** Assignment

    /** Assignment

        The members of `other` are copied,

        The members of `other` are copied,

        re-using already existing string capacity.

        re-using already existing string capacity.

        @par Postconditions

        @par Postconditions

        @code

        @code

        this->key == other.key && this->value == other.value && this->has_value == other.has_value

        this->key == other.key && this->value == other.value && this->has_value == other.has_value

        @endcode

        @endcode

        @par Complexity

        @par Complexity

        Linear in `other.key.size() + other.value.size()`.

        Linear in `other.key.size() + other.value.size()`.

        @par Exception Safety

        @par Exception Safety

        Calls to allocate may throw.

        Calls to allocate may throw.

        @param other The parameter to copy.

        @param other The parameter to copy.

        @return A reference to this object.

        @return A reference to this object.

    */

    */

    param&

    param&

    operator=(param_pct_view const& other);

    operator=(param_pct_view const& other);

    /** Arrow support

    /** Arrow support

        This operator returns the address of the

        This operator returns the address of the

        object so that it can be used in pointer

        object so that it can be used in pointer

        contexts.

        contexts.

        @return A pointer to the object.

        @return A pointer to the object.

     */

     */

    param const*

    param const*

    {

    {

    }

    }

    /** Aggregate construction

    /** Aggregate construction

        @param key The key to set.

        @param key The key to set.

        @param value The value to set.

        @param value The value to set.

        @param has_value True if a value is present.

        @param has_value True if a value is present.

     */

     */

        core::string_view key,

        core::string_view key,

        core::string_view value,

        core::string_view value,

        bool has_value) noexcept

        bool has_value) noexcept

            : core::string_view())

            : core::string_view())

    {

    {

private:

private:

        core::string_view key,

        core::string_view key,

        detail::optional_string const& value)

        detail::optional_string const& value)

    {

    {

};

};

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

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

/** A view of a query parameter

/** A view of a query parameter

    Objects of this type represent a single key

    Objects of this type represent a single key

    and value pair in a query string where a key

    and value pair in a query string where a key

    is always present and may be empty, while the

    is always present and may be empty, while the

    presence of a value is indicated by

    presence of a value is indicated by

    @ref has_value equal to true.

    @ref has_value equal to true.

    An empty value is distinct from no value.

    An empty value is distinct from no value.

    Depending on where the object was obtained,

    Depending on where the object was obtained,

    the strings may or may not contain percent

    the strings may or may not contain percent

    escapes. Some functions and objects might

    escapes. Some functions and objects might

    expect encoded strings in this view, while

    expect encoded strings in this view, while

    others expect decoded strings. The caller

    others expect decoded strings. The caller

    should be aware of the context in which

    should be aware of the context in which

    the object will be used.

    the object will be used.

    For most usages, key comparisons are

    For most usages, key comparisons are

    case-sensitive and duplicate keys in

    case-sensitive and duplicate keys in

    a query are possible. However, it is

    a query are possible. However, it is

    the authority that has final control

    the authority that has final control

    over how the query is interpreted.

    over how the query is interpreted.

    <br>

    <br>

    Keys and values in this object reference

    Keys and values in this object reference

    external character buffers.

    external character buffers.

    Ownership of the buffers is not transferred;

    Ownership of the buffers is not transferred;

    the caller is responsible for ensuring that

    the caller is responsible for ensuring that

    the assigned buffers remain valid until

    the assigned buffers remain valid until

    they are no longer referenced.

    they are no longer referenced.

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

    key             = *qpchar

    key             = *qpchar

    value           = *( qpchar / "=" )

    value           = *( qpchar / "=" )

    @endcode

    @endcode

    @par Specification

    @par Specification

    @li <a href="https://en.wikipedia.org/wiki/Query_string"

    @li <a href="https://en.wikipedia.org/wiki/Query_string"

        >Query string (Wikipedia)</a>

        >Query string (Wikipedia)</a>

    @see

    @see

        @ref param,

        @ref param,

        @ref param_pct_view.

        @ref param_pct_view.

*/

*/

struct param_view

struct param_view

{

{

    /** The key

    /** The key

        For most usages, key comparisons are

        For most usages, key comparisons are

        case-sensitive and duplicate keys in

        case-sensitive and duplicate keys in

        a query are possible. However, it is

        a query are possible. However, it is

        the authority that has final control

        the authority that has final control

        over how the query is interpreted.

        over how the query is interpreted.

    */

    */

    core::string_view key;

    core::string_view key;

    /** The value

    /** The value

        The presence of a value is indicated by

        The presence of a value is indicated by

        @ref has_value equal to true.

        @ref has_value equal to true.

        An empty value is distinct from no value.

        An empty value is distinct from no value.

    */

    */

    core::string_view value;

    core::string_view value;

    /** True if a value is present

    /** True if a value is present

        The presence of a value is indicated by

        The presence of a value is indicated by

        `has_value == true`.

        `has_value == true`.

        An empty value is distinct from no value.

        An empty value is distinct from no value.

    */

    */

    bool has_value = false;

    bool has_value = false;

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

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

    /** Constructor

    /** Constructor

        Default constructed query parameters

        Default constructed query parameters

        have an empty key and no value.

        have an empty key and no value.

        @par Example

        @par Example

        @code

        @code

        param_view qp;

        param_view qp;

        @endcode

        @endcode

        @par Postconditions

        @par Postconditions

        @code

        @code

        this->key == "" && this->value == "" && this->has_value == false

        this->key == "" && this->value == "" && this->has_value == false

        @endcode

        @endcode

        @par Complexity

        @par Complexity

        Constant.

        Constant.

        @par Exception Safety

        @par Exception Safety

        Throws nothing.

        Throws nothing.

    */

    */

    param_view() = default;

    param_view() = default;

    /** Constructor

    /** Constructor

        This constructs a parameter with a key

        This constructs a parameter with a key

        and value.

        and value.

        No validation is performed on the strings.

        No validation is performed on the strings.

        The new key and value reference

        The new key and value reference

        the same corresponding underlying

        the same corresponding underlying

        character buffers.

        character buffers.

        Ownership of the buffers is not transferred;

        Ownership of the buffers is not transferred;

        the caller is responsible for ensuring that

        the caller is responsible for ensuring that

        the assigned buffers remain valid until

        the assigned buffers remain valid until

        they are no longer referenced.

        they are no longer referenced.

        @par Example

        @par Example

        @code

        @code

        param_view qp( "key", "value" );

        param_view qp( "key", "value" );

        @endcode

        @endcode

        @par Postconditions

        @par Postconditions

        @code

        @code

        this->key.data() == key.data() && this->value.data() == value.data() && this->has_value == true

        this->key.data() == key.data() && this->value.data() == value.data() && this->has_value == true

        @endcode

        @endcode

        @par Complexity

        @par Complexity

        Constant.

        Constant.

        @par Exception Safety

        @par Exception Safety

        Throws nothing.

        Throws nothing.

        @tparam OptionalString An optional string

        @tparam OptionalString An optional string

        type, such as `core::string_view`,

        type, such as `core::string_view`,

        `std::nullptr`, @ref no_value_t, or

        `std::nullptr`, @ref no_value_t, or

        `optional<core::string_view>`.

        `optional<core::string_view>`.

        @param key The key to set.

        @param key The key to set.

        @param value The value to set.

        @param value The value to set.

    */

    */

    template <class OptionalString>

    template <class OptionalString>

        core::string_view key,

        core::string_view key,

        OptionalString const& value) noexcept

        OptionalString const& value) noexcept

    {

    {

    /** Constructor

    /** Constructor

        This function constructs a param

        This function constructs a param

        which references the character buffers

        which references the character buffers

        representing the key and value in another

        representing the key and value in another

        container.

        container.

        Ownership of the buffers is not transferred;

        Ownership of the buffers is not transferred;

        the caller is responsible for ensuring that

        the caller is responsible for ensuring that

        the assigned buffers remain valid until

        the assigned buffers remain valid until