Index/include / boost / burl / fields.hpp

include/boost/burl/fields.hpp

100.0% Lines (5/5) 100.0% List of functions (2/2) -% Branches (0/0)
[ ] prev/next file
fields.hpp
f(x) Functions (2)
Function Calls Lines Blocks
boost::burl::swap(boost::burl::fields&, boost::burl::fields&) :281 1x 100.0% 100.0% boost::burl::fields::static_() const :343 445x 100.0% 100.0%
Line TLA Hits Source Code
1 //
2 // Copyright (c) 2021 Vinnie Falco ([email protected])
3 // Copyright (c) 2026 Mohammad Nejati
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/burl
9 //
10
11 #ifndef BOOST_BURL_FIELDS_HPP
12 #define BOOST_BURL_FIELDS_HPP
13
14 #include <boost/burl/detail/config.hpp>
15 #include <boost/burl/fields_base.hpp>
16
17 #include <initializer_list>
18
19 namespace boost
20 {
21 namespace burl
22 {
23
24 /** A dynamic container of HTTP fields.
25
26 This container owns a sequence of HTTP fields in
27 a single allocation which grows as needed.
28
29 A default-constructed container refers to a static
30 two-byte buffer holding the final "\r\n" and does
31 not allocate.
32
33 @see @ref fields_base for the shared observers,
34 lookup functions, and modifiers.
35 */
36 class fields : public fields_base
37 {
38 public:
39 //--------------------------------------------
40 //
41 // Special members
42 //
43 //--------------------------------------------
44
45 /** Constructor.
46
47 The container is empty and does not
48 allocate; @ref buffer returns "\r\n".
49
50 @par Postconditions
51 @code
52 this->capacity_in_bytes() == 0
53 @endcode
54
55 @par Complexity
56 Constant.
57 */
58 BOOST_BURL_DECL
59 fields() noexcept;
60
61 /** Destructor.
62
63 Any allocated memory is released. All
64 iterators, references, and views obtained
65 from the container are invalidated.
66
67 @par Complexity
68 Constant.
69 */
70 BOOST_BURL_DECL
71 ~fields();
72
73 /** Constructor.
74
75 The container acquires ownership of the
76 contents of `other`, which is left in its
77 default-constructed state. Views obtained
78 from `other` remain valid; its iterators
79 are invalidated.
80
81 @par Postconditions
82 @code
83 other.capacity_in_bytes() == 0
84 @endcode
85
86 @par Complexity
87 Constant.
88 */
89 BOOST_BURL_DECL
90 fields(fields&& other) noexcept;
91
92 /** Constructor.
93
94 The contents of `other` are copied into
95 an exact-fit allocation. No allocation
96 occurs when `other` is empty.
97
98 @par Complexity
99 Linear in `other.buffer().size()`.
100
101 @par Exception Safety
102 Strong guarantee.
103 Calls to allocate may throw.
104 */
105 BOOST_BURL_DECL
106 fields(fields const& other);
107
108 /** Constructor.
109
110 The field section of `other` is copied into
111 an exact-fit allocation. When `other` is a
112 message header, only its fields are copied;
113 the start line is discarded. No allocation
114 occurs when `other` is empty.
115
116 This constructor is `explicit`: converting a
117 non-owning view into an owning container
118 allocates, and discarding a header's start
119 line should be deliberate.
120
121 @par Complexity
122 Linear in `other.buffer().size()`.
123
124 @par Exception Safety
125 Strong guarantee.
126 Calls to allocate may throw.
127
128 @param other The fields to copy.
129 */
130 BOOST_BURL_DECL
131 explicit
132 fields(fields_base const& other);
133
134 /** Constructor.
135
136 The container is constructed with a copy
137 of the fields in `init`, equivalent to
138 calling @ref append for each element in
139 order. Duplicate names are allowed and
140 their relative order is preserved.
141
142 The storage is allocated exactly once.
143 No allocation occurs when `init` is
144 empty.
145
146 @par Example
147 @code
148 fields f = {
149 { http::field::host, "example.com" },
150 { "X-Request-Id", "42" },
151 };
152 @endcode
153
154 @par Complexity
155 Linear in the total size of the names
156 and values in `init`.
157
158 @par Exception Safety
159 Strong guarantee.
160 Calls to allocate may throw.
161 Exception thrown if a size limit would be
162 exceeded.
163
164 @throw std::length_error
165 A size limit would be exceeded; see
166 @ref max_name_size, @ref max_value_size,
167 and @ref max_buffer_size.
168
169 @param init The fields to insert.
170 */
171 BOOST_BURL_DECL
172 fields(std::initializer_list<field_view> init);
173
174 /** Assignment.
175
176 The container acquires ownership of the
177 contents of `other`, which is left in its
178 default-constructed state. The previous
179 contents are destroyed.
180
181 @par Complexity
182 Constant.
183 */
184 BOOST_BURL_DECL
185 fields&
186 operator=(fields&& other) noexcept;
187
188 /** Assignment.
189
190 The contents are replaced with a copy of
191 `other`. The existing allocation is reused
192 when it is large enough.
193
194 @par Complexity
195 Linear in `other.buffer().size()`.
196
197 @par Exception Safety
198 Strong guarantee.
199 Calls to allocate may throw.
200 */
201 BOOST_BURL_DECL
202 fields&
203 operator=(fields const& other);
204
205 /** Assignment.
206
207 The contents are replaced with a copy of the
208 field section of `other`. When `other` is a
209 message header, only its fields are copied;
210 the start line is discarded.
211
212 @par Complexity
213 Linear in `other.buffer().size()`.
214
215 @par Exception Safety
216 Strong guarantee.
217 Calls to allocate may throw.
218
219 @param other The fields to copy.
220 */
221 BOOST_BURL_DECL
222 fields&
223 operator=(fields_base const& other);
224
225 /** Swap the contents.
226
227 The contents of the two containers are
228 exchanged. No allocation occurs and no
229 bytes are copied.
230
231 Views obtained from either container remain
232 valid; they follow the contents into the
233 other container. Iterators are invalidated:
234 an iterator stays bound to the container it
235 was obtained from, which now holds different
236 fields.
237
238 If `this == &other`, this function call has
239 no effect.
240
241 @par Complexity
242 Constant.
243
244 @par Exception Safety
245 No-throw guarantee.
246
247 @param other The container to swap with.
248 */
249 BOOST_BURL_DECL
250 void
251 swap(fields& other) noexcept;
252
253 /** Swap the contents.
254
255 The contents of the two containers are
256 exchanged. No allocation occurs and no
257 bytes are copied.
258
259 If `&v0 == &v1`, this function call has no
260 effect.
261
262 @par Effects
263 @code
264 v0.swap(v1);
265 @endcode
266
267 @par Complexity
268 Constant.
269
270 @par Exception Safety
271 No-throw guarantee.
272
273 @param v0 The first container to swap.
274
275 @param v1 The second container to swap.
276
277 @see @ref fields::swap
278 */
279 friend
280 void
281 1x swap(
282 fields& v0,
283 fields& v1) noexcept
284 {
285 1x v0.swap(v1);
286 1x }
287
288 //--------------------------------------------
289 //
290 // Capacity
291 //
292 //--------------------------------------------
293
294 /** Reserve storage.
295
296 This function ensures that @ref buffer
297 can grow to `bytes` bytes, and the
298 number of fields to `count`, without
299 a reallocation. Has no effect if the
300 current capacity is already sufficient.
301
302 All references and views are invalidated
303 when a reallocation occurs.
304
305 @par Exception Safety
306 Strong guarantee.
307 Calls to allocate may throw.
308 Exception thrown if a size limit would be
309 exceeded.
310
311 @throw std::length_error
312 `bytes` exceeds @ref max_buffer_size, or
313 `count` exceeds @ref max_field_count.
314
315 @param bytes The serialized size in bytes.
316
317 @param count The number of fields.
318 */
319 BOOST_BURL_DECL
320 void
321 reserve(
322 std::size_t bytes,
323 std::size_t count);
324
325 /** Remove excess capacity.
326
327 An empty container releases its
328 allocation entirely.
329
330 All references and views are invalidated
331 when a reallocation occurs.
332
333 @par Exception Safety
334 Strong guarantee.
335 Calls to allocate may throw.
336 */
337 BOOST_BURL_DECL
338 void
339 shrink_to_fit();
340
341 private:
342 bool
343 445x static_() const noexcept override
344 {
345 445x return false;
346 }
347 };
348
349 } // namespace burl
350 } // namespace boost
351
352 #endif
353