1<html> 2<head> 3<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> 4<title>Buffer Types</title> 5<link rel="stylesheet" href="../../../../../../doc/src/boostbook.css" type="text/css"> 6<meta name="generator" content="DocBook XSL Stylesheets V1.79.1"> 7<link rel="home" href="../../index.html" title="Chapter 1. Boost.Beast"> 8<link rel="up" href="../using_io.html" title="Networking"> 9<link rel="prev" href="layered_streams/counted_stream_example.html" title="Counted Stream ��"> 10<link rel="next" href="files.html" title="Files"> 11</head> 12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> 13<table cellpadding="2" width="100%"><tr> 14<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../boost.png"></td> 15<td align="center"><a href="../../../../../../index.html">Home</a></td> 16<td align="center"><a href="../../../../../../libs/libraries.htm">Libraries</a></td> 17<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td> 18<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td> 19<td align="center"><a href="../../../../../../more/index.htm">More</a></td> 20</tr></table> 21<hr> 22<div class="spirit-nav"> 23<a accesskey="p" href="layered_streams/counted_stream_example.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../using_io.html"><img src="../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="files.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a> 24</div> 25<div class="section"> 26<div class="titlepage"><div><div><h3 class="title"> 27<a name="beast.using_io.buffer_types"></a><a class="link" href="buffer_types.html" title="Buffer Types">Buffer Types</a> 28</h3></div></div></div> 29<p> 30 To facilitate working with instances of the <a href="../../../../../../doc/html/boost_asio/reference/ConstBufferSequence.html" target="_top"><span class="emphasis"><em>ConstBufferSequence</em></span></a> 31 and <a href="../../../../../../doc/html/boost_asio/reference/MutableBufferSequence.html" target="_top"><span class="emphasis"><em>MutableBufferSequence</em></span></a> 32 concepts introduced in <a href="../../../../../../libs/asio/index.html" target="_top">Boost.Asio</a>, 33 Beast treats those sequences as a special type of range. The following algorithms 34 and wrappers are provided which transform these ranges efficiently using 35 lazy evaluation. No memory allocations are used in the transformations; instead, 36 they create lightweight iterators over the existing, unmodified memory buffers. 37 Control of buffers is retained by the caller; ownership is not transferred. 38 </p> 39<div class="table"> 40<a name="beast.using_io.buffer_types.buffer_algorithms_and_types"></a><p class="title"><b>Table 1.7. Buffer Algorithms and Types</b></p> 41<div class="table-contents"><table class="table" summary="Buffer Algorithms and Types"> 42<colgroup> 43<col> 44<col> 45</colgroup> 46<thead><tr> 47<th> 48 <p> 49 Name 50 </p> 51 </th> 52<th> 53 <p> 54 Description 55 </p> 56 </th> 57</tr></thead> 58<tbody> 59<tr> 60<td> 61 <p> 62 <a class="link" href="../ref/boost__beast__buffer_bytes.html" title="buffer_bytes"><code class="computeroutput"><span class="identifier">buffer_bytes</span></code></a> 63 </p> 64 </td> 65<td> 66 <p> 67 This is a more reliable version of <a href="../../../../../../doc/html/boost_asio/reference/buffer_size.html" target="_top"><code class="computeroutput"><span class="identifier">net</span><span class="special">::</span><span class="identifier">buffer_size</span></code></a> which is 68 easier to use and also works for types which are convertible to 69 <code class="computeroutput"><span class="identifier">net</span><span class="special">::</span><span class="identifier">const_buffer</span></code> or <code class="computeroutput"><span class="identifier">net</span><span class="special">::</span><span class="identifier">mutable_buffer</span></code>. 70 </p> 71 </td> 72</tr> 73<tr> 74<td> 75 <p> 76 <a class="link" href="../ref/boost__beast__buffers_cat.html" title="buffers_cat"><code class="computeroutput"><span class="identifier">buffers_cat</span></code></a> 77 </p> 78 </td> 79<td> 80 <p> 81 This functions returns a new buffer sequence which, when iterated, 82 traverses the sequence which would be formed if all of the input 83 buffer sequences were concatenated. With this routine, multiple 84 calls to a stream's <code class="computeroutput"><span class="identifier">write_some</span></code> 85 function may be combined into one, eliminating expensive system 86 calls. 87 </p> 88 </td> 89</tr> 90<tr> 91<td> 92 <p> 93 <a class="link" href="../ref/boost__beast__buffers_cat_view.html" title="buffers_cat_view"><code class="computeroutput"><span class="identifier">buffers_cat_view</span></code></a> 94 </p> 95 </td> 96<td> 97 <p> 98 This class represents the buffer sequence formed by concatenating 99 two or more buffer sequences. This is type of object returned by 100 <a class="link" href="../ref/boost__beast__buffers_cat.html" title="buffers_cat"><code class="computeroutput"><span class="identifier">buffers_cat</span></code></a>. 101 </p> 102 </td> 103</tr> 104<tr> 105<td> 106 <p> 107 <a class="link" href="../ref/boost__beast__buffers_front.html" title="buffers_front"><code class="computeroutput"><span class="identifier">buffers_front</span></code></a> 108 </p> 109 </td> 110<td> 111 <p> 112 This function returns the first buffer in a buffer sequence, or 113 a buffer of size zero if the buffer sequence has no elements. 114 </p> 115 </td> 116</tr> 117<tr> 118<td> 119 <p> 120 <a class="link" href="../ref/boost__beast__buffers_prefix.html" title="buffers_prefix"><code class="computeroutput"><span class="identifier">buffers_prefix</span></code></a> 121 </p> 122 </td> 123<td> 124 <p> 125 This function returns a new buffer or buffer sequence which represents 126 a prefix of the original buffers. 127 </p> 128 </td> 129</tr> 130<tr> 131<td> 132 <p> 133 <a class="link" href="../ref/boost__beast__buffers_prefix_view.html" title="buffers_prefix_view"><code class="computeroutput"><span class="identifier">buffers_prefix_view</span></code></a> 134 </p> 135 </td> 136<td> 137 <p> 138 This class represents the buffer sequence formed from a prefix 139 of an existing buffer sequence. This is the type of buffer returned 140 by <a class="link" href="../ref/boost__beast__buffers_prefix.html" title="buffers_prefix"><code class="computeroutput"><span class="identifier">buffers_prefix</span></code></a>. 141 </p> 142 </td> 143</tr> 144<tr> 145<td> 146 <p> 147 <a class="link" href="../ref/boost__beast__buffers_range.html" title="buffers_range"><code class="computeroutput"><span class="identifier">buffers_range</span></code></a> <a class="link" href="../ref/boost__beast__buffers_range_ref.html" title="buffers_range_ref"><code class="computeroutput"><span class="identifier">buffers_range_ref</span></code></a> 148 </p> 149 </td> 150<td> 151 <p> 152 This function returns an iterable range representing the passed 153 buffer sequence. The values obtained when iterating the range will 154 always be a constant buffer, unless the underlying buffer sequence 155 is mutable, in which case the value obtained when iterating will 156 be a mutable buffer. It is intended as a notational convenience 157 when writing a <span class="emphasis"><em>range-for</em></span> statement over a 158 buffer sequence. 159 </p> 160 <p> 161 The function <a class="link" href="../ref/boost__beast__buffers_range_ref.html" title="buffers_range_ref"><code class="computeroutput"><span class="identifier">buffers_range</span></code></a> maintains 162 a copy of the buffer sequence, while <a class="link" href="../ref/boost__beast__buffers_range_ref.html" title="buffers_range_ref"><code class="computeroutput"><span class="identifier">buffers_range_ref</span></code></a> maintains 163 a reference (in this case, the caller must ensure that the lifetime 164 of the referenced buffer sequence extends until the range object 165 is destroyed). 166 </p> 167 </td> 168</tr> 169<tr> 170<td> 171 <p> 172 <a class="link" href="../ref/boost__beast__buffers_suffix.html" title="buffers_suffix"><code class="computeroutput"><span class="identifier">buffers_suffix</span></code></a> 173 </p> 174 </td> 175<td> 176 <p> 177 This class wraps the underlying memory of an existing buffer sequence 178 and presents a suffix of the original sequence. The length of the 179 suffix may be progressively shortened. This lets callers work with 180 sequential increments of a buffer sequence. 181 </p> 182 </td> 183</tr> 184<tr> 185<td> 186 <p> 187 <a class="link" href="../ref/boost__beast__buffers_to_string.html" title="buffers_to_string"><code class="computeroutput"><span class="identifier">buffers_to_string</span></code></a> 188 </p> 189 </td> 190<td> 191 <p> 192 This function converts a buffer sequence to a <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span></code>. 193 It can be used for diagnostic purposes and tests. 194 </p> 195 </td> 196</tr> 197</tbody> 198</table></div> 199</div> 200<br class="table-break"><p> 201 The <a class="link" href="../concepts/DynamicBuffer.html" title="DynamicBuffer"><span class="emphasis"><em>DynamicBuffer</em></span></a> 202 concept introduced in <a href="../../../../../../libs/asio/index.html" target="_top">Boost.Asio</a> 203 models a buffer sequence which supports an owning, resizable range. Beast 204 provides this set of additional implementations of the dynamic buffer concept: 205 </p> 206<div class="table"> 207<a name="beast.using_io.buffer_types.dynamic_buffer_implementations"></a><p class="title"><b>Table 1.8. Dynamic Buffer Implementations</b></p> 208<div class="table-contents"><table class="table" summary="Dynamic Buffer Implementations"> 209<colgroup> 210<col> 211<col> 212</colgroup> 213<thead><tr> 214<th> 215 <p> 216 Name 217 </p> 218 </th> 219<th> 220 <p> 221 Description 222 </p> 223 </th> 224</tr></thead> 225<tbody> 226<tr> 227<td> 228 <p> 229 <a class="link" href="../ref/boost__beast__buffers_adaptor.html" title="buffers_adaptor"><code class="computeroutput"><span class="identifier">buffers_adaptor</span></code></a> 230 </p> 231 </td> 232<td> 233 <p> 234 This wrapper adapts any <a href="../../../../../../doc/html/boost_asio/reference/MutableBufferSequence.html" target="_top"><span class="emphasis"><em>MutableBufferSequence</em></span></a> 235 into a <a class="link" href="../concepts/DynamicBuffer.html" title="DynamicBuffer"><span class="emphasis"><em>DynamicBuffer</em></span></a> 236 with an upper limit on the total size of the input and output areas 237 equal to the size of the underlying mutable buffer sequence. The 238 implementation does not perform heap allocations. 239 </p> 240 </td> 241</tr> 242<tr> 243<td> 244 <p> 245 <a class="link" href="../ref/boost__beast__flat_buffer.html" title="flat_buffer"><code class="computeroutput"><span class="identifier">flat_buffer</span></code></a> <a class="link" href="../ref/boost__beast__basic_flat_buffer.html" title="basic_flat_buffer"><code class="computeroutput"><span class="identifier">basic_flat_buffer</span></code></a> 246 </p> 247 </td> 248<td> 249 <p> 250 Guarantees that input and output areas are buffer sequences with 251 length one. Upon construction an optional upper limit to the total 252 size of the input and output areas may be set. The basic container 253 is an <a href="https://en.cppreference.com/w/cpp/named_req/AllocatorAwareContainer" target="_top"><span class="bold"><strong>AllocatorAwareContainer</strong></span></a>. 254 </p> 255 </td> 256</tr> 257<tr> 258<td> 259 <p> 260 <a class="link" href="../ref/boost__beast__multi_buffer.html" title="multi_buffer"><code class="computeroutput"><span class="identifier">multi_buffer</span></code></a> <a class="link" href="../ref/boost__beast__basic_multi_buffer.html" title="basic_multi_buffer"><code class="computeroutput"><span class="identifier">basic_multi_buffer</span></code></a> 261 </p> 262 </td> 263<td> 264 <p> 265 Uses a sequence of one or more character arrays of varying sizes. 266 Additional character array objects are appended to the sequence 267 to accommodate changes in the size of the character sequence. The 268 basic container is an <a href="https://en.cppreference.com/w/cpp/named_req/AllocatorAwareContainer" target="_top"><span class="bold"><strong>AllocatorAwareContainer</strong></span></a>. 269 </p> 270 </td> 271</tr> 272<tr> 273<td> 274 <p> 275 <a class="link" href="../ref/boost__beast__flat_static_buffer.html" title="flat_static_buffer"><code class="computeroutput"><span class="identifier">flat_static_buffer</span></code></a> <a class="link" href="../ref/boost__beast__flat_static_buffer_base.html" title="flat_static_buffer_base"><code class="computeroutput"><span class="identifier">flat_static_buffer_base</span></code></a> 276 </p> 277 </td> 278<td> 279 <p> 280 Guarantees that input and output areas are buffer sequences with 281 length one. Provides the facilities of a dynamic buffer, subject 282 to an upper limit placed on the total size of the input and output 283 areas defined by a constexpr template parameter. The storage for 284 the sequences are kept in the class; the implementation does not 285 perform heap allocations. 286 </p> 287 </td> 288</tr> 289<tr> 290<td> 291 <p> 292 <a class="link" href="../ref/boost__beast__static_buffer.html" title="static_buffer"><code class="computeroutput"><span class="identifier">static_buffer</span></code></a> <a class="link" href="../ref/boost__beast__static_buffer_base.html" title="static_buffer_base"><code class="computeroutput"><span class="identifier">static_buffer_base</span></code></a> 293 </p> 294 </td> 295<td> 296 <p> 297 Provides the facilities of a circular dynamic buffer. subject to 298 an upper limit placed on the total size of the input and output 299 areas defined by a constexpr template parameter. The implementation 300 never moves memory during buffer operations. The storage for the 301 sequences are kept in the class; the implementation does not perform 302 heap allocations. 303 </p> 304 </td> 305</tr> 306</tbody> 307</table></div> 308</div> 309<br class="table-break"><p> 310 These two functions facilitate buffer interoperability with standard output 311 streams. 312 </p> 313<div class="table"> 314<a name="beast.using_io.buffer_types.buffer_output_streams"></a><p class="title"><b>Table 1.9. Buffer Output Streams</b></p> 315<div class="table-contents"><table class="table" summary="Buffer Output Streams"> 316<colgroup> 317<col> 318<col> 319</colgroup> 320<thead><tr> 321<th> 322 <p> 323 Name 324 </p> 325 </th> 326<th> 327 <p> 328 Description 329 </p> 330 </th> 331</tr></thead> 332<tbody> 333<tr> 334<td> 335 <p> 336 <a class="link" href="../ref/boost__beast__make_printable.html" title="make_printable"><code class="computeroutput"><span class="identifier">make_printable</span></code></a> 337 </p> 338 </td> 339<td> 340 <p> 341 This function wraps a <a href="../../../../../../doc/html/boost_asio/reference/ConstBufferSequence.html" target="_top"><span class="emphasis"><em>ConstBufferSequence</em></span></a> 342 so it may be used with <code class="computeroutput"><span class="keyword">operator</span><span class="special"><<</span></code> and <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">ostream</span></code>. 343 </p> 344 </td> 345</tr> 346<tr> 347<td> 348 <p> 349 <a class="link" href="../ref/boost__beast__ostream.html" title="ostream"><code class="computeroutput"><span class="identifier">ostream</span></code></a> 350 </p> 351 </td> 352<td> 353 <p> 354 This function returns a <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">ostream</span></code> 355 which wraps a dynamic buffer. Characters sent to the stream using 356 <code class="computeroutput"><span class="keyword">operator</span><span class="special"><<</span></code> 357 are stored in the dynamic buffer. 358 </p> 359 </td> 360</tr> 361</tbody> 362</table></div> 363</div> 364<br class="table-break"><p> 365 These type traits are provided to facilitate writing compile-time metafunctions 366 which operate on buffers: 367 </p> 368<div class="table"> 369<a name="beast.using_io.buffer_types.buffer_algorithms_and_types0"></a><p class="title"><b>Table 1.10. Buffer Algorithms and Types</b></p> 370<div class="table-contents"><table class="table" summary="Buffer Algorithms and Types"> 371<colgroup> 372<col> 373<col> 374</colgroup> 375<thead><tr> 376<th> 377 <p> 378 Name 379 </p> 380 </th> 381<th> 382 <p> 383 Description 384 </p> 385 </th> 386</tr></thead> 387<tbody> 388<tr> 389<td> 390 <p> 391 <a class="link" href="../ref/boost__beast__buffers_iterator_type.html" title="buffers_iterator_type"><code class="computeroutput"><span class="identifier">buffers_iterator_type</span></code></a> 392 </p> 393 </td> 394<td> 395 <p> 396 This metafunction is used to determine the type of iterator used 397 by a particular buffer sequence. 398 </p> 399 </td> 400</tr> 401<tr> 402<td> 403 <p> 404 <a class="link" href="../ref/boost__beast__buffers_type.html" title="buffers_type"><code class="computeroutput"><span class="identifier">buffers_type</span></code></a> 405 </p> 406 </td> 407<td> 408 <p> 409 This metafunction is used to determine the underlying buffer type 410 for a list of buffer sequence. The equivalent type of the alias 411 will vary depending on the template type argument. 412 </p> 413 </td> 414</tr> 415<tr> 416<td> 417 <p> 418 <a class="link" href="../ref/boost__beast__is_const_buffer_sequence.html" title="is_const_buffer_sequence"><code class="computeroutput"><span class="identifier">is_const_buffer_sequence</span></code></a> 419 </p> 420 </td> 421<td> 422 <p> 423 This metafunction is used to determine if all of the specified 424 types meet the requirements of <a href="../../../../../../doc/html/boost_asio/reference/ConstBufferSequence.html" target="_top"><span class="emphasis"><em>ConstBufferSequence</em></span></a>. 425 This type alias will be <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">true_type</span></code> 426 if each specified type meets the requirements, otherwise, this 427 type alias will be <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">false_type</span></code>. 428 </p> 429 </td> 430</tr> 431<tr> 432<td> 433 <p> 434 <a class="link" href="../ref/boost__beast__is_mutable_buffer_sequence.html" title="is_mutable_buffer_sequence"><code class="computeroutput"><span class="identifier">is_mutable_buffer_sequence</span></code></a> 435 </p> 436 </td> 437<td> 438 <p> 439 This metafunction is used to determine if all of the specified 440 types meet the requirements of <a href="../../../../../../doc/html/boost_asio/reference/MutableBufferSequence.html" target="_top"><span class="emphasis"><em>MutableBufferSequence</em></span></a>. 441 This type alias will be <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">true_type</span></code> 442 if each specified type meets the requirements, otherwise, this 443 type alias will be <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">false_type</span></code>. 444 </p> 445 </td> 446</tr> 447</tbody> 448</table></div> 449</div> 450<br class="table-break"> 451</div> 452<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> 453<td align="left"></td> 454<td align="right"><div class="copyright-footer">Copyright © 2016-2019 Vinnie 455 Falco<p> 456 Distributed under the Boost Software License, Version 1.0. (See accompanying 457 file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>) 458 </p> 459</div></td> 460</tr></table> 461<hr> 462<div class="spirit-nav"> 463<a accesskey="p" href="layered_streams/counted_stream_example.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../using_io.html"><img src="../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="files.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a> 464</div> 465</body> 466</html> 467
