. /include/boost/http /fields_base.hpp
100.00% Lines (44/44) 100.00% Functions (11/11)
[ ] prev/next file n p prev/next uncovered line
TLA Baseline Branch
Line Hits Code Line Hits Code
1   // 1   //
2   // Copyright (c) 2021 Vinnie Falco (vinnie.falco@gmail.com) 2   // Copyright (c) 2021 Vinnie Falco (vinnie.falco@gmail.com)
3   // Copyright (c) 2024 Christian Mazakas 3   // Copyright (c) 2024 Christian Mazakas
4   // Copyright (c) 2025 Mohammad Nejati 4   // Copyright (c) 2025 Mohammad Nejati
5   // 5   //
6   // Distributed under the Boost Software License, Version 1.0. (See accompanying 6   // Distributed under the Boost Software License, Version 1.0. (See accompanying
7   // file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) 7   // file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
8   // 8   //
9   // Official repository: https://github.com/cppalliance/http 9   // Official repository: https://github.com/cppalliance/http
10   // 10   //
11   11  
12   #ifndef BOOST_HTTP_FIELDS_BASE_HPP 12   #ifndef BOOST_HTTP_FIELDS_BASE_HPP
13   #define BOOST_HTTP_FIELDS_BASE_HPP 13   #define BOOST_HTTP_FIELDS_BASE_HPP
14   14  
15   #include <boost/http/detail/config.hpp> 15   #include <boost/http/detail/config.hpp>
16   #include <boost/http/detail/except.hpp> 16   #include <boost/http/detail/except.hpp>
17   #include <boost/http/detail/header.hpp> 17   #include <boost/http/detail/header.hpp>
18   #include <boost/core/detail/string_view.hpp> 18   #include <boost/core/detail/string_view.hpp>
19   19  
20   #include <iosfwd> 20   #include <iosfwd>
21   21  
22   namespace boost { 22   namespace boost {
23   namespace http { 23   namespace http {
24   24  
25   /** Mixin for modifiable HTTP fields. 25   /** Mixin for modifiable HTTP fields.
26   26  
27   @par Iterators 27   @par Iterators
28   28  
29   Iterators obtained from @ref fields 29   Iterators obtained from @ref fields
30   containers are not invalidated when 30   containers are not invalidated when
31   the underlying container is modified. 31   the underlying container is modified.
32   32  
33   @note HTTP field names are case-insensitive. 33   @note HTTP field names are case-insensitive.
34   */ 34   */
35   class fields_base 35   class fields_base
36   { 36   {
37   detail::header h_; 37   detail::header h_;
38   std::size_t max_cap_ = 38   std::size_t max_cap_ =
39   std::numeric_limits<std::size_t>::max(); 39   std::numeric_limits<std::size_t>::max();
40   bool external_storage_ = false; 40   bool external_storage_ = false;
41   41  
42   using entry = 42   using entry =
43   detail::header::entry; 43   detail::header::entry;
44   using offset_type = 44   using offset_type =
45   detail::header::offset_type; 45   detail::header::offset_type;
46   using table = 46   using table =
47   detail::header::table; 47   detail::header::table;
48   48  
49   class op_t; 49   class op_t;
50   class prefix_op_t 50   class prefix_op_t
51   { 51   {
52   fields_base& self_; 52   fields_base& self_;
53   offset_type new_prefix_; 53   offset_type new_prefix_;
54   char* buf_ = nullptr; 54   char* buf_ = nullptr;
55   55  
56   public: 56   public:
57   prefix_op_t( 57   prefix_op_t(
58   fields_base& self, 58   fields_base& self,
59   std::size_t new_prefix, 59   std::size_t new_prefix,
60   core::string_view* s0 = nullptr, 60   core::string_view* s0 = nullptr,
61   core::string_view* s1 = nullptr); 61   core::string_view* s1 = nullptr);
62   62  
63   ~prefix_op_t(); 63   ~prefix_op_t();
64   }; 64   };
65   65  
66   friend class fields; 66   friend class fields;
67   friend class message_base; 67   friend class message_base;
68   friend class request_base; 68   friend class request_base;
69   friend class request; 69   friend class request;
70   friend class static_request; 70   friend class static_request;
71   friend class response_base; 71   friend class response_base;
72   friend class response; 72   friend class response;
73   friend class static_response; 73   friend class static_response;
74   friend class parser; 74   friend class parser;
75   friend class serializer; 75   friend class serializer;
76   76  
77   BOOST_HTTP_DECL 77   BOOST_HTTP_DECL
78   explicit 78   explicit
79   fields_base( 79   fields_base(
80   detail::kind k) noexcept; 80   detail::kind k) noexcept;
81   81  
82   BOOST_HTTP_DECL 82   BOOST_HTTP_DECL
83   fields_base( 83   fields_base(
84   detail::kind k, 84   detail::kind k,
85   void* storage, 85   void* storage,
86   std::size_t cap) noexcept; 86   std::size_t cap) noexcept;
87   87  
88   BOOST_HTTP_DECL 88   BOOST_HTTP_DECL
89   fields_base( 89   fields_base(
90   detail::kind k, 90   detail::kind k,
91   core::string_view s); 91   core::string_view s);
92   92  
93   BOOST_HTTP_DECL 93   BOOST_HTTP_DECL
94   explicit 94   explicit
95   fields_base( 95   fields_base(
96   detail::header const& h); 96   detail::header const& h);
97   97  
98   BOOST_HTTP_DECL 98   BOOST_HTTP_DECL
99   fields_base( 99   fields_base(
100   fields_base const&); 100   fields_base const&);
101   101  
102   BOOST_HTTP_DECL 102   BOOST_HTTP_DECL
103   fields_base( 103   fields_base(
104   detail::header const& h, 104   detail::header const& h,
105   void* storage, 105   void* storage,
106   std::size_t cap); 106   std::size_t cap);
107   107  
108   public: 108   public:
109   //-------------------------------------------- 109   //--------------------------------------------
110   // 110   //
111   // Types 111   // Types
112   // 112   //
113   //-------------------------------------------- 113   //--------------------------------------------
114   114  
115   /** A view to an HTTP field. 115   /** A view to an HTTP field.
116   116  
117   The view will be invalidated when the 117   The view will be invalidated when the
118   underlying container is modified. 118   underlying container is modified.
119   119  
120   The caller is responsible for ensuring 120   The caller is responsible for ensuring
121   that the lifetime of the container extends 121   that the lifetime of the container extends
122   until it is no longer referenced. 122   until it is no longer referenced.
123   */ 123   */
124   struct reference 124   struct reference
125   { 125   {
126   /** Field name constant. 126   /** Field name constant.
127   127  
128   Set to `boost::none` if the constant 128   Set to `boost::none` if the constant
129   does not exist in @ref field. 129   does not exist in @ref field.
130   */ 130   */
131   boost::optional<field> const id; 131   boost::optional<field> const id;
132   132  
133   /// A view to the field name. 133   /// A view to the field name.
134   core::string_view const name; 134   core::string_view const name;
135   135  
136   /// A view to the field value. 136   /// A view to the field value.
137   core::string_view const value; 137   core::string_view const value;
138   138  
139   reference const* 139   reference const*
HITCBC 140   1805 operator->() const noexcept 140   1805 operator->() const noexcept
141   { 141   {
HITCBC 142   1805 return this; 142   1805 return this;
143   } 143   }
144   }; 144   };
145   145  
146   /// @copydoc reference 146   /// @copydoc reference
147   typedef reference const_reference; 147   typedef reference const_reference;
148   148  
149   /** A value type which represent an HTTP field. 149   /** A value type which represent an HTTP field.
150   150  
151   This type allows for making a copy of 151   This type allows for making a copy of
152   a field where ownership is retained 152   a field where ownership is retained
153   in the copy. 153   in the copy.
154   */ 154   */
155   struct value_type 155   struct value_type
156   { 156   {
157   /** Field name constant. 157   /** Field name constant.
158   158  
159   Set to `boost::none` if the 159   Set to `boost::none` if the
160   constant does not exist in @ref field. 160   constant does not exist in @ref field.
161   */ 161   */
162   boost::optional<field> id; 162   boost::optional<field> id;
163   163  
164   /// Field name. 164   /// Field name.
165   std::string name; 165   std::string name;
166   166  
167   /// Field value. 167   /// Field value.
168   std::string value; 168   std::string value;
169   169  
170   /// Constructor. 170   /// Constructor.
171   BOOST_HTTP_DECL 171   BOOST_HTTP_DECL
172   value_type( 172   value_type(
173   reference const& other); 173   reference const& other);
174   174  
175   /** Conversion. 175   /** Conversion.
176   176  
177   @see 177   @see
178   @ref reference. 178   @ref reference.
179   179  
180   @return A view to the fields. 180   @return A view to the fields.
181   */ 181   */
182   operator reference() const noexcept; 182   operator reference() const noexcept;
183   }; 183   };
184   184  
185   /** A bidirectional iterator to HTTP fields. 185   /** A bidirectional iterator to HTTP fields.
186   */ 186   */
187   class iterator; 187   class iterator;
188   188  
189   /// @copydoc iterator 189   /// @copydoc iterator
190   using const_iterator = iterator; 190   using const_iterator = iterator;
191   191  
192   /** A bidirectional reverse iterator to HTTP fields. 192   /** A bidirectional reverse iterator to HTTP fields.
193   */ 193   */
194   class reverse_iterator; 194   class reverse_iterator;
195   195  
196   /// @copydoc iterator 196   /// @copydoc iterator
197   using const_reverse_iterator = reverse_iterator; 197   using const_reverse_iterator = reverse_iterator;
198   198  
199   /** A forward range of matching fields. 199   /** A forward range of matching fields.
200   200  
201   Objects of this type are returned by 201   Objects of this type are returned by
202   the function @ref find_all. 202   the function @ref find_all.
203   */ 203   */
204   class subrange; 204   class subrange;
205   205  
206   //-------------------------------------------- 206   //--------------------------------------------
207   // 207   //
208   // Special Members 208   // Special Members
209   // 209   //
210   //-------------------------------------------- 210   //--------------------------------------------
211   211  
212   /** Destructor. 212   /** Destructor.
213   */ 213   */
214   BOOST_HTTP_DECL 214   BOOST_HTTP_DECL
215   ~fields_base(); 215   ~fields_base();
216   216  
217   //-------------------------------------------- 217   //--------------------------------------------
218   // 218   //
219   // Observers 219   // Observers
220   // 220   //
221   //-------------------------------------------- 221   //--------------------------------------------
222   222  
223   /** Return the largest possible serialized message. 223   /** Return the largest possible serialized message.
224   */ 224   */
225   static 225   static
226   constexpr 226   constexpr
227   std::size_t 227   std::size_t
228   max_size() noexcept 228   max_size() noexcept
229   { 229   {
230   // TODO: this doesn't take into account 230   // TODO: this doesn't take into account
231   // the start-line 231   // the start-line
232   return detail::header::max_offset; 232   return detail::header::max_offset;
233   } 233   }
234   234  
235   /** Return an iterator to the beginning. 235   /** Return an iterator to the beginning.
236   */ 236   */
237   iterator 237   iterator
238   begin() const noexcept; 238   begin() const noexcept;
239   239  
240   /** Return an iterator to the end. 240   /** Return an iterator to the end.
241   */ 241   */
242   iterator 242   iterator
243   end() const noexcept; 243   end() const noexcept;
244   244  
245   /** Return a reverse iterator to the beginning. 245   /** Return a reverse iterator to the beginning.
246   */ 246   */
247   reverse_iterator 247   reverse_iterator
248   rbegin() const noexcept; 248   rbegin() const noexcept;
249   249  
250   /** Return a reverse iterator to the end. 250   /** Return a reverse iterator to the end.
251   */ 251   */
252   reverse_iterator 252   reverse_iterator
253   rend() const noexcept; 253   rend() const noexcept;
254   254  
255   /** Return a string view representing the serialized data. 255   /** Return a string view representing the serialized data.
256   */ 256   */
257   core::string_view 257   core::string_view
HITCBC 258   586 buffer() const noexcept 258   586 buffer() const noexcept
259   { 259   {
HITCBC 260   1172 return core::string_view( 260   1172 return core::string_view(
HITCBC 261   586 h_.cbuf, h_.size); 261   586 h_.cbuf, h_.size);
262   } 262   }
263   263  
264   /** Return the number of fields in the container. 264   /** Return the number of fields in the container.
265   */ 265   */
266   std::size_t 266   std::size_t
HITCBC 267   185 size() const noexcept 267   185 size() const noexcept
268   { 268   {
HITCBC 269   185 return h_.count; 269   185 return h_.count;
270   } 270   }
271   271  
272   /** Return the value of a field, or throws an exception. 272   /** Return the value of a field, or throws an exception.
273   273  
274   If more than one field with the specified 274   If more than one field with the specified
275   name exists, the first field defined by 275   name exists, the first field defined by
276   insertion order is returned. 276   insertion order is returned.
277   277  
278   @par Exception Safety 278   @par Exception Safety
279   Strong guarantee. 279   Strong guarantee.
280   280  
281   @throw std::out_of_range 281   @throw std::out_of_range
282   Field is not found. 282   Field is not found.
283   283  
284   @param id The field name constant. 284   @param id The field name constant.
285   */ 285   */
286   BOOST_HTTP_DECL 286   BOOST_HTTP_DECL
287   core::string_view 287   core::string_view
288   at(field id) const; 288   at(field id) const;
289   289  
290   /** Return the value of a field, or throws an exception. 290   /** Return the value of a field, or throws an exception.
291   291  
292   If more than one field with the specified 292   If more than one field with the specified
293   name exists, the first field defined by 293   name exists, the first field defined by
294   insertion order is returned. 294   insertion order is returned.
295   295  
296   If `name` refers to a known field, it is 296   If `name` refers to a known field, it is
297   faster to call @ref at with a field id 297   faster to call @ref at with a field id
298   instead of a string. 298   instead of a string.
299   299  
300   @par Exception Safety 300   @par Exception Safety
301   Strong guarantee. 301   Strong guarantee.
302   302  
303   @throw std::out_of_range 303   @throw std::out_of_range
304   Field is not found. 304   Field is not found.
305   305  
306   @param name The field name. 306   @param name The field name.
307   */ 307   */
308   BOOST_HTTP_DECL 308   BOOST_HTTP_DECL
309   core::string_view 309   core::string_view
310   at(core::string_view name) const; 310   at(core::string_view name) const;
311   311  
312   /** Return true if a field exists. 312   /** Return true if a field exists.
313   */ 313   */
314   BOOST_HTTP_DECL 314   BOOST_HTTP_DECL
315   bool 315   bool
316   exists(field id) const noexcept; 316   exists(field id) const noexcept;
317   317  
318   /** Return true if a field exists. 318   /** Return true if a field exists.
319   319  
320   If `name` refers to a known field, 320   If `name` refers to a known field,
321   it is faster to call @ref exists 321   it is faster to call @ref exists
322   with a field id instead of a string. 322   with a field id instead of a string.
323   323  
324   @param name The field name. 324   @param name The field name.
325   */ 325   */
326   BOOST_HTTP_DECL 326   BOOST_HTTP_DECL
327   bool 327   bool
328   exists( 328   exists(
329   core::string_view name) const noexcept; 329   core::string_view name) const noexcept;
330   330  
331   /** Return the number of matching fields. 331   /** Return the number of matching fields.
332   332  
333   @param id The field name constant. 333   @param id The field name constant.
334   */ 334   */
335   BOOST_HTTP_DECL 335   BOOST_HTTP_DECL
336   std::size_t 336   std::size_t
337   count(field id) const noexcept; 337   count(field id) const noexcept;
338   338  
339   /** Return the number of matching fields. 339   /** Return the number of matching fields.
340   340  
341   If `name` refers to a known field, 341   If `name` refers to a known field,
342   it is faster to call @ref count 342   it is faster to call @ref count
343   with a field id instead of a string. 343   with a field id instead of a string.
344   344  
345   @param name The field name. 345   @param name The field name.
346   */ 346   */
347   BOOST_HTTP_DECL 347   BOOST_HTTP_DECL
348   std::size_t 348   std::size_t
349   count( 349   count(
350   core::string_view name) const noexcept; 350   core::string_view name) const noexcept;
351   351  
352   /** Return an iterator to the matching element if it exists. 352   /** Return an iterator to the matching element if it exists.
353   353  
354   @param id The field name constant. 354   @param id The field name constant.
355   */ 355   */
356   BOOST_HTTP_DECL 356   BOOST_HTTP_DECL
357   iterator 357   iterator
358   find(field id) const noexcept; 358   find(field id) const noexcept;
359   359  
360   /** Return an iterator to the matching element if it exists. 360   /** Return an iterator to the matching element if it exists.
361   361  
362   If `name` refers to a known field, 362   If `name` refers to a known field,
363   it is faster to call @ref find 363   it is faster to call @ref find
364   with a field id instead of a string. 364   with a field id instead of a string.
365   365  
366   @param name The field name. 366   @param name The field name.
367   */ 367   */
368   BOOST_HTTP_DECL 368   BOOST_HTTP_DECL
369   iterator 369   iterator
370   find( 370   find(
371   core::string_view name) const noexcept; 371   core::string_view name) const noexcept;
372   372  
373   /** Return an iterator to the matching element if it exists. 373   /** Return an iterator to the matching element if it exists.
374   374  
375   @param from The position to begin the 375   @param from The position to begin the
376   search from. This can be `end()`. 376   search from. This can be `end()`.
377   377  
378   @param id The field name constant. 378   @param id The field name constant.
379   */ 379   */
380   BOOST_HTTP_DECL 380   BOOST_HTTP_DECL
381   iterator 381   iterator
382   find( 382   find(
383   iterator from, 383   iterator from,
384   field id) const noexcept; 384   field id) const noexcept;
385   385  
386   /** Return an iterator to the matching element if it exists. 386   /** Return an iterator to the matching element if it exists.
387   387  
388   If `name` refers to a known field, 388   If `name` refers to a known field,
389   it is faster to call @ref find 389   it is faster to call @ref find
390   with a field id instead of a string. 390   with a field id instead of a string.
391   391  
392   @param from The position to begin the 392   @param from The position to begin the
393   search from. This can be `end()`. 393   search from. This can be `end()`.
394   394  
395   @param name The field name. 395   @param name The field name.
396   */ 396   */
397   BOOST_HTTP_DECL 397   BOOST_HTTP_DECL
398   iterator 398   iterator
399   find( 399   find(
400   iterator from, 400   iterator from,
401   core::string_view name) const noexcept; 401   core::string_view name) const noexcept;
402   402  
403   /** Return an iterator to the matching element if it exists. 403   /** Return an iterator to the matching element if it exists.
404   404  
405   @param before One past the position 405   @param before One past the position
406   to begin the search from. This can 406   to begin the search from. This can
407   be `end()`. 407   be `end()`.
408   408  
409   @param id The field name constant. 409   @param id The field name constant.
410   */ 410   */
411   BOOST_HTTP_DECL 411   BOOST_HTTP_DECL
412   iterator 412   iterator
413   find_last( 413   find_last(
414   iterator before, 414   iterator before,
415   field id) const noexcept; 415   field id) const noexcept;
416   416  
417   /** Return an iterator to the matching element if it exists. 417   /** Return an iterator to the matching element if it exists.
418   418  
419   If `name` refers to a known field, 419   If `name` refers to a known field,
420   it is faster to call @ref find_last 420   it is faster to call @ref find_last
421   with a field id instead of a string. 421   with a field id instead of a string.
422   422  
423   @param before One past the position 423   @param before One past the position
424   to begin the search from. This can 424   to begin the search from. This can
425   be `end()`. 425   be `end()`.
426   426  
427   @param name The field name. 427   @param name The field name.
428   */ 428   */
429   BOOST_HTTP_DECL 429   BOOST_HTTP_DECL
430   iterator 430   iterator
431   find_last( 431   find_last(
432   iterator before, 432   iterator before,
433   core::string_view name) const noexcept; 433   core::string_view name) const noexcept;
434   434  
435   /** Return the value of a field or a default if missing. 435   /** Return the value of a field or a default if missing.
436   436  
437   @param id The field name constant. 437   @param id The field name constant.
438   438  
439   @param s The value to be returned if 439   @param s The value to be returned if
440   field does not exist. 440   field does not exist.
441   */ 441   */
442   BOOST_HTTP_DECL 442   BOOST_HTTP_DECL
443   core::string_view 443   core::string_view
444   value_or( 444   value_or(
445   field id, 445   field id,
446   core::string_view s) const noexcept; 446   core::string_view s) const noexcept;
447   447  
448   /** Return the value of a field or a default if missing. 448   /** Return the value of a field or a default if missing.
449   449  
450   If `name` refers to a known field, 450   If `name` refers to a known field,
451   it is faster to call @ref value_or 451   it is faster to call @ref value_or
452   with a field id instead of a string. 452   with a field id instead of a string.
453   453  
454   @param name The field name. 454   @param name The field name.
455   455  
456   @param s The value to be returned if 456   @param s The value to be returned if
457   field does not exist. 457   field does not exist.
458   */ 458   */
459   BOOST_HTTP_DECL 459   BOOST_HTTP_DECL
460   core::string_view 460   core::string_view
461   value_or( 461   value_or(
462   core::string_view name, 462   core::string_view name,
463   core::string_view s) const noexcept; 463   core::string_view s) const noexcept;
464   464  
465   /** Return a forward range containing values for all matching fields. 465   /** Return a forward range containing values for all matching fields.
466   466  
467   @param id The field name constant. 467   @param id The field name constant.
468   */ 468   */
469   BOOST_HTTP_DECL 469   BOOST_HTTP_DECL
470   subrange 470   subrange
471   find_all(field id) const noexcept; 471   find_all(field id) const noexcept;
472   472  
473   /** Return a forward range containing values for all matching fields. 473   /** Return a forward range containing values for all matching fields.
474   474  
475   If `name` refers to a known field, 475   If `name` refers to a known field,
476   it is faster to call @ref find_all 476   it is faster to call @ref find_all
477   with a field id instead of a string. 477   with a field id instead of a string.
478   478  
479   @param name The field name. 479   @param name The field name.
480   */ 480   */
481   BOOST_HTTP_DECL 481   BOOST_HTTP_DECL
482   subrange 482   subrange
483   find_all( 483   find_all(
484   core::string_view name) const noexcept; 484   core::string_view name) const noexcept;
485   485  
486   //-------------------------------------------- 486   //--------------------------------------------
487   // 487   //
488   // Capacity 488   // Capacity
489   // 489   //
490   //-------------------------------------------- 490   //--------------------------------------------
491   491  
492   /** Return the maximum allowed capacity in bytes. 492   /** Return the maximum allowed capacity in bytes.
493   */ 493   */
494   std::size_t 494   std::size_t
HITCBC 495   24 max_capacity_in_bytes() noexcept 495   24 max_capacity_in_bytes() noexcept
496   { 496   {
HITCBC 497   24 return max_cap_; 497   24 return max_cap_;
498   } 498   }
499   499  
500   /** Return the total number of bytes allocated by the container. 500   /** Return the total number of bytes allocated by the container.
501   */ 501   */
502   std::size_t 502   std::size_t
HITCBC 503   105 capacity_in_bytes() const noexcept 503   105 capacity_in_bytes() const noexcept
504   { 504   {
HITCBC 505   105 return h_.cap; 505   105 return h_.cap;
506   } 506   }
507   507  
508   /** Clear contents while preserving the capacity. 508   /** Clear contents while preserving the capacity.
509   509  
510   In the case of response and request 510   In the case of response and request
511   containers the start-line also resets to 511   containers the start-line also resets to
512   default. 512   default.
513   513  
514   @par Postconditions 514   @par Postconditions
515   @code 515   @code
516   this->size() == 0 516   this->size() == 0
517   @endcode 517   @endcode
518   518  
519   @par Complexity 519   @par Complexity
520   Constant. 520   Constant.
521   */ 521   */
522   BOOST_HTTP_DECL 522   BOOST_HTTP_DECL
523   void 523   void
524   clear() noexcept; 524   clear() noexcept;
525   525  
526   /** Adjust the capacity without changing the size. 526   /** Adjust the capacity without changing the size.
527   527  
528   This function adjusts the capacity 528   This function adjusts the capacity
529   of the container in bytes, without 529   of the container in bytes, without
530   affecting the current contents. Has 530   affecting the current contents. Has
531   no effect if `n <= this->capacity_in_bytes()`. 531   no effect if `n <= this->capacity_in_bytes()`.
532   532  
533   @par Postconditions 533   @par Postconditions
534   @code 534   @code
535   this->capacity_in_bytes() >= n 535   this->capacity_in_bytes() >= n
536   @endcode 536   @endcode
537   537  
538   @par Exception Safety 538   @par Exception Safety
539   Strong guarantee. 539   Strong guarantee.
540   Calls to allocate may throw. 540   Calls to allocate may throw.
541   Exception thrown if max capacity exceeded. 541   Exception thrown if max capacity exceeded.
542   542  
543   @throw std::length_error 543   @throw std::length_error
544   Max capacity would be exceeded. 544   Max capacity would be exceeded.
545   545  
546   @param n The capacity in bytes. 546   @param n The capacity in bytes.
547   */ 547   */
548   BOOST_HTTP_DECL 548   BOOST_HTTP_DECL
549   void 549   void
550   reserve_bytes(std::size_t n); 550   reserve_bytes(std::size_t n);
551   551  
552   /** Set the maximum allowed capacity in bytes. 552   /** Set the maximum allowed capacity in bytes.
553   553  
554   Prevents the container from growing beyond 554   Prevents the container from growing beyond
555   `n` bytes. Exceeding this limit will throw 555   `n` bytes. Exceeding this limit will throw
556   an exception. 556   an exception.
557   557  
558   @par Preconditions 558   @par Preconditions
559   @code 559   @code
560   this->capacity_in_bytes() <= n 560   this->capacity_in_bytes() <= n
561   @endcode 561   @endcode
562   562  
563   @par Postconditions 563   @par Postconditions
564   @code 564   @code
565   this->max_capacity_in_bytes() == n 565   this->max_capacity_in_bytes() == n
566   @endcode 566   @endcode
567   567  
568   @par Exception Safety 568   @par Exception Safety
569   Strong guarantee. 569   Strong guarantee.
570   Exception thrown on invalid input. 570   Exception thrown on invalid input.
571   571  
572   @throw std::invalid_argument 572   @throw std::invalid_argument
573   `n < this->capacity_in_bytes()` 573   `n < this->capacity_in_bytes()`
574   574  
575   @param n The maximum allowed capacity in bytes. 575   @param n The maximum allowed capacity in bytes.
576   */ 576   */
577   BOOST_HTTP_DECL 577   BOOST_HTTP_DECL
578   void 578   void
579   set_max_capacity_in_bytes(std::size_t n); 579   set_max_capacity_in_bytes(std::size_t n);
580   580  
581   /** Remove excess capacity. 581   /** Remove excess capacity.
582   582  
583   @par Exception Safety 583   @par Exception Safety
584   Strong guarantee. 584   Strong guarantee.
585   Calls to allocate may throw. 585   Calls to allocate may throw.
586   */ 586   */
587   BOOST_HTTP_DECL 587   BOOST_HTTP_DECL
588   void 588   void
589   shrink_to_fit(); 589   shrink_to_fit();
590   590  
591   //-------------------------------------------- 591   //--------------------------------------------
592   // 592   //
593   // Modifiers 593   // Modifiers
594   // 594   //
595   //-------------------------------------------- 595   //--------------------------------------------
596   596  
597   /** Append a header. 597   /** Append a header.
598   598  
599   This function appends a new header. 599   This function appends a new header.
600   Existing headers with the same name are 600   Existing headers with the same name are
601   not changed. 601   not changed.
602   602  
603   Any leading or trailing whitespace in the 603   Any leading or trailing whitespace in the
604   value is ignored. 604   value is ignored.
605   605  
606   No iterators are invalidated. 606   No iterators are invalidated.
607   607  
608   @par Example 608   @par Example
609   @code 609   @code
610   request req; 610   request req;
611   611  
612   req.append( field::user_agent, "Boost" ); 612   req.append( field::user_agent, "Boost" );
613   @endcode 613   @endcode
614   614  
615   @par Complexity 615   @par Complexity
616   Linear in `to_string( id ).size() + value.size()`. 616   Linear in `to_string( id ).size() + value.size()`.
617   617  
618   @par Exception Safety 618   @par Exception Safety
619   Strong guarantee. 619   Strong guarantee.
620   Calls to allocate may throw. 620   Calls to allocate may throw.
621   Exception thrown on invalid input. 621   Exception thrown on invalid input.
622   Exception thrown if max capacity exceeded. 622   Exception thrown if max capacity exceeded.
623   623  
624   @throw system_error 624   @throw system_error
625   Input is invalid. 625   Input is invalid.
626   626  
627   @throw std::length_error 627   @throw std::length_error
628   Max capacity would be exceeded. 628   Max capacity would be exceeded.
629   629  
630   @param id The field name constant. 630   @param id The field name constant.
631   631  
632   @param value The value which must be semantically 632   @param value The value which must be semantically
633   valid for the message. 633   valid for the message.
634   */ 634   */
635   void 635   void
HITCBC 636   99 append( 636   99 append(
637   field id, 637   field id,
638   core::string_view value) 638   core::string_view value)
639   { 639   {
HITCBC 640   99 system::error_code ec; 640   99 system::error_code ec;
HITCBC 641   99 append(id, value, ec); 641   99 append(id, value, ec);
HITCBC 642   95 if(ec) 642   95 if(ec)
HITCBC 643   3 detail::throw_system_error(ec); 643   3 detail::throw_system_error(ec);
HITCBC 644   92 } 644   92 }
645   645  
646   /** Append a header. 646   /** Append a header.
647   647  
648   This function appends a new header. 648   This function appends a new header.
649   Existing headers with the same name are 649   Existing headers with the same name are
650   not changed. 650   not changed.
651   651  
652   Any leading or trailing whitespace in the 652   Any leading or trailing whitespace in the
653   value is ignored. 653   value is ignored.
654   654  
655   No iterators are invalidated. 655   No iterators are invalidated.
656   656  
657   @par Example 657   @par Example
658   @code 658   @code
659   request req; 659   request req;
660   660  
661   req.append( field::user_agent, "Boost" ); 661   req.append( field::user_agent, "Boost" );
662   @endcode 662   @endcode
663   663  
664   @par Complexity 664   @par Complexity
665   Linear in `to_string( id ).size() + value.size()`. 665   Linear in `to_string( id ).size() + value.size()`.
666   666  
667   @par Exception Safety 667   @par Exception Safety
668   Strong guarantee. 668   Strong guarantee.
669   Calls to allocate may throw. 669   Calls to allocate may throw.
670   Exception thrown if max capacity exceeded. 670   Exception thrown if max capacity exceeded.
671   671  
672   @throw std::length_error 672   @throw std::length_error
673   Max capacity would be exceeded. 673   Max capacity would be exceeded.
674   674  
675   @param id The field name constant. 675   @param id The field name constant.
676   676  
677   @param value The value which must be semantically 677   @param value The value which must be semantically
678   valid for the message. 678   valid for the message.
679   679  
680   @param ec Set to the error if input is invalid. 680   @param ec Set to the error if input is invalid.
681   */ 681   */
682   void 682   void
HITCBC 683   99 append( 683   99 append(
684   field id, 684   field id,
685   core::string_view value, 685   core::string_view value,
686   system::error_code& ec) 686   system::error_code& ec)
687   { 687   {
HITCBC 688   99 insert_impl( 688   99 insert_impl(
689   id, 689   id,
690   to_string(id), 690   to_string(id),
691   value, 691   value,
HITCBC 692   99 h_.count, 692   99 h_.count,
693   ec); 693   ec);
HITCBC 694   95 } 694   95 }
695   695  
696   /** Append a header. 696   /** Append a header.
697   697  
698   This function appends a new header. 698   This function appends a new header.
699   Existing headers with the same name are 699   Existing headers with the same name are
700   not changed. 700   not changed.
701   701  
702   Any leading or trailing whitespace in the 702   Any leading or trailing whitespace in the
703   value is ignored. 703   value is ignored.
704   704  
705   No iterators are invalidated. 705   No iterators are invalidated.
706   706  
707   @par Example 707   @par Example
708   @code 708   @code
709   request req; 709   request req;
710   710  
711   req.append( "User-Agent", "Boost" ); 711   req.append( "User-Agent", "Boost" );
712   @endcode 712   @endcode
713   713  
714   @par Complexity 714   @par Complexity
715   Linear in `name.size() + value.size()`. 715   Linear in `name.size() + value.size()`.
716   716  
717   @par Exception Safety 717   @par Exception Safety
718   Strong guarantee. 718   Strong guarantee.
719   Calls to allocate may throw. 719   Calls to allocate may throw.
720   Exception thrown on invalid input. 720   Exception thrown on invalid input.
721   Exception thrown if max capacity exceeded. 721   Exception thrown if max capacity exceeded.
722   722  
723   @throw system_error 723   @throw system_error
724   Input is invalid. 724   Input is invalid.
725   725  
726   @throw std::length_error 726   @throw std::length_error
727   Max capacity would be exceeded. 727   Max capacity would be exceeded.
728   728  
729   @param name The header name. 729   @param name The header name.
730   730  
731   @param value The header value, which must 731   @param value The header value, which must
732   be semantically valid for the message. 732   be semantically valid for the message.
733   */ 733   */
734   void 734   void
HITCBC 735   48 append( 735   48 append(
736   core::string_view name, 736   core::string_view name,
737   core::string_view value) 737   core::string_view value)
738   { 738   {
HITCBC 739   48 system::error_code ec; 739   48 system::error_code ec;
HITCBC 740   48 append(name, value, ec); 740   48 append(name, value, ec);
HITCBC 741   46 if(ec) 741   46 if(ec)
HITCBC 742   1 detail::throw_system_error(ec); 742   1 detail::throw_system_error(ec);
HITCBC 743   45 } 743   45 }
744   744  
745   /** Append a header. 745   /** Append a header.
746   746  
747   This function appends a new header. 747   This function appends a new header.
748   Existing headers with the same name are 748   Existing headers with the same name are
749   not changed. 749   not changed.
750   750  
751   Any leading or trailing whitespace in the 751   Any leading or trailing whitespace in the
752   value is ignored. 752   value is ignored.
753   753  
754   No iterators are invalidated. 754   No iterators are invalidated.
755   755  
756   @par Example 756   @par Example
757   @code 757   @code
758   request req; 758   request req;
759   759  
760   req.append( "User-Agent", "Boost" ); 760   req.append( "User-Agent", "Boost" );
761   @endcode 761   @endcode
762   762  
763   @par Complexity 763   @par Complexity
764   Linear in `name.size() + value.size()`. 764   Linear in `name.size() + value.size()`.
765   765  
766   @par Exception Safety 766   @par Exception Safety
767   Strong guarantee. 767   Strong guarantee.
768   Calls to allocate may throw. 768   Calls to allocate may throw.
769   Exception thrown if max capacity exceeded. 769   Exception thrown if max capacity exceeded.
770   770  
771   @throw std::length_error 771   @throw std::length_error
772   Max capacity would be exceeded. 772   Max capacity would be exceeded.
773   773  
774   @param name The header name. 774   @param name The header name.
775   775  
776   @param value The value which must be semantically 776   @param value The value which must be semantically
777   valid for the message. 777   valid for the message.
778   778  
779   @param ec Set to the error if input is invalid. 779   @param ec Set to the error if input is invalid.
780   */ 780   */
781   void 781   void
HITCBC 782   61 append( 782   61 append(
783   core::string_view name, 783   core::string_view name,
784   core::string_view value, 784   core::string_view value,
785   system::error_code& ec) 785   system::error_code& ec)
786   { 786   {
HITCBC 787   61 insert_impl( 787   61 insert_impl(
HITCBC 788   122 string_to_field(name), 788   122 string_to_field(name),
789   name, 789   name,
790   value, 790   value,
HITCBC 791   61 h_.count, 791   61 h_.count,
792   ec); 792   ec);
HITCBC 793   59 } 793   59 }
794   794  
795   /** Insert a header. 795   /** Insert a header.
796   796  
797   If a matching header with the same name 797   If a matching header with the same name
798   exists, it is not replaced. Instead, an 798   exists, it is not replaced. Instead, an
799   additional header with the same name is 799   additional header with the same name is
800   inserted. Names are not case-sensitive. 800   inserted. Names are not case-sensitive.
801   Any leading or trailing whitespace in 801   Any leading or trailing whitespace in
802   the new value is ignored. 802   the new value is ignored.
803   803  
804   All iterators that are equal to `before` 804   All iterators that are equal to `before`
805   or come after are invalidated. 805   or come after are invalidated.
806   806  
807   @par Example 807   @par Example
808   @code 808   @code
809   request req; 809   request req;
810   810  
811   req.insert( req.begin(), field::user_agent, "Boost" ); 811   req.insert( req.begin(), field::user_agent, "Boost" );
812   @endcode 812   @endcode
813   813  
814   @par Complexity 814   @par Complexity
815   Linear in `to_string( id ).size() + value.size()`. 815   Linear in `to_string( id ).size() + value.size()`.
816   816  
817   @par Exception Safety 817   @par Exception Safety
818   Strong guarantee. 818   Strong guarantee.
819   Calls to allocate may throw. 819   Calls to allocate may throw.
820   Exception thrown on invalid input. 820   Exception thrown on invalid input.
821   Exception thrown if max capacity exceeded. 821   Exception thrown if max capacity exceeded.
822   822  
823   @throw system_error 823   @throw system_error
824   Input is invalid. 824   Input is invalid.
825   825  
826   @throw std::length_error 826   @throw std::length_error
827   Max capacity would be exceeded. 827   Max capacity would be exceeded.
828   828  
829   @return An iterator to the newly inserted header. 829   @return An iterator to the newly inserted header.
830   830  
831   @param before Position to insert before. 831   @param before Position to insert before.
832   832  
833   @param id The field name constant. 833   @param id The field name constant.
834   834  
835   @param value The value which must be semantically 835   @param value The value which must be semantically
836   valid for the message. 836   valid for the message.
837   */ 837   */
838   BOOST_HTTP_DECL 838   BOOST_HTTP_DECL
839   iterator 839   iterator
840   insert( 840   insert(
841   iterator before, 841   iterator before,
842   field id, 842   field id,
843   core::string_view value); 843   core::string_view value);
844   844  
845   /** Insert a header. 845   /** Insert a header.
846   846  
847   If a matching header with the same name 847   If a matching header with the same name
848   exists, it is not replaced. Instead, an 848   exists, it is not replaced. Instead, an
849   additional header with the same name is 849   additional header with the same name is
850   inserted. Names are not case-sensitive. 850   inserted. Names are not case-sensitive.
851   851  
852   Any leading or trailing whitespace in 852   Any leading or trailing whitespace in
853   the new value is ignored. 853   the new value is ignored.
854   854  
855   All iterators that are equal to `before` 855   All iterators that are equal to `before`
856   or come after are invalidated. 856   or come after are invalidated.
857   857  
858   @par Example 858   @par Example
859   @code 859   @code
860   request req; 860   request req;
861   861  
862   req.insert( req.begin(), field::user_agent, "Boost" ); 862   req.insert( req.begin(), field::user_agent, "Boost" );
863   @endcode 863   @endcode
864   864  
865   @par Complexity 865   @par Complexity
866   Linear in `to_string( id ).size() + value.size()`. 866   Linear in `to_string( id ).size() + value.size()`.
867   867  
868   @par Exception Safety 868   @par Exception Safety
869   Strong guarantee. 869   Strong guarantee.
870   Calls to allocate may throw. 870   Calls to allocate may throw.
871   Exception thrown if max capacity exceeded. 871   Exception thrown if max capacity exceeded.
872   872  
873   @throw std::length_error 873   @throw std::length_error
874   Max capacity would be exceeded. 874   Max capacity would be exceeded.
875   875  
876   @return An iterator to the newly inserted header. 876   @return An iterator to the newly inserted header.
877   877  
878   @param before Position to insert before. 878   @param before Position to insert before.
879   879  
880   @param id The field name constant. 880   @param id The field name constant.
881   881  
882   @param value The value which must be semantically 882   @param value The value which must be semantically
883   valid for the message. 883   valid for the message.
884   884  
885   @param ec Set to the error if input is invalid. 885   @param ec Set to the error if input is invalid.
886   */ 886   */
887   BOOST_HTTP_DECL 887   BOOST_HTTP_DECL
888   iterator 888   iterator
889   insert( 889   insert(
890   iterator before, 890   iterator before,
891   field id, 891   field id,
892   core::string_view value, 892   core::string_view value,
893   system::error_code& ec); 893   system::error_code& ec);
894   894  
895   /** Insert a header. 895   /** Insert a header.
896   896  
897   If a matching header with the same name 897   If a matching header with the same name
898   exists, it is not replaced. Instead, an 898   exists, it is not replaced. Instead, an
899   additional header with the same name is 899   additional header with the same name is
900   inserted. Names are not case-sensitive. 900   inserted. Names are not case-sensitive.
901   901  
902   Any leading or trailing whitespace in 902   Any leading or trailing whitespace in
903   the new value is ignored. 903   the new value is ignored.
904   904  
905   All iterators that are equal to `before` 905   All iterators that are equal to `before`
906   or come after are invalidated. 906   or come after are invalidated.
907   907  
908   @par Example 908   @par Example
909   @code 909   @code
910   request req; 910   request req;
911   911  
912   req.insert( req.begin(), "User-Agent", "Boost" ); 912   req.insert( req.begin(), "User-Agent", "Boost" );
913   @endcode 913   @endcode
914   914  
915   @par Complexity 915   @par Complexity
916   Linear in `name.size() + value.size()`. 916   Linear in `name.size() + value.size()`.
917   917  
918   @par Exception Safety 918   @par Exception Safety
919   Strong guarantee. 919   Strong guarantee.
920   Calls to allocate may throw. 920   Calls to allocate may throw.
921   Exception thrown on invalid input. 921   Exception thrown on invalid input.
922   Exception thrown if max capacity exceeded. 922   Exception thrown if max capacity exceeded.
923   923  
924   @throw system_error 924   @throw system_error
925   Input is invalid. 925   Input is invalid.
926   926  
927   @throw std::length_error 927   @throw std::length_error
928   Max capacity would be exceeded. 928   Max capacity would be exceeded.
929   929  
930   @return An iterator to the newly inserted header. 930   @return An iterator to the newly inserted header.
931   931  
932   @param before Position to insert before. 932   @param before Position to insert before.
933   933  
934   @param name The header name. 934   @param name The header name.
935   935  
936   @param value The value which must be semantically 936   @param value The value which must be semantically
937   valid for the message. 937   valid for the message.
938   */ 938   */
939   BOOST_HTTP_DECL 939   BOOST_HTTP_DECL
940   iterator 940   iterator
941   insert( 941   insert(
942   iterator before, 942   iterator before,
943   core::string_view name, 943   core::string_view name,
944   core::string_view value); 944   core::string_view value);
945   945  
946   /** Insert a header. 946   /** Insert a header.
947   947  
948   If a matching header with the same name 948   If a matching header with the same name
949   exists, it is not replaced. Instead, an 949   exists, it is not replaced. Instead, an
950   additional header with the same name is 950   additional header with the same name is
951   inserted. Names are not case-sensitive. 951   inserted. Names are not case-sensitive.
952   952  
953   Any leading or trailing whitespace in 953   Any leading or trailing whitespace in
954   the new value is ignored. 954   the new value is ignored.
955   955  
956   All iterators that are equal to `before` 956   All iterators that are equal to `before`
957   or come after are invalidated. 957   or come after are invalidated.
958   958  
959   @par Example 959   @par Example
960   @code 960   @code
961   request req; 961   request req;
962   962  
963   req.insert( req.begin(), "User-Agent", "Boost" ); 963   req.insert( req.begin(), "User-Agent", "Boost" );
964   @endcode 964   @endcode
965   965  
966   @par Complexity 966   @par Complexity
967   Linear in `name.size() + value.size()`. 967   Linear in `name.size() + value.size()`.
968   968  
969   @par Exception Safety 969   @par Exception Safety
970   Strong guarantee. 970   Strong guarantee.
971   Calls to allocate may throw. 971   Calls to allocate may throw.
972   Exception thrown if max capacity exceeded. 972   Exception thrown if max capacity exceeded.
973   973  
974   @throw std::length_error 974   @throw std::length_error
975   Max capacity would be exceeded. 975   Max capacity would be exceeded.
976   976  
977   @return An iterator to the newly inserted header. 977   @return An iterator to the newly inserted header.
978   978  
979   @param before Position to insert before. 979   @param before Position to insert before.
980   980  
981   @param name The header name. 981   @param name The header name.
982   982  
983   @param value The value which must be semantically 983   @param value The value which must be semantically
984   valid for the message. 984   valid for the message.
985   985  
986   @param ec Set to the error if input is invalid. 986   @param ec Set to the error if input is invalid.
987   */ 987   */
988   BOOST_HTTP_DECL 988   BOOST_HTTP_DECL
989   iterator 989   iterator
990   insert( 990   insert(
991   iterator before, 991   iterator before,
992   core::string_view name, 992   core::string_view name,
993   core::string_view value, 993   core::string_view value,
994   system::error_code& ec); 994   system::error_code& ec);
995   995  
996   //-------------------------------------------- 996   //--------------------------------------------
997   997  
998   /** Erase headers. 998   /** Erase headers.
999   999  
1000   This function removes the header pointed 1000   This function removes the header pointed
1001   to by `it`. 1001   to by `it`.
1002   1002  
1003   All iterators that are equal to `it` 1003   All iterators that are equal to `it`
1004   or come after are invalidated. 1004   or come after are invalidated.
1005   1005  
1006   @par Complexity 1006   @par Complexity
1007   Linear in `name.size() + value.size()`. 1007   Linear in `name.size() + value.size()`.
1008   1008  
1009   @return An iterator to one past the 1009   @return An iterator to one past the
1010   removed element. 1010   removed element.
1011   1011  
1012   @param it The iterator to the element 1012   @param it The iterator to the element
1013   to erase. 1013   to erase.
1014   */ 1014   */
1015   BOOST_HTTP_DECL 1015   BOOST_HTTP_DECL
1016   iterator 1016   iterator
1017   erase(iterator it) noexcept; 1017   erase(iterator it) noexcept;
1018   1018  
1019   /** Erase headers. 1019   /** Erase headers.
1020   1020  
1021   This removes all headers whose name 1021   This removes all headers whose name
1022   constant is equal to `id`. 1022   constant is equal to `id`.
1023   1023  
1024   If any headers are erased, then all 1024   If any headers are erased, then all
1025   iterators equal to or that come after 1025   iterators equal to or that come after
1026   the first erased element are invalidated. 1026   the first erased element are invalidated.
1027   Otherwise, no iterators are invalidated. 1027   Otherwise, no iterators are invalidated.
1028   1028  
1029   @par Complexity 1029   @par Complexity
1030   Linear in `this->string().size()`. 1030   Linear in `this->string().size()`.
1031   1031  
1032   @return The number of headers erased. 1032   @return The number of headers erased.
1033   1033  
1034   @param id The field name constant. 1034   @param id The field name constant.
1035   */ 1035   */
1036   BOOST_HTTP_DECL 1036   BOOST_HTTP_DECL
1037   std::size_t 1037   std::size_t
1038   erase(field id) noexcept; 1038   erase(field id) noexcept;
1039   1039  
1040   /** Erase all matching fields. 1040   /** Erase all matching fields.
1041   1041  
1042   This removes all headers with a matching 1042   This removes all headers with a matching
1043   name, using a case-insensitive comparison. 1043   name, using a case-insensitive comparison.
1044   1044  
1045   If any headers are erased, then all 1045   If any headers are erased, then all
1046   iterators equal to or that come after 1046   iterators equal to or that come after
1047   the first erased element are invalidated. 1047   the first erased element are invalidated.
1048   Otherwise, no iterators are invalidated. 1048   Otherwise, no iterators are invalidated.
1049   1049  
1050   @par Complexity 1050   @par Complexity
1051   Linear in `this->string().size()`. 1051   Linear in `this->string().size()`.
1052   1052  
1053   @return The number of fields erased 1053   @return The number of fields erased
1054   1054  
1055   @param name The header name. 1055   @param name The header name.
1056   */ 1056   */
1057   BOOST_HTTP_DECL 1057   BOOST_HTTP_DECL
1058   std::size_t 1058   std::size_t
1059   erase( 1059   erase(
1060   core::string_view name) noexcept; 1060   core::string_view name) noexcept;
1061   1061  
1062   //-------------------------------------------- 1062   //--------------------------------------------
1063   1063  
1064   /** Set a header value. 1064   /** Set a header value.
1065   1065  
1066   Uses the given value to overwrite the 1066   Uses the given value to overwrite the
1067   current one in the header field pointed to 1067   current one in the header field pointed to
1068   by the iterator. The value must be 1068   by the iterator. The value must be
1069   syntactically valid or else an error is 1069   syntactically valid or else an error is
1070   returned. 1070   returned.
1071   1071  
1072   Any leading or trailing whitespace in the 1072   Any leading or trailing whitespace in the
1073   new value is ignored. 1073   new value is ignored.
1074   1074  
1075   @par Complexity 1075   @par Complexity
1076   1076  
1077   @par Exception Safety 1077   @par Exception Safety
1078   Strong guarantee. 1078   Strong guarantee.
1079   Calls to allocate may throw. 1079   Calls to allocate may throw.
1080   Exception thrown on invalid input. 1080   Exception thrown on invalid input.
1081   Exception thrown if max capacity exceeded. 1081   Exception thrown if max capacity exceeded.
1082   1082  
1083   @throw system_error 1083   @throw system_error
1084   Input is invalid. 1084   Input is invalid.
1085   1085  
1086   @throw std::length_error 1086   @throw std::length_error
1087   Max capacity would be exceeded. 1087   Max capacity would be exceeded.
1088   1088  
1089   @param it The iterator to the header. 1089   @param it The iterator to the header.
1090   1090  
1091   @param value The value which must be semantically 1091   @param value The value which must be semantically
1092   valid for the message. 1092   valid for the message.
1093   */ 1093   */
1094   BOOST_HTTP_DECL 1094   BOOST_HTTP_DECL
1095   void 1095   void
1096   set(iterator it, core::string_view value); 1096   set(iterator it, core::string_view value);
1097   1097  
1098   /** Set a header value. 1098   /** Set a header value.
1099   1099  
1100   Uses the given value to overwrite the 1100   Uses the given value to overwrite the
1101   current one in the header field pointed to 1101   current one in the header field pointed to
1102   by the iterator. The value must be 1102   by the iterator. The value must be
1103   syntactically valid or else an error is 1103   syntactically valid or else an error is
1104   returned. 1104   returned.
1105   1105  
1106   Any leading or trailing whitespace in the 1106   Any leading or trailing whitespace in the
1107   new value is ignored. 1107   new value is ignored.
1108   1108  
1109   @par Complexity 1109   @par Complexity
1110   1110  
1111   @par Exception Safety 1111   @par Exception Safety
1112   Strong guarantee. 1112   Strong guarantee.
1113   Calls to allocate may throw. 1113   Calls to allocate may throw.
1114   Exception thrown if max capacity exceeded. 1114   Exception thrown if max capacity exceeded.
1115   1115  
1116   @throw std::length_error 1116   @throw std::length_error
1117   Max capacity would be exceeded. 1117   Max capacity would be exceeded.
1118   1118  
1119   @param it The iterator to the header. 1119   @param it The iterator to the header.
1120   1120  
1121   @param value The value which must be semantically 1121   @param value The value which must be semantically
1122   valid for the message. 1122   valid for the message.
1123   1123  
1124   @param ec Set to the error if input is invalid. 1124   @param ec Set to the error if input is invalid.
1125   */ 1125   */
1126   BOOST_HTTP_DECL 1126   BOOST_HTTP_DECL
1127   void 1127   void
1128   set( 1128   set(
1129   iterator it, 1129   iterator it,
1130   core::string_view value, 1130   core::string_view value,
1131   system::error_code& ec); 1131   system::error_code& ec);
1132   1132  
1133   /** Set a header value. 1133   /** Set a header value.
1134   1134  
1135   The container is modified to contain 1135   The container is modified to contain
1136   exactly one field with the specified id 1136   exactly one field with the specified id
1137   set to the given value, which must be 1137   set to the given value, which must be
1138   syntactically valid or else an error is 1138   syntactically valid or else an error is
1139   returned. 1139   returned.
1140   1140  
1141   Any leading or trailing whitespace in the 1141   Any leading or trailing whitespace in the
1142   new value is ignored. 1142   new value is ignored.
1143   1143  
1144   @par Postconditions 1144   @par Postconditions
1145   @code 1145   @code
1146   this->count( id ) == 1 && this->at( id ) == value 1146   this->count( id ) == 1 && this->at( id ) == value
1147   @endcode 1147   @endcode
1148   1148  
1149   @par Complexity 1149   @par Complexity
1150   1150  
1151   @par Exception Safety 1151   @par Exception Safety
1152   Strong guarantee. 1152   Strong guarantee.
1153   Calls to allocate may throw. 1153   Calls to allocate may throw.
1154   Exception thrown on invalid input. 1154   Exception thrown on invalid input.
1155   Exception thrown if max capacity exceeded. 1155   Exception thrown if max capacity exceeded.
1156   1156  
1157   @throw system_error 1157   @throw system_error
1158   Input is invalid. 1158   Input is invalid.
1159   1159  
1160   @throw std::length_error 1160   @throw std::length_error
1161   Max capacity would be exceeded. 1161   Max capacity would be exceeded.
1162   1162  
1163   @param id The field constant of the header 1163   @param id The field constant of the header
1164   to set. 1164   to set.
1165   1165  
1166   @param value The value which must be semantically 1166   @param value The value which must be semantically
1167   valid for the message. 1167   valid for the message.
1168   */ 1168   */
1169   void 1169   void
HITCBC 1170   104 set( 1170   104 set(
1171   field id, 1171   field id,
1172   core::string_view value) 1172   core::string_view value)
1173   { 1173   {
HITCBC 1174   104 system::error_code ec; 1174   104 system::error_code ec;
HITCBC 1175   104 set(id, value, ec); 1175   104 set(id, value, ec);
HITCBC 1176   104 if(ec) 1176   104 if(ec)
HITCBC 1177   2 detail::throw_system_error(ec); 1177   2 detail::throw_system_error(ec);
HITCBC 1178   102 } 1178   102 }
1179   1179  
1180   /** Set a header value. 1180   /** Set a header value.
1181   1181  
1182   The container is modified to contain 1182   The container is modified to contain
1183   exactly one field with the specified id 1183   exactly one field with the specified id
1184   set to the given value, which must be 1184   set to the given value, which must be
1185   syntactically valid or else an error is 1185   syntactically valid or else an error is
1186   returned. 1186   returned.
1187   1187  
1188   Any leading or trailing whitespace in the 1188   Any leading or trailing whitespace in the
1189   new value is ignored. 1189   new value is ignored.
1190   1190  
1191   @par Postconditions 1191   @par Postconditions
1192   @code 1192   @code
1193   this->count( id ) == 1 && this->at( id ) == value 1193   this->count( id ) == 1 && this->at( id ) == value
1194   @endcode 1194   @endcode
1195   1195  
1196   @par Complexity 1196   @par Complexity
1197   1197  
1198   @par Exception Safety 1198   @par Exception Safety
1199   Strong guarantee. 1199   Strong guarantee.
1200   Calls to allocate may throw. 1200   Calls to allocate may throw.
1201   Exception thrown if max capacity exceeded. 1201   Exception thrown if max capacity exceeded.
1202   1202  
1203   @throw std::length_error 1203   @throw std::length_error
1204   Max capacity would be exceeded. 1204   Max capacity would be exceeded.
1205   1205  
1206   @param id The field name constant. 1206   @param id The field name constant.
1207   1207  
1208   @param value The value which must be semantically 1208   @param value The value which must be semantically
1209   valid for the message. 1209   valid for the message.
1210   1210  
1211   @param ec Set to the error if input is invalid. 1211   @param ec Set to the error if input is invalid.
1212   */ 1212   */
1213   BOOST_HTTP_DECL 1213   BOOST_HTTP_DECL
1214   void 1214   void
1215   set( 1215   set(
1216   field id, 1216   field id,
1217   core::string_view value, 1217   core::string_view value,
1218   system::error_code& ec); 1218   system::error_code& ec);
1219   1219  
1220   /** Set a header value. 1220   /** Set a header value.
1221   1221  
1222   The container is modified to contain 1222   The container is modified to contain
1223   exactly one field with the specified name 1223   exactly one field with the specified name
1224   set to the given value, which must be 1224   set to the given value, which must be
1225   syntactically valid or else an error is 1225   syntactically valid or else an error is
1226   returned. 1226   returned.
1227   1227  
1228   Any leading or trailing whitespace in the 1228   Any leading or trailing whitespace in the
1229   new value is ignored. 1229   new value is ignored.
1230   1230  
1231   @par Postconditions 1231   @par Postconditions
1232   @code 1232   @code
1233   this->count( name ) == 1 && this->at( name ) == value 1233   this->count( name ) == 1 && this->at( name ) == value
1234   @endcode 1234   @endcode
1235   1235  
1236   @par Complexity 1236   @par Complexity
1237   1237  
1238   @par Exception Safety 1238   @par Exception Safety
1239   Strong guarantee. 1239   Strong guarantee.
1240   Calls to allocate may throw. 1240   Calls to allocate may throw.
1241   Exception thrown on invalid input. 1241   Exception thrown on invalid input.
1242   Exception thrown if max capacity exceeded. 1242   Exception thrown if max capacity exceeded.
1243   1243  
1244   @throw system_error 1244   @throw system_error
1245   Input is invalid. 1245   Input is invalid.
1246   1246  
1247   @throw std::length_error 1247   @throw std::length_error
1248   Max capacity would be exceeded. 1248   Max capacity would be exceeded.
1249   1249  
1250   @param name The field name. 1250   @param name The field name.
1251   1251  
1252   @param value The value which must be semantically 1252   @param value The value which must be semantically
1253   valid for the message. 1253   valid for the message.
1254   */ 1254   */
1255   void 1255   void
HITCBC 1256   28 set( 1256   28 set(
1257   core::string_view name, 1257   core::string_view name,
1258   core::string_view value) 1258   core::string_view value)
1259   { 1259   {
HITCBC 1260   28 system::error_code ec; 1260   28 system::error_code ec;
HITCBC 1261   28 set(name, value, ec); 1261   28 set(name, value, ec);
HITCBC 1262   27 if(ec) 1262   27 if(ec)
HITCBC 1263   4 detail::throw_system_error(ec); 1263   4 detail::throw_system_error(ec);
HITCBC 1264   23 } 1264   23 }
1265   1265  
1266   /** Set a header value. 1266   /** Set a header value.
1267   1267  
1268   The container is modified to contain 1268   The container is modified to contain
1269   exactly one field with the specified name 1269   exactly one field with the specified name
1270   set to the given value, which must be 1270   set to the given value, which must be
1271   syntactically valid or else an error is 1271   syntactically valid or else an error is
1272   returned. 1272   returned.
1273   1273  
1274   Any leading or trailing whitespace in the 1274   Any leading or trailing whitespace in the
1275   new value is ignored. 1275   new value is ignored.
1276   1276  
1277   @par Postconditions 1277   @par Postconditions
1278   @code 1278   @code
1279   this->count( name ) == 1 && this->at( name ) == value 1279   this->count( name ) == 1 && this->at( name ) == value
1280   @endcode 1280   @endcode
1281   1281  
1282   @par Complexity 1282   @par Complexity
1283   1283  
1284   @par Exception Safety 1284   @par Exception Safety
1285   Strong guarantee. 1285   Strong guarantee.
1286   Calls to allocate may throw. 1286   Calls to allocate may throw.
1287   Exception thrown if max capacity exceeded. 1287   Exception thrown if max capacity exceeded.
1288   1288  
1289   @throw std::length_error 1289   @throw std::length_error
1290   Max capacity would be exceeded. 1290   Max capacity would be exceeded.
1291   1291  
1292   @param name The field name. 1292   @param name The field name.
1293   1293  
1294   @param value The value which must be semantically 1294   @param value The value which must be semantically
1295   valid for the message. 1295   valid for the message.
1296   1296  
1297   @param ec Set to the error if input is invalid. 1297   @param ec Set to the error if input is invalid.
1298   */ 1298   */
1299   BOOST_HTTP_DECL 1299   BOOST_HTTP_DECL
1300   void 1300   void
1301   set( 1301   set(
1302   core::string_view name, 1302   core::string_view name,
1303   core::string_view value, 1303   core::string_view value,
1304   system::error_code& ec); 1304   system::error_code& ec);
1305   1305  
1306   //-------------------------------------------- 1306   //--------------------------------------------
1307   1307  
1308   /** Format the container to the output stream 1308   /** Format the container to the output stream
1309   1309  
1310   This function serializes the container to 1310   This function serializes the container to
1311   the specified output stream. 1311   the specified output stream.
1312   1312  
1313   @par Example 1313   @par Example
1314   @code 1314   @code
1315   request req; 1315   request req;
1316   req.set(field::content_length, "42"); 1316   req.set(field::content_length, "42");
1317   std::stringstream ss; 1317   std::stringstream ss;
1318   ss << req; 1318   ss << req;
1319   assert( ss.str() == "GET / HTTP/1.1\nContent-Length: 42\n" ); 1319   assert( ss.str() == "GET / HTTP/1.1\nContent-Length: 42\n" );
1320   @endcode 1320   @endcode
1321   1321  
1322   @par Effects 1322   @par Effects
1323   @code 1323   @code
1324   return os << f.buffer(); 1324   return os << f.buffer();
1325   @endcode 1325   @endcode
1326   1326  
1327   @par Complexity 1327   @par Complexity
1328   Linear in `f.buffer().size()` 1328   Linear in `f.buffer().size()`
1329   1329  
1330   @par Exception Safety 1330   @par Exception Safety
1331   Basic guarantee. 1331   Basic guarantee.
1332   1332  
1333   @return A reference to the output stream, for chaining 1333   @return A reference to the output stream, for chaining
1334   1334  
1335   @param os The output stream to write to. 1335   @param os The output stream to write to.
1336   1336  
1337   @param f The container to write. 1337   @param f The container to write.
1338   */ 1338   */
1339   friend 1339   friend
1340   BOOST_HTTP_DECL 1340   BOOST_HTTP_DECL
1341   std::ostream& 1341   std::ostream&
1342   operator<<( 1342   operator<<(
1343   std::ostream& os, 1343   std::ostream& os,
1344   const fields_base& f); 1344   const fields_base& f);
1345   1345  
1346   private: 1346   private:
1347   BOOST_HTTP_DECL 1347   BOOST_HTTP_DECL
1348   void 1348   void
1349   copy_impl( 1349   copy_impl(
1350   detail::header const&); 1350   detail::header const&);
1351   1351  
1352   BOOST_HTTP_DECL 1352   BOOST_HTTP_DECL
1353   void 1353   void
1354   insert_impl( 1354   insert_impl(
1355   optional<field> id, 1355   optional<field> id,
1356   core::string_view name, 1356   core::string_view name,
1357   core::string_view value, 1357   core::string_view value,
1358   std::size_t before, 1358   std::size_t before,
1359   system::error_code& ec); 1359   system::error_code& ec);
1360   1360  
1361   void 1361   void
1362   insert_unchecked( 1362   insert_unchecked(
1363   optional<field> id, 1363   optional<field> id,
1364   core::string_view name, 1364   core::string_view name,
1365   core::string_view value, 1365   core::string_view value,
1366   std::size_t before, 1366   std::size_t before,
1367   bool has_obs_fold); 1367   bool has_obs_fold);
1368   1368  
1369   void 1369   void
1370   raw_erase( 1370   raw_erase(
1371   std::size_t) noexcept; 1371   std::size_t) noexcept;
1372   1372  
1373   void 1373   void
1374   raw_erase_n(field, std::size_t) noexcept; 1374   raw_erase_n(field, std::size_t) noexcept;
1375   1375  
1376   std::size_t 1376   std::size_t
1377   erase_all( 1377   erase_all(
1378   std::size_t i0, 1378   std::size_t i0,
1379   field id) noexcept; 1379   field id) noexcept;
1380   1380  
1381   std::size_t 1381   std::size_t
1382   erase_all( 1382   erase_all(
1383   std::size_t i0, 1383   std::size_t i0,
1384   core::string_view name) noexcept; 1384   core::string_view name) noexcept;
1385   1385  
1386   std::size_t 1386   std::size_t
1387   offset( 1387   offset(
1388   std::size_t i) const noexcept; 1388   std::size_t i) const noexcept;
1389   1389  
1390   std::size_t 1390   std::size_t
1391   length( 1391   length(
1392   std::size_t i) const noexcept; 1392   std::size_t i) const noexcept;
1393   }; 1393   };
1394   1394  
1395   } // http 1395   } // http
1396   } // boost 1396   } // boost
1397   1397  
1398   #include <boost/http/impl/fields_base.hpp> 1398   #include <boost/http/impl/fields_base.hpp>
1399   1399  
1400   #endif 1400   #endif