ceph/src/boost/libs/iostreams/doc/guide/generic_streams.html

   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>&lt;boost/iostreams/stream_buffer.hpp&gt;</CODE></A></DT>
  61   <DT><A CLASS="header" href="../../../../boost/iostreams/stream.hpp"><CODE>&lt;boost/iostreams/stream.hpp&gt;</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>&lt; <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&lt;<SPAN CLASS="omitted">...</SPAN>&gt;,
  82           <SPAN CLASS="keyword">typename</SPAN> <A CLASS="documented" HREF="#stream_buffer_params">Alloc</A> = std::allocator&lt;<SPAN CLASS="omitted">...</SPAN>&gt;,
  83           <SPAN CLASS="keyword">typename</SPAN> <A CLASS="documented" HREF="#stream_buffer_params">Mode</A> = <SPAN CLASS="omitted">...</SPAN> &gt;
  84 <SPAN CLASS="keyword">class</SPAN> <A CLASS="documented" HREF="#stream_buffer_params">stream_buffer</A> : <SPAN CLASS="keyword">public</SPAN> std::basic_streambuf&lt;<SPAN CLASS="omitted">...</SPAN>&gt; {
  85 <SPAN CLASS="keyword">public</SPAN>:
  86     <SPAN CLASS="keyword">typedef</SPAN> <SPAN CLASS="keyword">typename</SPAN> char_type_of&lt;T&gt;::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&amp; 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>&lt;<SPAN CLASS="keyword">typename</SPAN> U&gt;
  99     <A CLASS="documented" HREF="#stream_buffer_forwarding_constructors">stream_buffer</A>([<SPAN CLASS="keyword">const</SPAN>] U&amp; u);
 100
 101     <SPAN CLASS="keyword">template</SPAN>&lt;<SPAN CLASS="keyword">typename</SPAN> U1, <SPAN CLASS="keyword">typename</SPAN> U2&gt;
 102     <A CLASS="documented" HREF="#stream_buffer_forwarding_constructors">stream_buffer</A>([<SPAN CLASS="keyword">const</SPAN>] U1&amp; u1, <SPAN CLASS="keyword">const</SPAN> U2&amp; u2);
 103
 104         <SPAN CLASS="omitted">...</SPAN>
 105
 106     <SPAN CLASS="keyword">template</SPAN>&lt;<SPAN CLASS="keyword">typename</SPAN> U1, <SPAN CLASS="omitted">...</SPAN>, <SPAN CLASS="keyword">typename</SPAN> UN&gt;
 107     <A CLASS="documented" HREF="#stream_buffer_forwarding_constructors">stream_buffer</A>([<SPAN CLASS="keyword">const</SPAN>] U1&amp; u1, <SPAN CLASS="keyword">const</SPAN> U2&amp; u2 <SPAN CLASS="omitted">...</SPAN>, <SPAN CLASS="keyword">const</SPAN> UN&amp; uN);
 108
 109     <SPAN CLASS="keyword">void</SPAN> <A CLASS="documented" HREF="#stream_buffer_open">open</A>( <SPAN CLASS="keyword">const</SPAN> T&amp; 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>&lt;<SPAN CLASS="keyword">typename</SPAN> U&gt;
 116     <SPAN CLASS="keyword">void</SPAN> <A CLASS="documented" HREF="#stream_buffer_forwarding_open">open</A>([<SPAN CLASS="keyword">const</SPAN>] U&amp; u);
 117
 118     <SPAN CLASS="keyword">template</SPAN>&lt;<SPAN CLASS="keyword">typename</SPAN> U1, <SPAN CLASS="keyword">typename</SPAN> U2&gt;
 119     <SPAN CLASS="keyword">void</SPAN> <A CLASS="documented" HREF="#stream_buffer_forwarding_open">open</A>([<SPAN CLASS="keyword">const</SPAN>] U1&amp; u1, <SPAN CLASS="keyword">const</SPAN> U2&amp; u2);
 120
 121         <SPAN CLASS="omitted">...</SPAN>
 122
 123     <SPAN CLASS="keyword">template</SPAN>&lt;<SPAN CLASS="keyword">typename</SPAN> U1, <SPAN CLASS="omitted">...</SPAN>, <SPAN CLASS="keyword">typename</SPAN> UN&gt;
 124     <SPAN CLASS="keyword">void</SPAN> <A CLASS="documented" HREF="#stream_buffer_forwarding_open">open</A>([<SPAN CLASS="keyword">const</SPAN>] U1&amp; u1, <SPAN CLASS="keyword">const</SPAN> U2&amp; u2, <SPAN CLASS="omitted">...</SPAN>, <SPAN CLASS="keyword">const</SPAN> UN&amp; 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&amp; <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-&gt;</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&lt;Ch&gt;</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&lt;Ch&gt;</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&amp; 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>&lt;<SPAN CLASS="keyword">typename</SPAN> U&gt;
 197     <B>stream_buffer</B>([<SPAN CLASS="keyword">const</SPAN>] U&amp; u);
 198
 199     <SPAN CLASS="keyword">template</SPAN>&lt;<SPAN CLASS="keyword">typename</SPAN> U1, <SPAN CLASS="keyword">typename</SPAN> U2&gt;
 200     <B>stream_buffer</B>([<SPAN CLASS="keyword">const</SPAN>] U1&amp; u1, <SPAN CLASS="keyword">const</SPAN> U2&amp; u2);
 201
 202         <SPAN CLASS="omitted">...</SPAN>
 203
 204     template&lt;<SPAN CLASS="keyword">typename</SPAN> U1, <SPAN CLASS="omitted">...</SPAN>, <SPAN CLASS="keyword">typename</SPAN> UN&gt;
 205     <B>stream_buffer</B>([<SPAN CLASS="keyword">const</SPAN>] U1&amp; u1, <SPAN CLASS="keyword">const</SPAN> U2&amp; u2, <SPAN CLASS="omitted">...</SPAN>, <SPAN CLASS="keyword">const</SPAN> UN&amp; 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&amp; 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>&lt;<SPAN CLASS="keyword">typename</SPAN> U&gt;
 227     <SPAN CLASS="keyword">void</SPAN> <B>open</B>(<SPAN CLASS="keyword">const</SPAN> U&amp; u);
 228
 229     <SPAN CLASS="keyword">template</SPAN>&lt;<SPAN CLASS="keyword">typename</SPAN> U1, <SPAN CLASS="keyword">typename</SPAN> U2&gt;
 230     <SPAN CLASS="keyword">void</SPAN> <B>open</B>(<SPAN CLASS="keyword">const</SPAN> U1&amp; u1, <SPAN CLASS="keyword">const</SPAN> U2&amp; u2);
 231
 232         <SPAN CLASS="omitted">...</SPAN>
 233
 234     template&lt;<SPAN CLASS="keyword">typename</SPAN> U1, <SPAN CLASS="omitted">...</SPAN>, <SPAN CLASS="keyword">typename</SPAN> UN&gt;
 235     <SPAN CLASS="keyword">void</SPAN> <B>open</B>(<SPAN CLASS="keyword">const</SPAN> U1&amp; u1, <SPAN CLASS="omitted">...</SPAN>, <SPAN CLASS="keyword">const</SPAN> UN&amp; 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&amp; <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-&gt;</CODE></H4>
 268 <PRE>    T* <B>operator-&gt;</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>&lt; <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&lt;<SPAN CLASS="omitted">...</SPAN>&gt;,
 294           <SPAN CLASS="keyword">typename</SPAN> <A CLASS="documented" HREF="#stream_params">Alloc</A> = std::allocator&lt;<SPAN CLASS="omitted">...</SPAN>&gt;,
 295           <SPAN CLASS="keyword">typename</SPAN> <A CLASS="documented" HREF="#stream_params">Mode</A> = <SPAN CLASS="omitted">...</SPAN> &gt;
 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&lt;T&gt;::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&amp; 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>&lt;<SPAN CLASS="keyword">typename</SPAN> U&gt;
 311     <A CLASS="documented" HREF="#stream_forwarding_constructors">stream</A>([<SPAN CLASS="keyword">const</SPAN>] U&amp; u);
 312
 313     <SPAN CLASS="keyword">template</SPAN>&lt;<SPAN CLASS="keyword">typename</SPAN> U1, <SPAN CLASS="keyword">typename</SPAN> U2&gt;
 314     <A CLASS="documented" HREF="#stream_forwarding_constructors">stream</A>([<SPAN CLASS="keyword">const</SPAN>] U1&amp; u1, <SPAN CLASS="keyword">const</SPAN> U2&amp; u2);
 315
 316         <SPAN CLASS="omitted">...</SPAN>
 317
 318     <SPAN CLASS="keyword">template</SPAN>&lt;<SPAN CLASS="keyword">typename</SPAN> U1, <SPAN CLASS="omitted">...</SPAN>, <SPAN CLASS="keyword">typename</SPAN> UN&gt;
 319     <A CLASS="documented" HREF="#stream_forwarding_constructors">stream</A>([<SPAN CLASS="keyword">const</SPAN>] U1&amp; u1, <SPAN CLASS="keyword">const</SPAN> U2&amp; u2, <SPAN CLASS="omitted">...</SPAN>, <SPAN CLASS="keyword">const</SPAN> UN&amp; uN);
 320
 321     <SPAN CLASS="keyword">void</SPAN> <A CLASS="documented" HREF="#stream_open">open</A>( <SPAN CLASS="keyword">const</SPAN> T&amp; 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>&lt;<SPAN CLASS="keyword">typename</SPAN> U&gt;
 328     <SPAN CLASS="keyword">void</SPAN> <A CLASS="documented" HREF="#stream_forwarding_open">open</A>([<SPAN CLASS="keyword">const</SPAN>] U&amp; u);
 329
 330     <SPAN CLASS="keyword">template</SPAN>&lt;<SPAN CLASS="keyword">typename</SPAN> U1, <SPAN CLASS="keyword">typename</SPAN> U2&gt;
 331     <SPAN CLASS="keyword">void</SPAN> <A CLASS="documented" HREF="#stream_forwarding_open">open</A>([<SPAN CLASS="keyword">const</SPAN>] U1&amp; u1, <SPAN CLASS="keyword">const</SPAN> U2&amp; u2);
 332
 333         <SPAN CLASS="omitted">...</SPAN>
 334
 335     <SPAN CLASS="keyword">template</SPAN>&lt;<SPAN CLASS="keyword">typename</SPAN> U1, <SPAN CLASS="omitted">...</SPAN>, <SPAN CLASS="keyword">typename</SPAN> UN&gt;
 336     <SPAN CLASS="keyword">void</SPAN> <A CLASS="documented" HREF="#stream_forwarding_open">open</A>([<SPAN CLASS="keyword">const</SPAN>] U1&amp; u1, <SPAN CLASS="keyword">const</SPAN> U2&amp; u2, <SPAN CLASS="omitted">...</SPAN>, <SPAN CLASS="keyword">const</SPAN> UN&amp; 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&amp; <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-&gt;</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&lt;Ch&gt;</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&lt;Ch&gt;</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&amp; 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>&lt;<SPAN CLASS="keyword">typename</SPAN> U&gt;
 409     <B>stream</B>([<SPAN CLASS="keyword">const</SPAN>] U&amp; u);
 410
 411     <SPAN CLASS="keyword">template</SPAN>&lt;<SPAN CLASS="keyword">typename</SPAN> U1, <SPAN CLASS="keyword">typename</SPAN> U2&gt;
 412     <B>stream</B>([<SPAN CLASS="keyword">const</SPAN>] U1&amp; u1, <SPAN CLASS="keyword">const</SPAN> U2&amp; u2);
 413
 414         <SPAN CLASS="omitted">...</SPAN>
 415
 416     template&lt;<SPAN CLASS="keyword">typename</SPAN> U1, <SPAN CLASS="omitted">...</SPAN>, <SPAN CLASS="keyword">typename</SPAN> UN&gt;
 417     <B>stream</B>([<SPAN CLASS="keyword">const</SPAN>] U1&amp; u1, <SPAN CLASS="keyword">const</SPAN> U2&amp; u2, <SPAN CLASS="omitted">...</SPAN>, <SPAN CLASS="keyword">const</SPAN> UN&amp; 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&amp; 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>&lt;<SPAN CLASS="keyword">typename</SPAN> U&gt;
 439     <SPAN CLASS="keyword">void</SPAN> <B>open</B>([<SPAN CLASS="keyword">const</SPAN>] U&amp; u);
 440
 441     <SPAN CLASS="keyword">template</SPAN>&lt;<SPAN CLASS="keyword">typename</SPAN> U1, <SPAN CLASS="keyword">typename</SPAN> U2&gt;
 442     <SPAN CLASS="keyword">void</SPAN> <B>open</B>([<SPAN CLASS="keyword">const</SPAN>] U1&amp; u1, <SPAN CLASS="keyword">const</SPAN> U2&amp; u2);
 443
 444         <SPAN CLASS="omitted">...</SPAN>
 445
 446     template&lt;<SPAN CLASS="keyword">typename</SPAN> U1, <SPAN CLASS="omitted">...</SPAN>, <SPAN CLASS="keyword">typename</SPAN> UN&gt;
 447     <SPAN CLASS="keyword">void</SPAN> <B>open</B>([<SPAN CLASS="keyword">const</SPAN>] U1&amp; u1, <SPAN CLASS="keyword">const</SPAN> U2&amp; u2, <SPAN CLASS="omitted">...</SPAN>, <SPAN CLASS="keyword">const</SPAN> UN&amp; 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&amp; <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-&gt;</CODE></H4>
 480 <PRE>    T* <B>operator-&gt;</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">&lt;boost/iostreams/device/file.hpp&gt;</SPAN></A>
 494     <SPAN CLASS="preprocessor">#include</SPAN> <A STYLE="text-decoration:none" href="../../../../boost/iostreams/stream.hpp"><SPAN CLASS="literal">&lt;boost/iostreams/stream.hpp&gt;</SPAN></A>
 495
 496     <SPAN CLASS="keyword">typedef</SPAN> stream&lt;file_sink&gt; ofstream;
 497
 498     ofstream out(<SPAN CLASS="literal">"HeavyArtillery.txt"</SPAN>); <SPAN CLASS="comment">// Wilfred Owen</SPAN>
 499     out &lt;&lt; <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">&lt;cstring&gt;</SPAN>
 508     <SPAN CLASS="preprocessor">#include</SPAN> <SPAN CLASS="literal">&lt;iostream&gt;</SPAN>
 509     <SPAN CLASS="preprocessor">#include</SPAN> <SPAN CLASS="literal">&lt;string&gt;</SPAN>
 510     <SPAN CLASS="preprocessor">#include</SPAN> <A STYLE="text-decoration:none" href="../../../../boost/iostreams/device/array.hpp"><SPAN CLASS="literal">&lt;boost/iostreams/device/array.hpp&gt;</SPAN></A>
 511     <SPAN CLASS="preprocessor">#include</SPAN> <A STYLE="text-decoration:none" href="../../../../boost/iostreams/stream.hpp"><SPAN CLASS="literal">&lt;boost/iostreams/stream.hpp&gt;</SPAN></A>
 512
 513     const char*           h = <SPAN CLASS="literal">"Hello World!"</SPAN>;
 514     stream&lt;array_source&gt;  in(h, std::strlen(h));
 515     std::string           hello;
 516     std::getline(in, hello);
 517     std::cout &lt;&lt; hello &lt;&lt; "\n";  // <SPAN CLASS="comment">Prints "Hello World!"</SPAN></PRE>
 518
 519 <!-- Begin Footer -->
 520
 521 <HR>
 522
 523 <P CLASS="copyright">&copy; Copyright 2008 <a href="http://www.coderage.com/" target="_top">CodeRage, LLC</a><br/>&copy; Copyright 2004-2007 <a href="http://www.coderage.com/turkanis/" 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>