1<html> 2<head> 3<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> 4<title>streambuf</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="strand/_strand.html" title="strand::~strand"> 10<link rel="next" href="system_context.html" title="system_context"> 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="strand/_strand.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="system_context.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.streambuf"></a><a class="link" href="streambuf.html" title="streambuf">streambuf</a> 28</h3></div></div></div> 29<p> 30 <a class="indexterm" name="boost_asio.indexterm.streambuf"></a> 31Typedef for the typical usage of 32 <a class="link" href="basic_streambuf.html" title="basic_streambuf"><code class="computeroutput">basic_streambuf</code></a>. 33 </p> 34<pre class="programlisting">typedef basic_streambuf streambuf; 35</pre> 36<h5> 37<a name="boost_asio.reference.streambuf.h0"></a> 38 <span class="phrase"><a name="boost_asio.reference.streambuf.types"></a></span><a class="link" href="streambuf.html#boost_asio.reference.streambuf.types">Types</a> 39 </h5> 40<div class="informaltable"><table class="table"> 41<colgroup> 42<col> 43<col> 44</colgroup> 45<thead><tr> 46<th> 47 <p> 48 Name 49 </p> 50 </th> 51<th> 52 <p> 53 Description 54 </p> 55 </th> 56</tr></thead> 57<tbody> 58<tr> 59<td> 60 <p> 61 <a class="link" href="basic_streambuf/const_buffers_type.html" title="basic_streambuf::const_buffers_type"><span class="bold"><strong>const_buffers_type</strong></span></a> 62 </p> 63 </td> 64<td> 65 <p> 66 The type used to represent the input sequence as a list of buffers. 67 </p> 68 </td> 69</tr> 70<tr> 71<td> 72 <p> 73 <a class="link" href="basic_streambuf/mutable_buffers_type.html" title="basic_streambuf::mutable_buffers_type"><span class="bold"><strong>mutable_buffers_type</strong></span></a> 74 </p> 75 </td> 76<td> 77 <p> 78 The type used to represent the output sequence as a list of buffers. 79 </p> 80 </td> 81</tr> 82</tbody> 83</table></div> 84<h5> 85<a name="boost_asio.reference.streambuf.h1"></a> 86 <span class="phrase"><a name="boost_asio.reference.streambuf.member_functions"></a></span><a class="link" href="streambuf.html#boost_asio.reference.streambuf.member_functions">Member 87 Functions</a> 88 </h5> 89<div class="informaltable"><table class="table"> 90<colgroup> 91<col> 92<col> 93</colgroup> 94<thead><tr> 95<th> 96 <p> 97 Name 98 </p> 99 </th> 100<th> 101 <p> 102 Description 103 </p> 104 </th> 105</tr></thead> 106<tbody> 107<tr> 108<td> 109 <p> 110 <a class="link" href="basic_streambuf/basic_streambuf.html" title="basic_streambuf::basic_streambuf"><span class="bold"><strong>basic_streambuf</strong></span></a> <span class="silver">[constructor]</span> 111 </p> 112 </td> 113<td> 114 <p> 115 Construct a basic_streambuf object. 116 </p> 117 </td> 118</tr> 119<tr> 120<td> 121 <p> 122 <a class="link" href="basic_streambuf/capacity.html" title="basic_streambuf::capacity"><span class="bold"><strong>capacity</strong></span></a> 123 </p> 124 </td> 125<td> 126 <p> 127 Get the current capacity of the basic_streambuf. 128 </p> 129 </td> 130</tr> 131<tr> 132<td> 133 <p> 134 <a class="link" href="basic_streambuf/commit.html" title="basic_streambuf::commit"><span class="bold"><strong>commit</strong></span></a> 135 </p> 136 </td> 137<td> 138 <p> 139 Move characters from the output sequence to the input sequence. 140 </p> 141 </td> 142</tr> 143<tr> 144<td> 145 <p> 146 <a class="link" href="basic_streambuf/consume.html" title="basic_streambuf::consume"><span class="bold"><strong>consume</strong></span></a> 147 </p> 148 </td> 149<td> 150 <p> 151 Remove characters from the input sequence. 152 </p> 153 </td> 154</tr> 155<tr> 156<td> 157 <p> 158 <a class="link" href="basic_streambuf/data.html" title="basic_streambuf::data"><span class="bold"><strong>data</strong></span></a> 159 </p> 160 </td> 161<td> 162 <p> 163 Get a list of buffers that represents the input sequence. 164 </p> 165 </td> 166</tr> 167<tr> 168<td> 169 <p> 170 <a class="link" href="basic_streambuf/max_size.html" title="basic_streambuf::max_size"><span class="bold"><strong>max_size</strong></span></a> 171 </p> 172 </td> 173<td> 174 <p> 175 Get the maximum size of the basic_streambuf. 176 </p> 177 </td> 178</tr> 179<tr> 180<td> 181 <p> 182 <a class="link" href="basic_streambuf/prepare.html" title="basic_streambuf::prepare"><span class="bold"><strong>prepare</strong></span></a> 183 </p> 184 </td> 185<td> 186 <p> 187 Get a list of buffers that represents the output sequence, with 188 the given size. 189 </p> 190 </td> 191</tr> 192<tr> 193<td> 194 <p> 195 <a class="link" href="basic_streambuf/size.html" title="basic_streambuf::size"><span class="bold"><strong>size</strong></span></a> 196 </p> 197 </td> 198<td> 199 <p> 200 Get the size of the input sequence. 201 </p> 202 </td> 203</tr> 204</tbody> 205</table></div> 206<h5> 207<a name="boost_asio.reference.streambuf.h2"></a> 208 <span class="phrase"><a name="boost_asio.reference.streambuf.protected_member_functions"></a></span><a class="link" href="streambuf.html#boost_asio.reference.streambuf.protected_member_functions">Protected 209 Member Functions</a> 210 </h5> 211<div class="informaltable"><table class="table"> 212<colgroup> 213<col> 214<col> 215</colgroup> 216<thead><tr> 217<th> 218 <p> 219 Name 220 </p> 221 </th> 222<th> 223 <p> 224 Description 225 </p> 226 </th> 227</tr></thead> 228<tbody> 229<tr> 230<td> 231 <p> 232 <a class="link" href="basic_streambuf/overflow.html" title="basic_streambuf::overflow"><span class="bold"><strong>overflow</strong></span></a> 233 </p> 234 </td> 235<td> 236 <p> 237 Override std::streambuf behaviour. 238 </p> 239 </td> 240</tr> 241<tr> 242<td> 243 <p> 244 <a class="link" href="basic_streambuf/reserve.html" title="basic_streambuf::reserve"><span class="bold"><strong>reserve</strong></span></a> 245 </p> 246 </td> 247<td> 248 </td> 249</tr> 250<tr> 251<td> 252 <p> 253 <a class="link" href="basic_streambuf/underflow.html" title="basic_streambuf::underflow"><span class="bold"><strong>underflow</strong></span></a> 254 </p> 255 </td> 256<td> 257 <p> 258 Override std::streambuf behaviour. 259 </p> 260 </td> 261</tr> 262</tbody> 263</table></div> 264<p> 265 The <code class="computeroutput">basic_streambuf</code> class is derived from <code class="computeroutput">std::streambuf</code> 266 to associate the streambuf's input and output sequences with one or more 267 character arrays. These character arrays are internal to the <code class="computeroutput">basic_streambuf</code> 268 object, but direct access to the array elements is provided to permit them 269 to be used efficiently with I/O operations. Characters written to the output 270 sequence of a <code class="computeroutput">basic_streambuf</code> object are appended to the input 271 sequence of the same object. 272 </p> 273<p> 274 The <code class="computeroutput">basic_streambuf</code> class's public interface is intended to 275 permit the following implementation strategies: 276 </p> 277<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 278<li class="listitem"> 279 A single contiguous character array, which is reallocated as necessary 280 to accommodate changes in the size of the character sequence. This is 281 the implementation approach currently used in Asio. 282 </li> 283<li class="listitem"> 284 A sequence of one or more character arrays, where each array is of the 285 same size. Additional character array objects are appended to the sequence 286 to accommodate changes in the size of the character sequence. 287 </li> 288<li class="listitem"> 289 A sequence of one or more character arrays of varying sizes. Additional 290 character array objects are appended to the sequence to accommodate changes 291 in the size of the character sequence. 292 </li> 293</ul></div> 294<p> 295 The constructor for <a class="link" href="basic_streambuf.html" title="basic_streambuf"><code class="computeroutput">basic_streambuf</code></a> 296 accepts a <code class="computeroutput">size_t</code> argument specifying the maximum of the sum 297 of the sizes of the input sequence and output sequence. During the lifetime 298 of the <code class="computeroutput">basic_streambuf</code> object, the following invariant holds: 299 </p> 300<pre class="programlisting">size() <= max_size() 301</pre> 302<p> 303 Any member function that would, if successful, cause the invariant to be 304 violated shall throw an exception of class <code class="computeroutput">std::length_error</code>. 305 </p> 306<p> 307 The constructor for <code class="computeroutput">basic_streambuf</code> takes an Allocator argument. 308 A copy of this argument is used for any memory allocation performed, by the 309 constructor and by all member functions, during the lifetime of each <code class="computeroutput">basic_streambuf</code> 310 object. 311 </p> 312<h5> 313<a name="boost_asio.reference.streambuf.h3"></a> 314 <span class="phrase"><a name="boost_asio.reference.streambuf.examples"></a></span><a class="link" href="streambuf.html#boost_asio.reference.streambuf.examples">Examples</a> 315 </h5> 316<p> 317 Writing directly from an streambuf to a socket: 318 </p> 319<pre class="programlisting">boost::asio::streambuf b; 320std::ostream os(&b); 321os << "Hello, World!\n"; 322 323// try sending some data in input sequence 324size_t n = sock.send(b.data()); 325 326b.consume(n); // sent data is removed from input sequence 327</pre> 328<p> 329 Reading from a socket directly into a streambuf: 330 </p> 331<pre class="programlisting">boost::asio::streambuf b; 332 333// reserve 512 bytes in output sequence 334boost::asio::streambuf::mutable_buffers_type bufs = b.prepare(512); 335 336size_t n = sock.receive(bufs); 337 338// received data is "committed" from output sequence to input sequence 339b.commit(n); 340 341std::istream is(&b); 342std::string s; 343is >> s; 344</pre> 345<h5> 346<a name="boost_asio.reference.streambuf.h4"></a> 347 <span class="phrase"><a name="boost_asio.reference.streambuf.requirements"></a></span><a class="link" href="streambuf.html#boost_asio.reference.streambuf.requirements">Requirements</a> 348 </h5> 349<p> 350 <span class="emphasis"><em>Header: </em></span><code class="literal">boost/asio/streambuf.hpp</code> 351 </p> 352<p> 353 <span class="emphasis"><em>Convenience header: </em></span><code class="literal">boost/asio.hpp</code> 354 </p> 355</div> 356<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> 357<td align="left"></td> 358<td align="right"><div class="copyright-footer">Copyright © 2003-2020 Christopher M. 359 Kohlhoff<p> 360 Distributed under the Boost Software License, Version 1.0. (See accompanying 361 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>) 362 </p> 363</div></td> 364</tr></table> 365<hr> 366<div class="spirit-nav"> 367<a accesskey="p" href="strand/_strand.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="system_context.html"><img src="../../../../doc/src/images/next.png" alt="Next"></a> 368</div> 369</body> 370</html> 371
