1<html> 2<head> 3<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> 4<title>Dynamic buffer requirements (version 1)</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="../../boost_asio.html" title="Boost.Asio"> 8<link rel="up" href="../reference.html" title="Reference"> 9<link rel="prev" href="DynamicBuffer.html" title="Dynamic buffer requirements"> 10<link rel="next" href="DynamicBuffer_v2.html" title="Dynamic buffer requirements (version 2)"> 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="DynamicBuffer.html"><img src="../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../reference.html"><img src="../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../boost_asio.html"><img src="../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="DynamicBuffer_v2.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="boost_asio.reference.DynamicBuffer_v1"></a><a class="link" href="DynamicBuffer_v1.html" title="Dynamic buffer requirements (version 1)">Dynamic buffer 28 requirements (version 1)</a> 29</h3></div></div></div> 30<p> 31 A dynamic buffer encapsulates memory storage that may be automatically resized 32 as required, where the memory is divided into an input sequence followed 33 by an output sequence. These memory regions are internal to the dynamic buffer 34 sequence, but direct access to the elements is provided to permit them to 35 be efficiently used with I/O operations, such as the <code class="computeroutput">send</code> or 36 <code class="computeroutput">receive</code> operations of a socket. Data written to the output sequence 37 of a dynamic buffer sequence object is appended to the input sequence of 38 the same object. 39 </p> 40<p> 41 A dynamic buffer type <code class="computeroutput">X</code> shall satisfy the requirements of <code class="computeroutput">MoveConstructible</code> 42 (C++ Std, [moveconstructible]) types in addition to those listed below. 43 </p> 44<p> 45 In the table below, <code class="computeroutput">X</code> denotes a dynamic buffer class, <code class="computeroutput">x</code> 46 denotes a value of type <code class="computeroutput">X&</code>, <code class="computeroutput">x1</code> denotes values 47 of type <code class="computeroutput">const X&</code>, and <code class="computeroutput">n</code> denotes a value of 48 type <code class="computeroutput">size_t</code>, and <code class="computeroutput">u</code> denotes an identifier. 49 </p> 50<div class="table"> 51<a name="boost_asio.reference.DynamicBuffer_v1.t0"></a><p class="title"><b>Table 9. DynamicBuffer_v1 requirements</b></p> 52<div class="table-contents"><table class="table" summary="DynamicBuffer_v1 requirements"> 53<colgroup> 54<col> 55<col> 56<col> 57</colgroup> 58<thead><tr> 59<th> 60 <p> 61 expression 62 </p> 63 </th> 64<th> 65 <p> 66 type 67 </p> 68 </th> 69<th> 70 <p> 71 assertion/note<br> pre/post-conditions 72 </p> 73 </th> 74</tr></thead> 75<tbody> 76<tr> 77<td> 78 <p> 79 <code class="computeroutput">X::const_buffers_type</code> 80 </p> 81 </td> 82<td> 83 <p> 84 type meeting <a class="link" href="ConstBufferSequence.html" title="Constant buffer sequence requirements">ConstBufferSequence</a> 85 requirements. 86 </p> 87 </td> 88<td> 89 <p> 90 This type represents the memory associated with the input sequence. 91 </p> 92 </td> 93</tr> 94<tr> 95<td> 96 <p> 97 <code class="computeroutput">X::mutable_buffers_type</code> 98 </p> 99 </td> 100<td> 101 <p> 102 type meeting <a class="link" href="MutableBufferSequence.html" title="Mutable buffer sequence requirements">MutableBufferSequence</a> 103 requirements. 104 </p> 105 </td> 106<td> 107 <p> 108 This type represents the memory associated with the output sequence. 109 </p> 110 </td> 111</tr> 112<tr> 113<td> 114 <p> 115 <code class="computeroutput">x1.size()</code> 116 </p> 117 </td> 118<td> 119 <p> 120 <code class="computeroutput">size_t</code> 121 </p> 122 </td> 123<td> 124 <p> 125 Returns the size, in bytes, of the input sequence. 126 </p> 127 </td> 128</tr> 129<tr> 130<td> 131 <p> 132 <code class="computeroutput">x1.max_size()</code> 133 </p> 134 </td> 135<td> 136 <p> 137 <code class="computeroutput">size_t</code> 138 </p> 139 </td> 140<td> 141 <p> 142 Returns the permitted maximum of the sum of the sizes of the input 143 sequence and output sequence. 144 </p> 145 </td> 146</tr> 147<tr> 148<td> 149 <p> 150 <code class="computeroutput">x1.capacity()</code> 151 </p> 152 </td> 153<td> 154 <p> 155 <code class="computeroutput">size_t</code> 156 </p> 157 </td> 158<td> 159 <p> 160 Returns the maximum sum of the sizes of the input sequence and 161 output sequence that the dynamic buffer can hold without requiring 162 reallocation. 163 </p> 164 </td> 165</tr> 166<tr> 167<td> 168 <p> 169 <code class="computeroutput">x1.data()</code> 170 </p> 171 </td> 172<td> 173 <p> 174 <code class="computeroutput">X::const_buffers_type</code> 175 </p> 176 </td> 177<td> 178 <p> 179 Returns a constant buffer sequence <code class="computeroutput">u</code> that represents 180 the memory associated with the input sequence, and where <code class="computeroutput">buffer_size(u) 181 == size()</code>. 182 </p> 183 </td> 184</tr> 185<tr> 186<td> 187 <p> 188 <code class="computeroutput">x.prepare(n)</code> 189 </p> 190 </td> 191<td> 192 <p> 193 <code class="computeroutput">X::mutable_buffers_type</code> 194 </p> 195 </td> 196<td> 197 <p> 198 Requires: <code class="computeroutput">size() + n <= max_size()</code>.<br> <br> 199 Returns a mutable buffer sequence <code class="computeroutput">u</code> representing the 200 output sequence, and where <code class="computeroutput">buffer_size(u) == n</code>. The 201 dynamic buffer reallocates memory as required. All constant or 202 mutable buffer sequences previously obtained using <code class="computeroutput">data()</code> 203 or <code class="computeroutput">prepare()</code> are invalidated.<br> <br> Throws: 204 <code class="computeroutput">length_error</code> if <code class="computeroutput">size() + n > max_size()</code>. 205 </p> 206 </td> 207</tr> 208<tr> 209<td> 210 <p> 211 <code class="computeroutput">x.commit(n)</code> 212 </p> 213 </td> 214<td> 215 </td> 216<td> 217 <p> 218 Appends <code class="computeroutput">n</code> bytes from the start of the output sequence 219 to the end of the input sequence. The remainder of the output sequence 220 is discarded. If <code class="computeroutput">n</code> is greater than the size of the 221 output sequence, the entire output sequence is appended to the 222 input sequence. All constant or mutable buffer sequences previously 223 obtained using <code class="computeroutput">data()</code> or <code class="computeroutput">prepare()</code> are 224 invalidated. 225 </p> 226 </td> 227</tr> 228<tr> 229<td> 230 <p> 231 <code class="computeroutput">x.consume(n)</code> 232 </p> 233 </td> 234<td> 235 </td> 236<td> 237 <p> 238 Removes <code class="computeroutput">n</code> bytes from beginning of the input sequence. 239 If <code class="computeroutput">n</code> is greater than the size of the input sequence, 240 the entire input sequence is removed. All constant or mutable buffer 241 sequences previously obtained using <code class="computeroutput">data()</code> or <code class="computeroutput">prepare()</code> 242 are invalidated. 243 </p> 244 </td> 245</tr> 246</tbody> 247</table></div> 248</div> 249<br class="table-break"> 250</div> 251<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> 252<td align="left"></td> 253<td align="right"><div class="copyright-footer">Copyright © 2003-2020 Christopher M. 254 Kohlhoff<p> 255 Distributed under the Boost Software License, Version 1.0. (See accompanying 256 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>) 257 </p> 258</div></td> 259</tr></table> 260<hr> 261<div class="spirit-nav"> 262<a accesskey="p" href="DynamicBuffer.html"><img src="../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../reference.html"><img src="../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../boost_asio.html"><img src="../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="DynamicBuffer_v2.html"><img src="../../../../doc/src/images/next.png" alt="Next"></a> 263</div> 264</body> 265</html> 266
