Diff coverage report for

//

//

// Copyright (c) 2021 Vinnie Falco (vinnie.falco@gmail.com)

// Copyright (c) 2021 Vinnie Falco (vinnie.falco@gmail.com)

// Copyright (c) 2024 Christian Mazakas

// Copyright (c) 2024 Christian Mazakas

// Copyright (c) 2025 Mohammad Nejati

// Copyright (c) 2025 Mohammad Nejati

//

//

// 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/cppalliance/http

// Official repository: https://github.com/cppalliance/http

//

//

#ifndef BOOST_HTTP_FIELDS_BASE_HPP

#ifndef BOOST_HTTP_FIELDS_BASE_HPP

#define BOOST_HTTP_FIELDS_BASE_HPP

#define BOOST_HTTP_FIELDS_BASE_HPP

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

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

#include <boost/http/detail/except.hpp>

#include <boost/http/detail/except.hpp>

#include <boost/http/detail/header.hpp>

#include <boost/http/detail/header.hpp>

#include <boost/core/detail/string_view.hpp>

#include <boost/core/detail/string_view.hpp>

#include <iosfwd>

#include <iosfwd>

namespace boost {

namespace boost {

namespace http {

namespace http {

/** Mixin for modifiable HTTP fields.

/** Mixin for modifiable HTTP fields.

    @par Iterators

    @par Iterators

    Iterators obtained from @ref fields

    Iterators obtained from @ref fields

    containers are not invalidated when

    containers are not invalidated when

    the underlying container is modified.

    the underlying container is modified.

    @note HTTP field names are case-insensitive.

    @note HTTP field names are case-insensitive.

*/

*/

class fields_base

class fields_base

{

{

    detail::header h_;

    detail::header h_;

    std::size_t max_cap_ =

    std::size_t max_cap_ =

        std::numeric_limits<std::size_t>::max();

        std::numeric_limits<std::size_t>::max();

    bool external_storage_ = false;

    bool external_storage_ = false;

    using entry =

    using entry =

        detail::header::entry;

        detail::header::entry;

    using offset_type =

    using offset_type =

        detail::header::offset_type;

        detail::header::offset_type;

    using table =

    using table =

        detail::header::table;

        detail::header::table;

    class op_t;

    class op_t;

    class prefix_op_t

    class prefix_op_t

    {

    {

        fields_base& self_;

        fields_base& self_;

        offset_type new_prefix_;

        offset_type new_prefix_;

        char* buf_ = nullptr;

        char* buf_ = nullptr;

    public:

    public:

        prefix_op_t(

        prefix_op_t(

            fields_base& self,

            fields_base& self,

            std::size_t new_prefix,

            std::size_t new_prefix,

            core::string_view* s0 = nullptr,

            core::string_view* s0 = nullptr,

            core::string_view* s1 = nullptr);

            core::string_view* s1 = nullptr);

        ~prefix_op_t();

        ~prefix_op_t();

    };

    };

    friend class fields;

    friend class fields;

    friend class message_base;

    friend class message_base;

    friend class request_base;

    friend class request_base;

    friend class request;

    friend class request;

    friend class static_request;

    friend class static_request;

    friend class response_base;

    friend class response_base;

    friend class response;

    friend class response;

    friend class static_response;

    friend class static_response;

    friend class parser;

    friend class parser;

    friend class serializer;

    friend class serializer;

    BOOST_HTTP_DECL

    BOOST_HTTP_DECL

    explicit

    explicit

    fields_base(

    fields_base(

        detail::kind k) noexcept;

        detail::kind k) noexcept;

    BOOST_HTTP_DECL

    BOOST_HTTP_DECL

    fields_base(

    fields_base(

        detail::kind k,

        detail::kind k,

        void* storage,

        void* storage,

        std::size_t cap) noexcept;

        std::size_t cap) noexcept;

    BOOST_HTTP_DECL

    BOOST_HTTP_DECL

    fields_base(

    fields_base(

        detail::kind k,

        detail::kind k,

        core::string_view s);

        core::string_view s);

    BOOST_HTTP_DECL

    BOOST_HTTP_DECL

    explicit

    explicit

    fields_base(

    fields_base(

        detail::header const& h);

        detail::header const& h);

    BOOST_HTTP_DECL

    BOOST_HTTP_DECL

    fields_base(

    fields_base(

        fields_base const&);

        fields_base const&);

    BOOST_HTTP_DECL

    BOOST_HTTP_DECL

    fields_base(

    fields_base(

        detail::header const& h,

        detail::header const& h,

        void* storage,

        void* storage,

        std::size_t cap);

        std::size_t cap);

public:

public:

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

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

    //

    //

    // Types

    // Types

    //

    //

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

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

    /** A view to an HTTP field.

    /** A view to an HTTP field.

        The view will be invalidated when the

        The view will be invalidated when the

        underlying container is modified.

        underlying container is modified.

        The caller is responsible for ensuring

        The caller is responsible for ensuring

        that the lifetime of the container extends

        that the lifetime of the container extends

        until it is no longer referenced.

        until it is no longer referenced.

    */

    */

    struct reference

    struct reference

    {

    {

        /** Field name constant.

        /** Field name constant.

            Set to `boost::none` if the constant

            Set to `boost::none` if the constant

            does not exist in @ref field.

            does not exist in @ref field.

        */

        */

        boost::optional<field> const id;

        boost::optional<field> const id;

        /// A view to the field name.

        /// A view to the field name.

        core::string_view const name;

        core::string_view const name;

        /// A view to the field value.

        /// A view to the field value.

        core::string_view const value;

        core::string_view const value;

        reference const*

        reference const*

        {

        {

        }

        }

    };

    };

    /// @copydoc reference

    /// @copydoc reference

    typedef reference const_reference;

    typedef reference const_reference;

    /** A value type which represent an HTTP field.

    /** A value type which represent an HTTP field.

        This type allows for making a copy of

        This type allows for making a copy of

        a field where ownership is retained

        a field where ownership is retained

        in the copy.

        in the copy.

    */

    */

    struct value_type

    struct value_type

    {

    {

        /** Field name constant.

        /** Field name constant.

            Set to `boost::none` if the

            Set to `boost::none` if the

            constant does not exist in @ref field.

            constant does not exist in @ref field.

        */

        */

        boost::optional<field> id;

        boost::optional<field> id;

        /// Field name.

        /// Field name.

        std::string name;

        std::string name;

        /// Field value.

        /// Field value.

        std::string value;

        std::string value;

        /// Constructor.

        /// Constructor.

        BOOST_HTTP_DECL

        BOOST_HTTP_DECL

        value_type(

        value_type(

            reference const& other);

            reference const& other);

        /** Conversion.

        /** Conversion.

            @see

            @see

                @ref reference.

                @ref reference.

            @return A view to the fields.

            @return A view to the fields.

        */

        */

        operator reference() const noexcept;

        operator reference() const noexcept;

    };

    };

    /** A bidirectional iterator to HTTP fields.

    /** A bidirectional iterator to HTTP fields.

    */

    */

    class iterator;

    class iterator;

    /// @copydoc iterator

    /// @copydoc iterator

    using const_iterator = iterator;

    using const_iterator = iterator;

    /** A bidirectional reverse iterator to HTTP fields.

    /** A bidirectional reverse iterator to HTTP fields.

    */

    */

    class reverse_iterator;

    class reverse_iterator;

    /// @copydoc iterator

    /// @copydoc iterator

    using const_reverse_iterator = reverse_iterator;

    using const_reverse_iterator = reverse_iterator;

    /** A forward range of matching fields.

    /** A forward range of matching fields.

        Objects of this type are returned by

        Objects of this type are returned by

        the function @ref find_all.

        the function @ref find_all.

    */

    */

    class subrange;

    class subrange;

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

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

    //

    //

    // Special Members

    // Special Members

    //

    //

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

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

    /** Destructor.

    /** Destructor.

    */

    */

    BOOST_HTTP_DECL

    BOOST_HTTP_DECL

    ~fields_base();

    ~fields_base();

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

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

    //

    //

    // Observers

    // Observers

    //

    //

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

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

    /** Return the largest possible serialized message.

    /** Return the largest possible serialized message.

    */

    */

    static

    static

    constexpr

    constexpr

    std::size_t

    std::size_t

    max_size() noexcept

    max_size() noexcept

    {

    {

        // TODO: this doesn't take into account

        // TODO: this doesn't take into account

        // the start-line

        // the start-line

        return detail::header::max_offset;

        return detail::header::max_offset;

    }

    }

    /** Return an iterator to the beginning.

    /** Return an iterator to the beginning.

    */

    */

    iterator

    iterator

    begin() const noexcept;

    begin() const noexcept;

    /** Return an iterator to the end.

    /** Return an iterator to the end.

    */

    */

    iterator

    iterator

    end() const noexcept;

    end() const noexcept;

    /** Return a reverse iterator to the beginning.

    /** Return a reverse iterator to the beginning.

    */

    */

    reverse_iterator

    reverse_iterator

    rbegin() const noexcept;

    rbegin() const noexcept;

    /** Return a reverse iterator to the end.

    /** Return a reverse iterator to the end.

    */

    */

    reverse_iterator

    reverse_iterator

    rend() const noexcept;

    rend() const noexcept;

    /** Return a string view representing the serialized data.

    /** Return a string view representing the serialized data.

    */

    */

    core::string_view

    core::string_view

    {

    {

    }

    }

    /** Return the number of fields in the container.

    /** Return the number of fields in the container.

    */

    */

    std::size_t

    std::size_t

    {

    {

    }

    }

    /** Return the value of a field, or throws an exception.

    /** Return the value of a field, or throws an exception.

        If more than one field with the specified

        If more than one field with the specified

        name exists, the first field defined by

        name exists, the first field defined by

        insertion order is returned.

        insertion order is returned.

        @par Exception Safety

        @par Exception Safety

        Strong guarantee.

        Strong guarantee.

        @throw std::out_of_range

        @throw std::out_of_range

        Field is not found.

        Field is not found.

        @param id The field name constant.

        @param id The field name constant.

    */

    */

    BOOST_HTTP_DECL

    BOOST_HTTP_DECL

    core::string_view

    core::string_view

    at(field id) const;

    at(field id) const;

    /** Return the value of a field, or throws an exception.

    /** Return the value of a field, or throws an exception.

        If more than one field with the specified

        If more than one field with the specified

        name exists, the first field defined by

        name exists, the first field defined by

        insertion order is returned.

        insertion order is returned.

        If `name` refers to a known field, it is

        If `name` refers to a known field, it is

        faster to call @ref at with a field id

        faster to call @ref at with a field id

        instead of a string.

        instead of a string.

        @par Exception Safety

        @par Exception Safety

        Strong guarantee.

        Strong guarantee.

        @throw std::out_of_range

        @throw std::out_of_range

        Field is not found.

        Field is not found.

        @param name The field name.

        @param name The field name.

    */

    */

    BOOST_HTTP_DECL

    BOOST_HTTP_DECL

    core::string_view

    core::string_view

    at(core::string_view name) const;

    at(core::string_view name) const;

    /** Return true if a field exists.

    /** Return true if a field exists.

    */

    */

    BOOST_HTTP_DECL

    BOOST_HTTP_DECL

    bool

    bool

    exists(field id) const noexcept;

    exists(field id) const noexcept;

    /** Return true if a field exists.

    /** Return true if a field exists.

        If `name` refers to a known field,

        If `name` refers to a known field,

        it is faster to call @ref exists

        it is faster to call @ref exists

        with a field id instead of a string.

        with a field id instead of a string.

        @param name The field name.

        @param name The field name.

    */

    */

    BOOST_HTTP_DECL

    BOOST_HTTP_DECL

    bool

    bool

    exists(

    exists(

        core::string_view name) const noexcept;

        core::string_view name) const noexcept;

    /** Return the number of matching fields.

    /** Return the number of matching fields.

        @param id The field name constant.

        @param id The field name constant.

    */

    */

    BOOST_HTTP_DECL

    BOOST_HTTP_DECL

    std::size_t

    std::size_t

    count(field id) const noexcept;

    count(field id) const noexcept;

    /** Return the number of matching fields.

    /** Return the number of matching fields.

        If `name` refers to a known field,

        If `name` refers to a known field,

        it is faster to call @ref count

        it is faster to call @ref count

        with a field id instead of a string.

        with a field id instead of a string.

        @param name The field name.

        @param name The field name.

    */

    */

    BOOST_HTTP_DECL

    BOOST_HTTP_DECL

    std::size_t

    std::size_t

    count(

    count(

        core::string_view name) const noexcept;

        core::string_view name) const noexcept;

    /** Return an iterator to the matching element if it exists.

    /** Return an iterator to the matching element if it exists.

        @param id The field name constant.

        @param id The field name constant.

    */

    */

    BOOST_HTTP_DECL

    BOOST_HTTP_DECL

    iterator

    iterator

    find(field id) const noexcept;

    find(field id) const noexcept;

    /** Return an iterator to the matching element if it exists.

    /** Return an iterator to the matching element if it exists.

        If `name` refers to a known field,

        If `name` refers to a known field,

        it is faster to call @ref find

        it is faster to call @ref find

        with a field id instead of a string.

        with a field id instead of a string.

        @param name The field name.

        @param name The field name.

    */

    */

    BOOST_HTTP_DECL

    BOOST_HTTP_DECL

    iterator

    iterator

    find(

    find(

        core::string_view name) const noexcept;

        core::string_view name) const noexcept;

    /** Return an iterator to the matching element if it exists.

    /** Return an iterator to the matching element if it exists.

        @param from The position to begin the

        @param from The position to begin the

        search from. This can be `end()`.

        search from. This can be `end()`.

        @param id The field name constant.

        @param id The field name constant.

    */

    */

    BOOST_HTTP_DECL

    BOOST_HTTP_DECL

    iterator

    iterator

    find(

    find(

        iterator from,

        iterator from,

        field id) const noexcept;

        field id) const noexcept;

    /** Return an iterator to the matching element if it exists.

    /** Return an iterator to the matching element if it exists.

        If `name` refers to a known field,

        If `name` refers to a known field,

        it is faster to call @ref find

        it is faster to call @ref find

        with a field id instead of a string.

        with a field id instead of a string.

        @param from The position to begin the

        @param from The position to begin the

        search from. This can be `end()`.

        search from. This can be `end()`.

        @param name The field name.

        @param name The field name.

    */

    */

    BOOST_HTTP_DECL

    BOOST_HTTP_DECL

    iterator

    iterator

    find(

    find(

        iterator from,

        iterator from,

        core::string_view name) const noexcept;

        core::string_view name) const noexcept;

    /** Return an iterator to the matching element if it exists.

    /** Return an iterator to the matching element if it exists.

        @param before One past the position

        @param before One past the position

        to begin the search from. This can

        to begin the search from. This can

        be `end()`.

        be `end()`.

        @param id The field name constant.

        @param id The field name constant.

    */

    */

    BOOST_HTTP_DECL

    BOOST_HTTP_DECL

    iterator

    iterator

    find_last(

    find_last(

        iterator before,

        iterator before,

        field id) const noexcept;

        field id) const noexcept;

    /** Return an iterator to the matching element if it exists.

    /** Return an iterator to the matching element if it exists.

        If `name` refers to a known field,

        If `name` refers to a known field,

        it is faster to call @ref find_last

        it is faster to call @ref find_last

        with a field id instead of a string.

        with a field id instead of a string.

        @param before One past the position

        @param before One past the position

        to begin the search from. This can

        to begin the search from. This can

        be `end()`.

        be `end()`.

        @param name The field name.

        @param name The field name.

    */

    */

    BOOST_HTTP_DECL

    BOOST_HTTP_DECL

    iterator

    iterator

    find_last(

    find_last(

        iterator before,

        iterator before,

        core::string_view name) const noexcept;

        core::string_view name) const noexcept;

    /** Return the value of a field or a default if missing.

    /** Return the value of a field or a default if missing.

        @param id The field name constant.

        @param id The field name constant.

        @param s The value to be returned if

        @param s The value to be returned if

        field does not exist.

        field does not exist.

    */

    */

    BOOST_HTTP_DECL

    BOOST_HTTP_DECL

    core::string_view

    core::string_view

    value_or(

    value_or(

        field id,

        field id,

        core::string_view s) const noexcept;

        core::string_view s) const noexcept;

    /** Return the value of a field or a default if missing.

    /** Return the value of a field or a default if missing.

        If `name` refers to a known field,

        If `name` refers to a known field,

        it is faster to call @ref value_or

        it is faster to call @ref value_or

        with a field id instead of a string.

        with a field id instead of a string.

        @param name The field name.

        @param name The field name.

        @param s The value to be returned if

        @param s The value to be returned if

        field does not exist.

        field does not exist.

    */

    */

    BOOST_HTTP_DECL

    BOOST_HTTP_DECL

    core::string_view

    core::string_view

    value_or(

    value_or(

        core::string_view name,

        core::string_view name,

        core::string_view s) const noexcept;

        core::string_view s) const noexcept;

    /** Return a forward range containing values for all matching fields.

    /** Return a forward range containing values for all matching fields.

        @param id The field name constant.

        @param id The field name constant.

    */

    */

    BOOST_HTTP_DECL

    BOOST_HTTP_DECL

    subrange

    subrange

    find_all(field id) const noexcept;

    find_all(field id) const noexcept;

    /** Return a forward range containing values for all matching fields.

    /** Return a forward range containing values for all matching fields.

        If `name` refers to a known field,

        If `name` refers to a known field,

        it is faster to call @ref find_all

        it is faster to call @ref find_all

        with a field id instead of a string.

        with a field id instead of a string.

        @param name The field name.

        @param name The field name.

    */

    */

    BOOST_HTTP_DECL

    BOOST_HTTP_DECL

    subrange

    subrange

    find_all(

    find_all(

        core::string_view name) const noexcept;

        core::string_view name) const noexcept;

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

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

    //

    //

    // Capacity

    // Capacity

    //

    //

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

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

    /** Return the maximum allowed capacity in bytes.

    /** Return the maximum allowed capacity in bytes.

    */

    */

    std::size_t

    std::size_t

    {

    {

    }

    }

    /** Return the total number of bytes allocated by the container.

    /** Return the total number of bytes allocated by the container.

    */

    */

    std::size_t

    std::size_t

    {

    {

    }

    }

    /** Clear contents while preserving the capacity.

    /** Clear contents while preserving the capacity.

        In the case of response and request

        In the case of response and request

        containers the start-line also resets to

        containers the start-line also resets to

        default.

        default.

        @par Postconditions

        @par Postconditions

        @code

        @code

        this->size() == 0

        this->size() == 0

        @endcode

        @endcode

        @par Complexity

        @par Complexity

        Constant.

        Constant.

    */

    */

    BOOST_HTTP_DECL

    BOOST_HTTP_DECL

    void

    void

    clear() noexcept;

    clear() noexcept;

    /** Adjust the capacity without changing the size.

    /** Adjust the capacity without changing the size.

        This function adjusts the capacity

        This function adjusts the capacity

        of the container in bytes, without

        of the container in bytes, without

        affecting the current contents. Has

        affecting the current contents. Has

        no effect if `n <= this->capacity_in_bytes()`.

        no effect if `n <= this->capacity_in_bytes()`.

        @par Postconditions

        @par Postconditions