1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> 2<HTML> 3<HEAD> 4 <TITLE>Generic Streams and Stream Buffers</TITLE> 5 <LINK REL="stylesheet" href="../../../../boost.css"> 6 <LINK REL="stylesheet" href="../theme/iostreams.css"> 7 <STYLE>PRE { font-size: 80% }</STYLE> 8</HEAD> 9<BODY> 10 11<!-- Begin Banner --> 12 13 <H1 CLASS="title">User's Guide</H1> 14 <HR CLASS="banner"> 15 16<!-- End Banner --> 17 18<!-- Begin Nav --> 19 20<DIV CLASS='nav'> 21 <A HREF='modes.html'><IMG BORDER=0 WIDTH=19 HEIGHT=19 SRC='../../../../doc/src/images/prev.png'></A> 22 <A HREF='guide.html'><IMG BORDER=0 WIDTH=19 HEIGHT=19 SRC='../../../../doc/src/images/up.png'></A> 23 <A HREF='filtering_streams.html'><IMG BORDER=0 WIDTH=19 HEIGHT=19 SRC='../../../../doc/src/images/next.png'></A> 24</DIV> 25 26<!-- End Nav --> 27 28<H2>3.3 Generic Streams and Stream Buffers</H2> 29 30<DL class="page-index"> 31 <DT><A href="#overview">Overview</A></DT> 32 <DT><A href="#headers">Headers</A></DT> 33 <DT><A href="#reference">Reference</A> 34 <DL> 35 <DT><A href="#stream_buffer">Class template <CODE>stream_buffer</CODE></A></DT> 36 <DT><A href="#stream">Class template <CODE>stream</CODE></A></DT> 37 </DL> 38 </DT> 39 <DT><A href="#examples">Examples</A></DT> 40</DL> 41 42<HR STYLE="margin-top:1em"> 43 44<A NAME="overview"></A> 45<H2>Overview</H2> 46 47<P> 48 The fundamental component provided by the Iostreams library is the class template <CODE>stream_buffer</CODE>, a derived class of <CODE>std::basic_streambuf</CODE> which performs i/o by delegating to a contained Device. Instances of the Device can be associated and disassociated with an instance of <CODE>stream_buffer</CODE> using member functions <CODE><A HREF="#stream_buffer_open">open</A></CODE> and <CODE><A HREF="#stream_buffer_close">close</A></CODE>. The interface is patterned after <CODE>std::basic_filebuf</CODE> and <CODE>std::basic_fstream</CODE>. 49</P> 50 51<P> 52 The class template <CODE>stream</CODE> is a stream template which derives from one of <CODE>std::basic_istream</CODE>, <CODE>std::basic_ostream</CODE> and <CODE>std::basic_iostream</CODE> depending on the <A href="modes.html">mode</A> of the first template parameter. As with <CODE>stream_buffer</CODE>, instances of the Device can by associated and disassociated with an instance of <CODE>stream</CODE> using its member functions <CODE><A HREF="#stream_open">open</A></CODE> and <CODE><A HREF="#stream_close">close</A></CODE>. 53</P> 54 55 56<A NAME="headers"></A> 57<H2>Headers</H2> 58 59<DL class="page-index"> 60 <DT><A CLASS="header" href="../../../../boost/iostreams/stream_buffer.hpp"><CODE><boost/iostreams/stream_buffer.hpp></CODE></A></DT> 61 <DT><A CLASS="header" href="../../../../boost/iostreams/stream.hpp"><CODE><boost/iostreams/stream.hpp></CODE></A></DT> 62</DL> 63 64<A NAME="reference"></A> 65<H2>Reference</H2> 66 67<A NAME="stream_buffer"></A> 68<H3>Class template <CODE>stream_buffer</CODE></H3> 69 70<H4>Description</H4> 71 72<P> 73 Stream buffer template which performs i/o by delegating to a contained <A HREF="../concepts/device.html">Device</A>. The Device type is specified as the first template parameter to <CODE>stream_buffer</CODE>. Instances of the the Device type are attached and detached using the member functions <A HREF="#stream_buffer_open"><CODE>open</CODE></A> and <A HREF="#stream_buffer_close"><CODE>close</CODE></A>. 74</P> 75 76<H4>Synopsis</H4> 77 78<PRE><SPAN CLASS="keyword">namespace</SPAN> boost { <SPAN CLASS="keyword">namespace</SPAN> iostreams { 79 80<SPAN CLASS="keyword">template</SPAN>< <SPAN CLASS="keyword">typename</SPAN> <A CLASS="documented" HREF="#stream_buffer_params">T</A>, 81 <SPAN CLASS="keyword">typename</SPAN> <A CLASS="documented" HREF="#stream_buffer_params">Tr</A> = std::char_traits<<SPAN CLASS="omitted">...</SPAN>>, 82 <SPAN CLASS="keyword">typename</SPAN> <A CLASS="documented" HREF="#stream_buffer_params">Alloc</A> = std::allocator<<SPAN CLASS="omitted">...</SPAN>>, 83 <SPAN CLASS="keyword">typename</SPAN> <A CLASS="documented" HREF="#stream_buffer_params">Mode</A> = <SPAN CLASS="omitted">...</SPAN> > 84<SPAN CLASS="keyword">class</SPAN> <A CLASS="documented" HREF="#stream_buffer_params">stream_buffer</A> : <SPAN CLASS="keyword">public</SPAN> std::basic_streambuf<<SPAN CLASS="omitted">...</SPAN>> { 85<SPAN CLASS="keyword">public</SPAN>: 86 <SPAN CLASS="keyword">typedef</SPAN> <SPAN CLASS="keyword">typename</SPAN> char_type_of<T>::type char_type; 87 <SPAN CLASS="keyword">typedef</SPAN> <SPAN CLASS="keyword">typename</SPAN> Tr traits_type; 88 89 [<SPAN CLASS="omitted">Standard stream buffer typedefs: int_type, off_type, etc.</SPAN>] 90 91 <A CLASS="documented" HREF="#stream_buffer_default_constructor">stream_buffer</A>(); 92 <A CLASS="documented" HREF="#stream_buffer_policy_constructor">stream_buffer</A>( <SPAN CLASS="keyword">const</SPAN> T& t, 93 std::streamsize buffer_size = <SPAN CLASS="omitted">default_value</SPAN>, 94 std::streamsize pback_size = <SPAN CLASS="omitted">default_value</SPAN> ); 95 96 <SPAN CLASS="comment">// Forwarding constructors</SPAN> 97 98 <SPAN CLASS="keyword">template</SPAN><<SPAN CLASS="keyword">typename</SPAN> U> 99 <A CLASS="documented" HREF="#stream_buffer_forwarding_constructors">stream_buffer</A>([<SPAN CLASS="keyword">const</SPAN>] U& u); 100 101 <SPAN CLASS="keyword">template</SPAN><<SPAN CLASS="keyword">typename</SPAN> U1, <SPAN CLASS="keyword">typename</SPAN> U2> 102 <A CLASS="documented" HREF="#stream_buffer_forwarding_constructors">stream_buffer</A>([<SPAN CLASS="keyword">const</SPAN>] U1& u1, <SPAN CLASS="keyword">const</SPAN> U2& u2); 103 104 <SPAN CLASS="omitted">...</SPAN> 105 106 <SPAN CLASS="keyword">template</SPAN><<SPAN CLASS="keyword">typename</SPAN> U1, <SPAN CLASS="omitted">...</SPAN>, <SPAN CLASS="keyword">typename</SPAN> UN> 107 <A CLASS="documented" HREF="#stream_buffer_forwarding_constructors">stream_buffer</A>([<SPAN CLASS="keyword">const</SPAN>] U1& u1, <SPAN CLASS="keyword">const</SPAN> U2& u2 <SPAN CLASS="omitted">...</SPAN>, <SPAN CLASS="keyword">const</SPAN> UN& uN); 108 109 <SPAN CLASS="keyword">void</SPAN> <A CLASS="documented" HREF="#stream_buffer_open">open</A>( <SPAN CLASS="keyword">const</SPAN> T& t, 110 std::streamsize buffer_size = <SPAN CLASS="omitted">default_value</SPAN>, 111 std::streamsize pback_size = <SPAN CLASS="omitted">default_value</SPAN> ); 112 113 <SPAN CLASS="comment">// Forwarding overloads of open()</SPAN> 114 115 <SPAN CLASS="keyword">template</SPAN><<SPAN CLASS="keyword">typename</SPAN> U> 116 <SPAN CLASS="keyword">void</SPAN> <A CLASS="documented" HREF="#stream_buffer_forwarding_open">open</A>([<SPAN CLASS="keyword">const</SPAN>] U& u); 117 118 <SPAN CLASS="keyword">template</SPAN><<SPAN CLASS="keyword">typename</SPAN> U1, <SPAN CLASS="keyword">typename</SPAN> U2> 119 <SPAN CLASS="keyword">void</SPAN> <A CLASS="documented" HREF="#stream_buffer_forwarding_open">open</A>([<SPAN CLASS="keyword">const</SPAN>] U1& u1, <SPAN CLASS="keyword">const</SPAN> U2& u2); 120 121 <SPAN CLASS="omitted">...</SPAN> 122 123 <SPAN CLASS="keyword">template</SPAN><<SPAN CLASS="keyword">typename</SPAN> U1, <SPAN CLASS="omitted">...</SPAN>, <SPAN CLASS="keyword">typename</SPAN> UN> 124 <SPAN CLASS="keyword">void</SPAN> <A CLASS="documented" HREF="#stream_buffer_forwarding_open">open</A>([<SPAN CLASS="keyword">const</SPAN>] U1& u1, <SPAN CLASS="keyword">const</SPAN> U2& u2, <SPAN CLASS="omitted">...</SPAN>, <SPAN CLASS="keyword">const</SPAN> UN& uN); 125 126 <SPAN CLASS="keyword">bool</SPAN> <A CLASS="documented" HREF="#stream_buffer_is_open">is_open</A>() <SPAN CLASS="keyword">const</SPAN>; 127 <SPAN CLASS="keyword">void</SPAN> <A CLASS="documented" HREF="#stream_buffer_close">close</A>(); 128 129 <SPAN CLASS="comment">// Device access</SPAN> 130 131 T& <A CLASS='documented' HREF="#stream_buffer_operator_star"><SPAN CLASS="documented">operator</SPAN>*</A>(); 132 T* <A CLASS='documented' HREF="#stream_buffer_operator_arrow"><SPAN CLASS="documented">operator-></SPAN></A>(); 133}; 134 135} } <SPAN CLASS="comment">// namespace boost::io</SPAN></PRE> 136 137<A NAME="stream_buffer_params"></A> 138<H4>Template parameters</H4> 139 140<TABLE STYLE="margin-left:2em" BORDER=0 CELLPADDING=2> 141<TR> 142 <TR> 143 <TD VALIGN="top"><I>T</I></TD><TD WIDTH="2em" VALIGN="top">-</TD> 144 <TD>A <A HREF="../../../../doc/html/CopyConstructible.html" TARGET="_top">CopyConstructible</A> model of one of the <A HREF="concepts.html#device_concepts">Device</A> concepts.</TD> 145 </TR> 146 <TR> 147 <TD VALIGN="top"><I>Tr</I></TD><TD WIDTH="2em" VALIGN="top">-</TD> 148 <TD>A C++ standard library charatcer traits type (<A CLASS="bib_ref" href="../bibliography.html#iso">[ISO]</A>, 21.1.1) with <CODE>char_type</CODE> equal to the <A HREF="traits.html#char_type">character type</A> <CODE>Ch</CODE> of T. Defaults to <CODE>std::char_traits<Ch></CODE>.</TD> 149 </TR> 150 <TR> 151 <TD VALIGN="top"><I>Alloc</I></TD><TD WIDTH="2em" VALIGN="top">-</TD> 152 <TD>A C++ standard library allocator type (<A CLASS="bib_ref" href="../bibliography.html#iso">[ISO]</A>, 20.1.5), used to allocate any required character buffers. Defaults to <CODE>std::allocator<Ch></CODE>, where <CODE>Ch</CODE> is the <A HREF="traits.html#char_type">character type</A> of T.</TD> 153 </TR> 154 <TR> 155 <TD VALIGN="top"><I>Mode</I></TD><TD WIDTH="2em" VALIGN="top">-</TD> 156 <TD>A mode tag <I>convertible to the <A HREF="modes.html">mode</A> of T</I>. This parameter is principally for internal use. Specifying a <A HREF="modes.html#mode_tags">mode tag</A> properly refined by the mode of T can prevent an unneeded buffer from being allocated in some cases. Defaults to the mode of T.</TD> 157 </TR> 158</TABLE> 159 160<H4><CODE>stream_buffer::stream_buffer</CODE></H4> 161 162<A NAME="stream_buffer_default_constructor"></A> 163<PRE> <B>stream_buffer</B>();</PRE> 164 165<P> 166 Constructs a <CODE>stream_buffer</CODE> with no associated instance of the Device <CODE>T</CODE>. Before the instance can be used for i/o, one of its <CODE>open()</CODE> overloads must be invoked. 167</P> 168 169<H4><CODE>stream_buffer::stream_buffer</CODE></H4> 170 171<A NAME="stream_buffer_policy_constructor"></A> 172<PRE> <B>stream_buffer</B>( <SPAN CLASS="keyword">const</SPAN> T& t, 173 std::streamsize buffer_size, 174 std::streamsize pback_size );</PRE> 175 176<P> 177 Constructs a <CODE>stream_buffer</CODE> which is ready to perform i/o, where the parameters have the following interpretations: 178 179<TABLE STYLE="margin-left:2em" BORDER=0 CELLPADDING=2> 180<TR> 181 <TR> 182 <TD VALIGN="top"><I>t</I></TD><TD WIDTH="2em" VALIGN="top">-</TD> 183 <TD>An instance of T</TD> 184 </TR> 185 <TR> 186 <TD VALIGN="top"><I>buffer_size</I></TD><TD WIDTH="2em" VALIGN="top">-</TD> 187 <TD>The size of any buffers that need to be allocated</TD> 188 </TR> 189 <TR> 190 <TD VALIGN="top"><I>pback_size</I></TD><TD WIDTH="2em" VALIGN="top">-</TD> 191 <TD>The size of the putback buffer, relevant only if <CODE>Mode</CODE> is a refinement of <A HREF="modes.html#input"><CODE>input</CODE></TD> 192 </TR> 193</TABLE> 194 195<A NAME="stream_buffer_forwarding_constructors"></A> 196<PRE> <SPAN CLASS="keyword">template</SPAN><<SPAN CLASS="keyword">typename</SPAN> U> 197 <B>stream_buffer</B>([<SPAN CLASS="keyword">const</SPAN>] U& u); 198 199 <SPAN CLASS="keyword">template</SPAN><<SPAN CLASS="keyword">typename</SPAN> U1, <SPAN CLASS="keyword">typename</SPAN> U2> 200 <B>stream_buffer</B>([<SPAN CLASS="keyword">const</SPAN>] U1& u1, <SPAN CLASS="keyword">const</SPAN> U2& u2); 201 202 <SPAN CLASS="omitted">...</SPAN> 203 204 template<<SPAN CLASS="keyword">typename</SPAN> U1, <SPAN CLASS="omitted">...</SPAN>, <SPAN CLASS="keyword">typename</SPAN> UN> 205 <B>stream_buffer</B>([<SPAN CLASS="keyword">const</SPAN>] U1& u1, <SPAN CLASS="keyword">const</SPAN> U2& u2, <SPAN CLASS="omitted">...</SPAN>, <SPAN CLASS="keyword">const</SPAN> UN& uN);</PRE> 206 207<P> 208 Each of these members constructs an instance of <CODE>stream_buffer</CODE> and associates it with an instance of the Device <CODE>T</CODE> constructed from the given lists of arguments. The <CODE>T</CODE> constructor must take all arguments other than the first by value or <CODE>const</CODE> reference. 209</P> 210<P> 211 It is not possible to specify a custom buffer size or putback buffer size using these constructors. 212</P> 213 214<H4><CODE>stream_buffer::open</CODE></H4> 215 216<A NAME="stream_buffer_open"></A> 217<PRE> void <B>open</B>( <SPAN CLASS="keyword">const</SPAN> T& t, 218 std::streamsize buffer_size, 219 std::streamsize pback_size );</PRE> 220 221<P> 222 Assocaites the given instance of <CODE>T</CODE> with <CODE>this</CODE> instance of <CODE>stream_buffer</CODE>, if there is no such instance currently associated; otherwise, throws <CODE>std::ios_base::failure</CODE>. The second parameter determines the size of any buffers that need to be allocated; a value of zero indicates that i/o should be unbuffered. The third parameter determines the size of the putback buffer; it is relevant only if <CODE>Mode</CODE> is a refinement of <A HREF="modes.html#input"><CODE>input</CODE></A>. 223</P> 224 225<A NAME="stream_buffer_forwarding_open"></A> 226<PRE> <SPAN CLASS="keyword">template</SPAN><<SPAN CLASS="keyword">typename</SPAN> U> 227 <SPAN CLASS="keyword">void</SPAN> <B>open</B>(<SPAN CLASS="keyword">const</SPAN> U& u); 228 229 <SPAN CLASS="keyword">template</SPAN><<SPAN CLASS="keyword">typename</SPAN> U1, <SPAN CLASS="keyword">typename</SPAN> U2> 230 <SPAN CLASS="keyword">void</SPAN> <B>open</B>(<SPAN CLASS="keyword">const</SPAN> U1& u1, <SPAN CLASS="keyword">const</SPAN> U2& u2); 231 232 <SPAN CLASS="omitted">...</SPAN> 233 234 template<<SPAN CLASS="keyword">typename</SPAN> U1, <SPAN CLASS="omitted">...</SPAN>, <SPAN CLASS="keyword">typename</SPAN> UN> 235 <SPAN CLASS="keyword">void</SPAN> <B>open</B>(<SPAN CLASS="keyword">const</SPAN> U1& u1, <SPAN CLASS="omitted">...</SPAN>, <SPAN CLASS="keyword">const</SPAN> UN& uN);</PRE> 236 237<P> 238 Each of these members associates with <CODE>this</CODE> instance of <CODE>stream_buffer</CODE> a newly constructed instance of the Device <CODE>T</CODE> constructed from the given lists of arguments, if there is no such instance currently associated; otherwise, they throw <CODE>std::ios_base::failure</CODE>. The <CODE>T</CODE> constructor must take all arguments other than the first by value or <CODE>const</CODE> reference. 239</P> 240<P> 241 It is not possible to specify a custom buffer size or putback buffer size using these members. 242</P> 243 244<A NAME="stream_buffer_is_open"></A> 245<H4><CODE>stream_buffer::is_open</CODE></H4> 246<PRE> <SPAN CLASS="keyword">bool</SPAN> <B>is_open</B>() <SPAN CLASS="keyword">const</SPAN>;</PRE> 247 248<P>Returns true if there is an instance of the Device <CODE>T</CODE> associated with <CODE>this</CODE> instance of <CODE>stream_buffer</CODE>.</P> 249 250<A NAME="stream_buffer_close"></A> 251<H4><CODE>stream_buffer::close</CODE></H4> 252<PRE> <SPAN CLASS="keyword">void</SPAN> <B>close</B>();</PRE> 253 254<P> 255 Disassociates from <CODE>this</CODE> instance of <CODE>stream_buffer</CODE> any instance of the Device <CODE>T</CODE> currently associated with it, calling cleanup functions as appropriate and destroying the associated instance of <CODE>T</CODE>. 256</P> 257 258<A NAME="stream_buffer_operator_star"></A> 259<H4><CODE>stream_buffer::operator*</CODE></H4> 260<PRE> T& <B>operator*</B>();</PRE> 261 262<P> 263 Returns a reference to the instance of <CODE>T</CODE> associated with this <CODE>stream_buffer</CODE>, which must be <A HREF="#stream_buffer_is_open"><CODE>open</CODE></A>. 264</P> 265 266<A NAME="stream_buffer_operator_arrow"></A> 267<H4><CODE>stream_buffer::operator-></CODE></H4> 268<PRE> T* <B>operator-></B>();</PRE> 269 270<P> 271 Returns a pointer to the instance of <CODE>T</CODE> associated with this <CODE>stream_buffer</CODE>, which must be <A HREF="#stream_buffer_is_open"><CODE>open</CODE></A>. 272</P> 273 274<A NAME="stream"></A> 275<H3>Class template <CODE>stream</CODE></H3> 276 277<H4>Description</H4> 278 279<P> 280 Stream template which performs i/o by delegating to a contained <A HREF="../concepts/device.html">Device</A>. The Device type is specified as the first template parameter to <CODE>stream</CODE>. Instances of the the Device type are attached and detached using the member functions <A HREF="#stream_open"><CODE>open</CODE></A> and <A HREF="#stream_close"><CODE>close</CODE></A>. 281</P> 282 283<P> 284 The template <CODE>stream</CODE> derives from a specialization of <CODE>std::basic_istream</CODE>, <CODE>std::basic_ostream</CODE> or <CODE>std::basic_iostream</CODE>, depending on whether the underlying <A HREF="../concepts/device.html">Device</A> models <A HREF="../concepts/source.html">Source</A>, <A HREF="../concepts/sink.html">Sink</A> or both.. 285</P> 286 287 288<H4>Synopsis</H4> 289 290<PRE><SPAN CLASS="keyword">namespace</SPAN> boost { <SPAN CLASS="keyword">namespace</SPAN> iostreams { 291 292<SPAN CLASS="keyword">template</SPAN>< <SPAN CLASS="keyword">typename</SPAN> <A CLASS="documented" HREF="#stream_params">T</A>, 293 <SPAN CLASS="keyword">typename</SPAN> <A CLASS="documented" HREF="#stream_params">Tr</A> = std::char_traits<<SPAN CLASS="omitted">...</SPAN>>, 294 <SPAN CLASS="keyword">typename</SPAN> <A CLASS="documented" HREF="#stream_params">Alloc</A> = std::allocator<<SPAN CLASS="omitted">...</SPAN>>, 295 <SPAN CLASS="keyword">typename</SPAN> <A CLASS="documented" HREF="#stream_params">Mode</A> = <SPAN CLASS="omitted">...</SPAN> > 296<SPAN CLASS="keyword">class</SPAN> <A CLASS="documented" HREF="#stream_params">stream</A> : <SPAN CLASS="keyword">public</SPAN> [<SPAN CLASS='omitted'>see Description</SPAN>] { 297<SPAN CLASS="keyword">public</SPAN>: 298 <SPAN CLASS="keyword">typedef</SPAN> <SPAN CLASS="keyword">typename</SPAN> char_type_of<T>::type char_type; 299 <SPAN CLASS="keyword">typedef</SPAN> <SPAN CLASS="keyword">typename</SPAN> Tr traits_type; 300 301 [<SPAN CLASS="omitted">Standard stream buffer typedefs: int_type, off_type, etc.</SPAN>] 302 303 <A CLASS="documented" HREF="#stream_default_constructor">stream</A>(); 304 <A CLASS="documented" HREF="#stream_policy_constructor">stream</A>( <SPAN CLASS="keyword">const</SPAN> T& t, 305 std::streamsize buffer_size = <SPAN CLASS="omitted">default_value</SPAN>, 306 std::streamsize pback_size = <SPAN CLASS="omitted">default_value</SPAN> ); 307 308 <SPAN CLASS="comment">// Forwarding constructors</SPAN> 309 310 <SPAN CLASS="keyword">template</SPAN><<SPAN CLASS="keyword">typename</SPAN> U> 311 <A CLASS="documented" HREF="#stream_forwarding_constructors">stream</A>([<SPAN CLASS="keyword">const</SPAN>] U& u); 312 313 <SPAN CLASS="keyword">template</SPAN><<SPAN CLASS="keyword">typename</SPAN> U1, <SPAN CLASS="keyword">typename</SPAN> U2> 314 <A CLASS="documented" HREF="#stream_forwarding_constructors">stream</A>([<SPAN CLASS="keyword">const</SPAN>] U1& u1, <SPAN CLASS="keyword">const</SPAN> U2& u2); 315 316 <SPAN CLASS="omitted">...</SPAN> 317 318 <SPAN CLASS="keyword">template</SPAN><<SPAN CLASS="keyword">typename</SPAN> U1, <SPAN CLASS="omitted">...</SPAN>, <SPAN CLASS="keyword">typename</SPAN> UN> 319 <A CLASS="documented" HREF="#stream_forwarding_constructors">stream</A>([<SPAN CLASS="keyword">const</SPAN>] U1& u1, <SPAN CLASS="keyword">const</SPAN> U2& u2, <SPAN CLASS="omitted">...</SPAN>, <SPAN CLASS="keyword">const</SPAN> UN& uN); 320 321 <SPAN CLASS="keyword">void</SPAN> <A CLASS="documented" HREF="#stream_open">open</A>( <SPAN CLASS="keyword">const</SPAN> T& t, 322 std::streamsize buffer_size = <SPAN CLASS="omitted">default_value</SPAN>, 323 std::streamsize pback_size = <SPAN CLASS="omitted">default_value</SPAN> ); 324 325 <SPAN CLASS="comment">// Forwarding overloads of open()</SPAN> 326 327 <SPAN CLASS="keyword">template</SPAN><<SPAN CLASS="keyword">typename</SPAN> U> 328 <SPAN CLASS="keyword">void</SPAN> <A CLASS="documented" HREF="#stream_forwarding_open">open</A>([<SPAN CLASS="keyword">const</SPAN>] U& u); 329 330 <SPAN CLASS="keyword">template</SPAN><<SPAN CLASS="keyword">typename</SPAN> U1, <SPAN CLASS="keyword">typename</SPAN> U2> 331 <SPAN CLASS="keyword">void</SPAN> <A CLASS="documented" HREF="#stream_forwarding_open">open</A>([<SPAN CLASS="keyword">const</SPAN>] U1& u1, <SPAN CLASS="keyword">const</SPAN> U2& u2); 332 333 <SPAN CLASS="omitted">...</SPAN> 334 335 <SPAN CLASS="keyword">template</SPAN><<SPAN CLASS="keyword">typename</SPAN> U1, <SPAN CLASS="omitted">...</SPAN>, <SPAN CLASS="keyword">typename</SPAN> UN> 336 <SPAN CLASS="keyword">void</SPAN> <A CLASS="documented" HREF="#stream_forwarding_open">open</A>([<SPAN CLASS="keyword">const</SPAN>] U1& u1, <SPAN CLASS="keyword">const</SPAN> U2& u2, <SPAN CLASS="omitted">...</SPAN>, <SPAN CLASS="keyword">const</SPAN> UN& uN); 337 338 <SPAN CLASS="keyword">bool</SPAN> <A CLASS="documented" HREF="#stream_is_open">is_open</A>() <SPAN CLASS="keyword">const</SPAN>; 339 <SPAN CLASS="keyword">void</SPAN> <A CLASS="documented" HREF="#stream_close">close</A>(); 340 341 <SPAN CLASS="comment">// Device access</SPAN> 342 343 T& <A CLASS='documented' HREF="#stream_operator_star"><SPAN CLASS="documented">operator</SPAN>*</A>(); 344 T* <A CLASS='documented' HREF="#stream_operator_arrow"><SPAN CLASS="documented">operator-></SPAN></A>(); 345}; 346 347} } <SPAN CLASS="comment">// namespace boost::io</SPAN></PRE> 348 349<A NAME="stream_params"></A> 350<H4>Template parameters</H4> 351 352<TABLE STYLE="margin-left:2em" BORDER=0 CELLPADDING=2> 353<TR> 354 <TR> 355 <TD VALIGN="top"><I>T</I></TD><TD WIDTH="2em" VALIGN="top">-</TD> 356 <TD>A <A HREF="../../../../doc/html/CopyConstructible.html" TARGET="_top">CopyConstructible</A> model of one of the <A HREF="concepts.html#device_concepts">Device</A> concepts.</TD> 357 </TR> 358 <TR> 359 <TD VALIGN="top"><I>Tr</I></TD><TD WIDTH="2em" VALIGN="top">-</TD> 360 <TD>A C++ standard library charatcer traits type (<A CLASS="bib_ref" href="../bibliography.html#iso">[ISO]</A>, 21.1.1) with <CODE>char_type</CODE> equal to the <A HREF="traits.html#char_type">character type</A> <CODE>Ch</CODE> of T. Defaults to <CODE>std::char_traits<Ch></CODE>.</TD> 361 </TR> 362 <TR> 363 <TD VALIGN="top"><I>Alloc</I></TD><TD WIDTH="2em" VALIGN="top">-</TD> 364 <TD>A C++ standard library allocator type (<A CLASS="bib_ref" href="../bibliography.html#iso">[ISO]</A>, 20.1.5), used to allocate any required character buffers. Defaults to <CODE>std::allocator<Ch></CODE>, where <CODE>Ch</CODE> is the <A HREF="traits.html#char_type">character type</A> of T.</TD> 365 </TR> 366 <TR> 367 <TD VALIGN="top"><I>Mode</I></TD><TD WIDTH="2em" VALIGN="top">-</TD> 368 <TD>A mode tag <I>convertible to the <A HREF="modes.html">mode</A> of T</I>. This parameter is principally for internal use. Specifying a <A HREF="modes.html#mode_tags">mode tag</A> properly refined by the mode of T can prevent an unneeded buffer from being allocated in some cases. Defaults to the mode of T.</TD> 369 </TR> 370</TABLE> 371 372<H4><CODE>stream::stream</CODE></H4> 373 374<A NAME="stream_default_constructor"></A> 375<PRE> <B>stream</B>();</PRE> 376 377<P> 378 Constructs a <CODE>stream</CODE> with no associated instance of the Device <CODE>T</CODE>. Before the instance can be used for i/o, one of its <CODE>open()</CODE> overloads must be invoked. 379</P> 380 381<H4><CODE>stream::stream</CODE></H4> 382 383<A NAME="stream_policy_constructor"></A> 384<PRE> <B>stream</B>( <SPAN CLASS="keyword">const</SPAN> T& t, 385 std::streamsize buffer_size, 386 std::streamsize pback_size );</PRE> 387 388<P> 389 Constructs a <CODE>stream</CODE> which is ready to perform i/o, where the parameters have the following interpretations: 390 391<TABLE STYLE="margin-left:2em" BORDER=0 CELLPADDING=2> 392<TR> 393 <TR> 394 <TD VALIGN="top"><I>t</I></TD><TD WIDTH="2em" VALIGN="top">-</TD> 395 <TD>An instance of T</TD> 396 </TR> 397 <TR> 398 <TD VALIGN="top"><I>buffer_size</I></TD><TD WIDTH="2em" VALIGN="top">-</TD> 399 <TD>The size of any buffers that need to be allocated</TD> 400 </TR> 401 <TR> 402 <TD VALIGN="top"><I>pback_size</I></TD><TD WIDTH="2em" VALIGN="top">-</TD> 403 <TD>The size of the putback buffer, relevant only if <CODE>Mode</CODE> is a refinement of <A HREF="modes.html#input"><CODE>input</CODE></TD> 404 </TR> 405</TABLE> 406 407<A NAME="stream_forwarding_constructors"></A> 408<PRE> <SPAN CLASS="keyword">template</SPAN><<SPAN CLASS="keyword">typename</SPAN> U> 409 <B>stream</B>([<SPAN CLASS="keyword">const</SPAN>] U& u); 410 411 <SPAN CLASS="keyword">template</SPAN><<SPAN CLASS="keyword">typename</SPAN> U1, <SPAN CLASS="keyword">typename</SPAN> U2> 412 <B>stream</B>([<SPAN CLASS="keyword">const</SPAN>] U1& u1, <SPAN CLASS="keyword">const</SPAN> U2& u2); 413 414 <SPAN CLASS="omitted">...</SPAN> 415 416 template<<SPAN CLASS="keyword">typename</SPAN> U1, <SPAN CLASS="omitted">...</SPAN>, <SPAN CLASS="keyword">typename</SPAN> UN> 417 <B>stream</B>([<SPAN CLASS="keyword">const</SPAN>] U1& u1, <SPAN CLASS="keyword">const</SPAN> U2& u2, <SPAN CLASS="omitted">...</SPAN>, <SPAN CLASS="keyword">const</SPAN> UN& uN);</PRE> 418 419<P> 420 Each of these members constructs an instance of <CODE>stream</CODE> and associates it with an instance of the Device <CODE>T</CODE> constructed from the given lists of arguments. The <CODE>T</CODE> constructors involved must take all arguments by value or <CODE>const</CODE> reference. 421</P> 422<P> 423 It is not possible to specify a custom buffer size or putback buffer size using these constructors. 424</P> 425 426<H4><CODE>stream::open</CODE></H4> 427 428<A NAME="stream_open"></A> 429<PRE> void <B>open</B>( <SPAN CLASS="keyword">const</SPAN> T& t, 430 std::streamsize buffer_size, 431 std::streamsize pback_size );</PRE> 432 433<P> 434 Assocaites the given instance of <CODE>T</CODE> with <CODE>this</CODE> instance of <CODE>stream</CODE>, if there is no such instance currently associated; otherwise, throws <CODE>std::ios_base::failure</CODE>. The second parameter determines the size of any buffers that need to be allocated; a value of zero indicates that i/o should be unbuffered. The third parameter determines the size of the putback buffer; it is relevant only if <CODE>Mode</CODE> is a refinement of <A HREF="modes.html#input"><CODE>input</CODE></A>. 435</P> 436 437<A NAME="stream_forwarding_open"></A> 438<PRE> <SPAN CLASS="keyword">template</SPAN><<SPAN CLASS="keyword">typename</SPAN> U> 439 <SPAN CLASS="keyword">void</SPAN> <B>open</B>([<SPAN CLASS="keyword">const</SPAN>] U& u); 440 441 <SPAN CLASS="keyword">template</SPAN><<SPAN CLASS="keyword">typename</SPAN> U1, <SPAN CLASS="keyword">typename</SPAN> U2> 442 <SPAN CLASS="keyword">void</SPAN> <B>open</B>([<SPAN CLASS="keyword">const</SPAN>] U1& u1, <SPAN CLASS="keyword">const</SPAN> U2& u2); 443 444 <SPAN CLASS="omitted">...</SPAN> 445 446 template<<SPAN CLASS="keyword">typename</SPAN> U1, <SPAN CLASS="omitted">...</SPAN>, <SPAN CLASS="keyword">typename</SPAN> UN> 447 <SPAN CLASS="keyword">void</SPAN> <B>open</B>([<SPAN CLASS="keyword">const</SPAN>] U1& u1, <SPAN CLASS="keyword">const</SPAN> U2& u2, <SPAN CLASS="omitted">...</SPAN>, <SPAN CLASS="keyword">const</SPAN> UN& uN);</PRE> 448 449<P> 450 Each of these members associates with <CODE>this</CODE> instance of <CODE>stream</CODE> a newly constructed instance of the Device <CODE>T</CODE> constructed from the given lists of arguments, if there is no such instance currently associated; otherwise, they throw <CODE>std::ios_base::failure</CODE>. The <CODE>T</CODE> constructors involved must take all arguments by value or <CODE>const</CODE> reference. 451</P> 452<P> 453 It is not possible to specify a custom buffer size or putback buffer size using these members. 454</P> 455 456<A NAME="stream_is_open"></A> 457<H4><CODE>stream::is_open</CODE></H4> 458<PRE> <SPAN CLASS="keyword">bool</SPAN> <B>is_open</B>() <SPAN CLASS="keyword">const</SPAN>;</PRE> 459 460<P>Returns true if there is an instance of the Device <CODE>T</CODE> associated with <CODE>this</CODE> instance of <CODE>stream</CODE>.</P> 461 462<A NAME="stream_close"></A> 463<H4><CODE>stream::close</CODE></H4> 464<PRE> <SPAN CLASS="keyword">void</SPAN> <B>close</B>();</PRE> 465 466<P> 467 Disassociates from <CODE>this</CODE> instance of <CODE>stream</CODE> any instance of the Device <CODE>T</CODE> currently associated with it, calling cleanup functions as appropriate and destroying the associated instance of <CODE>T</CODE>. 468</P> 469 470<A NAME="stream_operator_star"></A> 471<H4><CODE>stream::operator*</CODE></H4> 472<PRE> T& <B>operator*</B>();</PRE> 473 474<P> 475 Returns a reference to the instance of <CODE>T</CODE> associated with this <CODE>stream</CODE>, which must be <A HREF="#stream_is_open"><CODE>open</CODE></A>. 476</P> 477 478<A NAME="stream_operator_arrow"></A> 479<H4><CODE>stream::operator-></CODE></H4> 480<PRE> T* <B>operator-></B>();</PRE> 481 482<P> 483 Returns a pointer to the instance of <CODE>T</CODE> associated with this <CODE>stream</CODE>, which must be <A HREF="#stream_is_open"><CODE>open</CODE></A>. 484</P> 485 486<A NAME="examples"></A> 487<H2>Examples</H2> 488 489<H4>Defining a simple <CODE>ofstream</CODE></H4> 490 491<P>The following example uses a <A HREF="../classes/file.html#file_sink"><CODE>file_sink</CODE></A> to define a class similar to a <CODE>std::ofstream</CODE>. 492 493<PRE> <SPAN CLASS="preprocessor">#include</SPAN> <A STYLE="text-decoration:none" href="../../../../boost/iostreams/device/file.hpp"><SPAN CLASS="literal"><boost/iostreams/device/file.hpp></SPAN></A> 494 <SPAN CLASS="preprocessor">#include</SPAN> <A STYLE="text-decoration:none" href="../../../../boost/iostreams/stream.hpp"><SPAN CLASS="literal"><boost/iostreams/stream.hpp></SPAN></A> 495 496 <SPAN CLASS="keyword">typedef</SPAN> stream<file_sink> ofstream; 497 498 ofstream out(<SPAN CLASS="literal">"HeavyArtillery.txt"</SPAN>); <SPAN CLASS="comment">// Wilfred Owen</SPAN> 499 out << <SPAN CLASS="literal">"Reach at that Arrogance which needs thy harm,\n"</SPAN> 500 <SPAN CLASS="literal">"And beat it down before its sins grow worse.\n"</SPAN>; 501 out.close();</PRE> 502 503<H4>Reading from an array</H4> 504 505<P>The following example uses an <A href="../classes/array.html#array_source"><CODE>array_source</CODE></A> to construct an input stream from a C-style string. 506 507<PRE> <SPAN CLASS="preprocessor">#include</SPAN> <SPAN CLASS="literal"><cstring></SPAN> 508 <SPAN CLASS="preprocessor">#include</SPAN> <SPAN CLASS="literal"><iostream></SPAN> 509 <SPAN CLASS="preprocessor">#include</SPAN> <SPAN CLASS="literal"><string></SPAN> 510 <SPAN CLASS="preprocessor">#include</SPAN> <A STYLE="text-decoration:none" href="../../../../boost/iostreams/device/array.hpp"><SPAN CLASS="literal"><boost/iostreams/device/array.hpp></SPAN></A> 511 <SPAN CLASS="preprocessor">#include</SPAN> <A STYLE="text-decoration:none" href="../../../../boost/iostreams/stream.hpp"><SPAN CLASS="literal"><boost/iostreams/stream.hpp></SPAN></A> 512 513 const char* h = <SPAN CLASS="literal">"Hello World!"</SPAN>; 514 stream<array_source> in(h, std::strlen(h)); 515 std::string hello; 516 std::getline(in, hello); 517 std::cout << hello << "\n"; // <SPAN CLASS="comment">Prints "Hello World!"</SPAN></PRE> 518 519<!-- Begin Footer --> 520 521<HR> 522 523<P CLASS="copyright">© Copyright 2008 <a href="http://www.coderage.com/" target="_top">CodeRage, LLC</a><br/>© Copyright 2004-2007 <a href="https://www.boost.org/users/people/jonathan_turkanis.html" target="_top">Jonathan Turkanis</a></P> 524<P CLASS="copyright"> 525 Distributed under the Boost Software License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at <A HREF="http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt</A>) 526</P> 527 528<!-- End Footer --> 529 530</BODY>
