Line data    Source code

       1             : //
       2             : // Copyright (c) 2021 Vinnie Falco (vinnie.falco@gmail.com)
       3             : // Copyright (c) 2024 Christian Mazakas
       4             : //
       5             : // Distributed under the Boost Software License, Version 1.0. (See accompanying
       6             : // file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
       7             : //
       8             : // Official repository: https://github.com/cppalliance/http_proto
       9             : //
      10             : 
      11             : #ifndef BOOST_HTTP_PROTO_FIELDS_HPP
      12             : #define BOOST_HTTP_PROTO_FIELDS_HPP
      13             : 
      14             : #include <boost/http_proto/detail/config.hpp>
      15             : #include <boost/http_proto/fields_base.hpp>
      16             : #include <boost/http_proto/fields_view.hpp>
      17             : #include <boost/core/detail/string_view.hpp>
      18             : #include <initializer_list>
      19             : 
      20             : namespace boost {
      21             : namespace http_proto {
      22             : 
      23             : /** A modifiable container of HTTP fields
      24             : */
      25             : class fields final
      26             :     : public fields_base
      27             : {
      28             : public:
      29             : 
      30             :     //--------------------------------------------
      31             :     //
      32             :     // Special Members
      33             :     //
      34             :     //--------------------------------------------
      35             : 
      36             :     /** Constructor
      37             : 
      38             :         Default-constructed fields have no
      39             :         name-value pairs.
      40             :     */
      41             :     BOOST_HTTP_PROTO_DECL
      42             :     fields() noexcept;
      43             : 
      44             :     /** Constructor
      45             :     */
      46             :     BOOST_HTTP_PROTO_DECL
      47             :     explicit
      48             :     fields(
      49             :         core::string_view s);
      50             : 
      51             :     /** Constructor
      52             : 
      53             :         Construct a fields container which allocates
      54             :         `storage_size` bytes for storing the header.
      55             :         Attempting to grow the container beyond
      56             :         this amount will result in an exception.
      57             :         The storage is also used internally to store
      58             :         instances of an implementation-defined type.
      59             :         The requested number of bytes will be aligned
      60             :         accordingly (currently the alignment requirement is 4).
      61             : 
      62             :         <br/>
      63             : 
      64             :         This constructor is useful when an upper-bound size
      65             :         of the fields is known ahead of time and we want
      66             :         to prevent reallocations.
      67             : 
      68             :         <br/>
      69             : 
      70             :         Passing an initial storage size of `0` does not
      71             :         throw and the maximum capacity is set to an
      72             :         implementation-defined limit observable via
      73             :         @ref max_capacity_in_bytes().
      74             : 
      75             :         @param storage_size The initial and final size of
      76             :         the storage.
      77             : 
      78             :         @code
      79             :         boost::http_proto::fields
      80             :         make_fields(std::string_view server)
      81             :         {
      82             :             std::size_t size = 4096;
      83             :             // flds.buffer() is now stable
      84             :             boost::http_proto::fields flds(size);
      85             :             BOOST_ASSERT(
      86             :                 flds.max_capacity_in_bytes(), 4096);
      87             : 
      88             :             // uses spare capacity so that reallocations
      89             :             // are avoided
      90             :             flds.append(
      91             :                 boost::http_proto::field::server, server);
      92             :             flds.append(
      93             :                 boost::http_proto::field::connection, "close");
      94             :             return flds;
      95             :         }
      96             :         @endcode
      97             :     */
      98             :     BOOST_HTTP_PROTO_DECL
      99             :     explicit
     100             :     fields(
     101             :         std::size_t storage_size);
     102             : 
     103             :     /** Constructor
     104             : 
     105             :         Construct a fields container which allocates
     106             :         `storage_size` bytes for storing the header, with an
     107             :         upper limit of `max_storage_size`. Attempting to
     108             :         grow the container beyond its maximum will result in
     109             :         an exception. The storage is also used internally to
     110             :         store instances of an implementation-defined type.
     111             :         Both values will be aligned accordingly (currently
     112             :         the alignment requirement is 4).
     113             : 
     114             :         <br/>
     115             : 
     116             :         This constructor is useful when there's a best-fit
     117             :         guess for an initial header size but we still wish
     118             :         to permit reallocating and growing the container to
     119             :         some upper limit.
     120             : 
     121             :         <br/>
     122             : 
     123             :         Passing an initial size of `0` does not throw.
     124             : 
     125             :         @param storage_size The initial size of the storage.
     126             : 
     127             :         @param max_storage_size The maximum size of the
     128             :         allocated storage. Any operation that attempts to
     129             :         grow the container beyond this value throws
     130             :         `std::length_error`.
     131             : 
     132             :         @throws std::length_error Thrown if `size > max_size`
     133             : 
     134             :         @code
     135             :         boost::http_proto::fields
     136             :         make_fields(std::string_view host)
     137             :         {
     138             :             std::size_t size = 4096;
     139             :             boost::http_proto::fields flds(size, 2 * size);
     140             :             BOOST_ASSERT(
     141             :                 flds.max_capacity_in_bytes(), 2 * 4096);
     142             : 
     143             :             // uses spare capacity so that reallocations
     144             :             // are avoided
     145             :             flds.append(
     146             :                 boost::http_proto::field::host, host);
     147             :             flds.append(
     148             :                 boost::http_proto::field::connection, "close");
     149             :             return flds;
     150             :         }
     151             :         @endcode
     152             :     */
     153             :     BOOST_HTTP_PROTO_DECL
     154             :     explicit
     155             :     fields(
     156             :         std::size_t storage_size,
     157             :         std::size_t max_storage_size);
     158             : 
     159             :     /** Constructor
     160             :     */
     161             :     BOOST_HTTP_PROTO_DECL
     162             :     fields(fields&& other) noexcept;
     163             : 
     164             :     /** Constructor
     165             :     */
     166             :     BOOST_HTTP_PROTO_DECL
     167             :     fields(fields const& other);
     168             : 
     169             :     /** Constructor
     170             :     */
     171             :     BOOST_HTTP_PROTO_DECL
     172             :     fields(fields_view const& other);
     173             : 
     174             :     /** Assignment
     175             :     */
     176             :     BOOST_HTTP_PROTO_DECL
     177             :     fields&
     178             :     operator=(fields&& f) noexcept;
     179             : 
     180             :     /** Assignment
     181             :     */
     182             :     fields&
     183           5 :     operator=(fields const& f) noexcept
     184             :     {
     185           5 :         copy_impl(*f.ph_);
     186           5 :         return *this;
     187             :     }
     188             : 
     189             :     /** Assignment
     190             :     */
     191             :     fields&
     192           4 :     operator=(fields_view const& f)
     193             :     {
     194           4 :         copy_impl(*f.ph_);
     195           4 :         return *this;
     196             :     }
     197             : 
     198             :     /** Conversion
     199             :     */
     200           4 :     operator fields_view() const noexcept
     201             :     {
     202           4 :         return fields_view(ph_);
     203             :     }
     204             : 
     205             :     //--------------------------------------------
     206             :     //
     207             :     // Modifiers
     208             :     //
     209             :     //--------------------------------------------
     210             : 
     211             :     /** Swap this with another instance
     212             :     */
     213             :     void
     214          10 :     swap(fields& other) noexcept
     215             :     {
     216          10 :         h_.swap(other.h_);
     217          10 :     }
     218             : 
     219             :     /** Swap two instances
     220             :     */
     221             :     // hidden friend
     222             :     friend
     223             :     void
     224             :     swap(
     225             :         fields& t0,
     226             :         fields& t1) noexcept
     227             :     {
     228             :         t0.swap(t1);
     229             :     }
     230             : };
     231             : 
     232             : } // http_proto
     233             : } // boost
     234             : 
     235             : #endif