Planet
navi homePPSaboutscreenshotsdownloaddevelopmentforum

source: downloads/boost_1_34_1/libs/iostreams/doc/guide/generic_streams.html @ 29

Last change on this file since 29 was 29, checked in by landauf, 16 years ago

updated boost from 1_33_1 to 1_34_1
File size: 31.6 KB
Line 
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/html/images/prev.png'></A>
22    <A HREF='guide.html'><IMG BORDER=0 WIDTH=19 HEIGHT=19 SRC='../../../../doc/html/images/up.png'></A>
23    <A HREF='filtering_streams.html'><IMG BORDER=0 WIDTH=19 HEIGHT=19 SRC='../../../../doc/html/images/next.png'></A>
24</DIV>
25
26<!-- End Nav -->
27
28<A NAME="overview"></A>
29<H2>3.3 Generic Streams and Stream Buffers</H2>
30
31<DL class="page-index">
32  <DT><A href="#overview">Overview</A></DT>
33  <DT><A href="#headers">Headers</A></DT>
34  <DT><A href="#reference">Reference</A>
35    <DL>
36      <DT><A href="#stream_buffer">Class template <CODE>stream_buffer</CODE></A></DT>
37      <DT><A href="#stream">Class template <CODE>stream</CODE></A></DT>
38    </DL>
39  </DT>
40  <DT><A href="#examples">Examples</A></DT>
41</DL>
42
43<HR STYLE="margin-top:1em">
44
45<A NAME="overview"></A>
46<H2>Overview</H2>
47
48<P>
49    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>.
50</P>
51
52<P>
53    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>.
54</P>
55
56
57<A NAME="headers"></A>
58<H2>Headers</H2>
59
60<DL class="page-index">
61  <DT><A CLASS="header" href="../../../../boost/iostreams/stream_buffer.hpp"><CODE>&lt;boost/iostreams/stream_buffer.hpp&gt;</CODE></A></DT>
62  <DT><A CLASS="header" href="../../../../boost/iostreams/stream.hpp"><CODE>&lt;boost/iostreams/stream.hpp&gt;</CODE></A></DT>
63</DL>
64
65<A NAME="reference"></A>
66<H2>Reference</H2>
67
68<A NAME="stream_buffer"></A>
69<H3>Class template <CODE>stream_buffer</CODE></H3>
70
71<H4>Description</H4>
72
73<P>
74    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>.
75</P>
76
77<H4>Synopsis</H4>
78
79<PRE><SPAN CLASS="keyword">namespace</SPAN> boost { <SPAN CLASS="keyword">namespace</SPAN> iostreams {
80
81<SPAN CLASS="keyword">template</SPAN>&lt; <SPAN CLASS="keyword">typename</SPAN> <A CLASS="documented" HREF="#stream_buffer_params">T</A>,
82          <SPAN CLASS="keyword">typename</SPAN> <A CLASS="documented" HREF="#stream_buffer_params">Tr</A> = std::char_traits&lt;<SPAN CLASS="omitted">...</SPAN>&gt;,
83          <SPAN CLASS="keyword">typename</SPAN> <A CLASS="documented" HREF="#stream_buffer_params">Alloc</A> = std::allocator&lt;<SPAN CLASS="omitted">...</SPAN>&gt;,
84          <SPAN CLASS="keyword">typename</SPAN> <A CLASS="documented" HREF="#stream_buffer_params">Mode</A> = <SPAN CLASS="omitted">...</SPAN> &gt;
85<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; {
86<SPAN CLASS="keyword">public</SPAN>:
87    <SPAN CLASS="keyword">typedef</SPAN> <SPAN CLASS="keyword">typename</SPAN> char_type_of&lt;T&gt;::type  char_type;
88    <SPAN CLASS="keyword">typedef</SPAN> <SPAN CLASS="keyword">typename</SPAN> Tr                     traits_type;
89
90    [<SPAN CLASS="omitted">Standard stream buffer typedefs: int_type, off_type, etc.</SPAN>]
91
92    <A CLASS="documented" HREF="#stream_buffer_default_constructor">stream_buffer</A>();
93    <A CLASS="documented" HREF="#stream_buffer_policy_constructor">stream_buffer</A>( <SPAN CLASS="keyword">const</SPAN> T& t,
94                   std::streamsize buffer_size = <SPAN CLASS="omitted">default_value</SPAN>,
95                   std::streamsize pback_size = <SPAN CLASS="omitted">default_value</SPAN> );
96
97        <SPAN CLASS="comment">// Forwarding constructors</SPAN>
98
99    <SPAN CLASS="keyword">template</SPAN>&lt;<SPAN CLASS="keyword">typename</SPAN> U&gt;
100    <A CLASS="documented" HREF="#stream_buffer_forwarding_constructors">stream_buffer</A>([<SPAN CLASS="keyword">const</SPAN>] U& u);
101
102    <SPAN CLASS="keyword">template</SPAN>&lt;<SPAN CLASS="keyword">typename</SPAN> U1, <SPAN CLASS="keyword">typename</SPAN> U2&gt;
103    <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);
104
105        <SPAN CLASS="omitted">...</SPAN>
106
107    <SPAN CLASS="keyword">template</SPAN>&lt;<SPAN CLASS="keyword">typename</SPAN> U1, <SPAN CLASS="omitted">...</SPAN>, <SPAN CLASS="keyword">typename</SPAN> UN&gt;
108    <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);
109
110    <SPAN CLASS="keyword">void</SPAN> <A CLASS="documented" HREF="#stream_buffer_open">open</A>( <SPAN CLASS="keyword">const</SPAN> T& t,
111               std::streamsize buffer_size = <SPAN CLASS="omitted">default_value</SPAN>,
112               std::streamsize pback_size = <SPAN CLASS="omitted">default_value</SPAN> );
113
114        <SPAN CLASS="comment">// Forwarding overloads of open()</SPAN>
115
116    <SPAN CLASS="keyword">template</SPAN>&lt;<SPAN CLASS="keyword">typename</SPAN> U&gt;
117    <SPAN CLASS="keyword">void</SPAN> <A CLASS="documented" HREF="#stream_buffer_forwarding_open">open</A>([<SPAN CLASS="keyword">const</SPAN>] U& u);
118
119    <SPAN CLASS="keyword">template</SPAN>&lt;<SPAN CLASS="keyword">typename</SPAN> U1, <SPAN CLASS="keyword">typename</SPAN> U2&gt;
120    <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);
121   
122        <SPAN CLASS="omitted">...</SPAN>
123
124    <SPAN CLASS="keyword">template</SPAN>&lt;<SPAN CLASS="keyword">typename</SPAN> U1, <SPAN CLASS="omitted">...</SPAN>, <SPAN CLASS="keyword">typename</SPAN> UN&gt;
125    <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);
126
127    <SPAN CLASS="keyword">bool</SPAN> <A CLASS="documented" HREF="#stream_buffer_is_open">is_open</A>() <SPAN CLASS="keyword">const</SPAN>;
128    <SPAN CLASS="keyword">void</SPAN> <A CLASS="documented" HREF="#stream_buffer_close">close</A>();
129
130        <SPAN CLASS="comment">// Device access</SPAN>
131   
132    T& <A CLASS='documented' HREF="#stream_buffer_operator_star"><SPAN CLASS="documented">operator</SPAN>*</A>();
133    T* <A CLASS='documented' HREF="#stream_buffer_operator_arrow"><SPAN CLASS="documented">operator-&gt;</SPAN></A>();
134};
135
136} } <SPAN CLASS="comment">// namespace boost::io</SPAN></PRE>
137
138<A NAME="stream_buffer_params"></A>
139<H4>Template parameters</H4>
140
141<TABLE STYLE="margin-left:2em" BORDER=0 CELLPADDING=2>
142<TR>
143    <TR>
144        <TD VALIGN="top"><A NAME="level"></A><I>T</I></TD><TD WIDTH="2em" VALIGN="top">-</TD>
145        <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>
146    </TR>
147    <TR>
148        <TD VALIGN="top"><A NAME="level"></A><I>Tr</I></TD><TD WIDTH="2em" VALIGN="top">-</TD>
149        <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>
150    </TR>
151    <TR>
152        <TD VALIGN="top"><A NAME="level"></A><I>Alloc</I></TD><TD WIDTH="2em" VALIGN="top">-</TD>
153        <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>
154    </TR>
155    <TR>
156        <TD VALIGN="top"><A NAME="level"></A><I>Mode</I></TD><TD WIDTH="2em" VALIGN="top">-</TD>
157        <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>
158    </TR>
159</TABLE>
160
161<H4><CODE>stream_buffer::stream_buffer</CODE></H4>
162
163<A NAME="stream_buffer_default_constructor"></A>
164<PRE>    <B>stream_buffer</B>();</PRE>
165   
166<P>
167    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.
168</P>
169
170<H4><CODE>stream_buffer::stream_buffer</CODE></H4>
171
172<A NAME="stream_buffer_policy_constructor"></A>
173<PRE>    <B>stream_buffer</B>( <SPAN CLASS="keyword">const</SPAN> T& t,
174                   std::streamsize buffer_size,
175                   std::streamsize pback_size );</PRE>
176   
177<P>
178    Constructs a <CODE>stream_buffer</CODE> which is ready to perform i/o, where the parameters have the following interpretations:
179
180<TABLE STYLE="margin-left:2em" BORDER=0 CELLPADDING=2>
181<TR>
182    <TR>
183        <TD VALIGN="top"><A NAME="level"></A><I>t</I></TD><TD WIDTH="2em" VALIGN="top">-</TD>
184        <TD>An instance of T</TD>
185    </TR>
186    <TR>
187        <TD VALIGN="top"><A NAME="level"></A><I>buffer_size</I></TD><TD WIDTH="2em" VALIGN="top">-</TD>
188        <TD>The size of any buffers that need to be allocated</TD>
189    </TR>
190    <TR>
191        <TD VALIGN="top"><A NAME="level"></A><I>pback_size</I></TD><TD WIDTH="2em" VALIGN="top">-</TD>
192        <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>
193    </TR>
194</TABLE>
195
196<A NAME="stream_buffer_forwarding_constructors"></A>
197<PRE>    <SPAN CLASS="keyword">template</SPAN>&lt;<SPAN CLASS="keyword">typename</SPAN> U&gt;
198    <B>stream_buffer</B>([<SPAN CLASS="keyword">const</SPAN>] U& u);
199
200    <SPAN CLASS="keyword">template</SPAN>&lt;<SPAN CLASS="keyword">typename</SPAN> U1, <SPAN CLASS="keyword">typename</SPAN> U2&gt;
201    <B>stream_buffer</B>([<SPAN CLASS="keyword">const</SPAN>] U1& u1, <SPAN CLASS="keyword">const</SPAN> U2& u2);
202
203        <SPAN CLASS="omitted">...</SPAN>
204
205    template&lt;<SPAN CLASS="keyword">typename</SPAN> U1, <SPAN CLASS="omitted">...</SPAN>, <SPAN CLASS="keyword">typename</SPAN> UN&gt;
206    <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>
207
208<P>
209    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.
210</P>
211<P>
212    It is not possible to specify a custom buffer size or putback buffer size using these constructors.
213</P>
214
215<H4><CODE>stream_buffer::open</CODE></H4>
216
217<A NAME="stream_buffer_open"></A>
218<PRE>    void <B>open</B>( <SPAN CLASS="keyword">const</SPAN> T& t,
219               std::streamsize buffer_size,
220               std::streamsize pback_size );</PRE>
221   
222<P>
223    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>.
224</P>
225
226<A NAME="stream_buffer_forwarding_open"></A>
227<PRE>    <SPAN CLASS="keyword">template</SPAN>&lt;<SPAN CLASS="keyword">typename</SPAN> U&gt;
228    <SPAN CLASS="keyword">void</SPAN> <B>open</B>(<SPAN CLASS="keyword">const</SPAN> U& u);
229
230    <SPAN CLASS="keyword">template</SPAN>&lt;<SPAN CLASS="keyword">typename</SPAN> U1, <SPAN CLASS="keyword">typename</SPAN> U2&gt;
231    <SPAN CLASS="keyword">void</SPAN> <B>open</B>(<SPAN CLASS="keyword">const</SPAN> U1& u1, <SPAN CLASS="keyword">const</SPAN> U2& u2);
232
233        <SPAN CLASS="omitted">...</SPAN>
234
235    template&lt;<SPAN CLASS="keyword">typename</SPAN> U1, <SPAN CLASS="omitted">...</SPAN>, <SPAN CLASS="keyword">typename</SPAN> UN&gt;
236    <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>
237
238<P>
239    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.
240</P>
241<P>
242    It is not possible to specify a custom buffer size or putback buffer size using these members.
243</P>
244
245<A NAME="stream_buffer_is_open"></A>
246<H4><CODE>stream_buffer::is_open</CODE></H4>
247<PRE>    <SPAN CLASS="keyword">bool</SPAN> <B>is_open</B>() <SPAN CLASS="keyword">const</SPAN>;</PRE>
248   
249<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>
250
251<A NAME="stream_buffer_close"></A>
252<H4><CODE>stream_buffer::close</CODE></H4>
253<PRE>    <SPAN CLASS="keyword">void</SPAN> <B>close</B>();</PRE>
254   
255<P>
256    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>.
257</P>
258
259<A NAME="stream_buffer_operator_star"></A>
260<H4><CODE>stream_buffer::operator*</CODE></H4>
261<PRE>    T& <B>operator*</B>();</PRE>
262   
263<P>
264    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>.
265</P>
266
267<A NAME="stream_buffer_operator_arrow"></A>
268<H4><CODE>stream_buffer::operator-&gt;</CODE></H4>
269<PRE>    T* <B>operator-&gt;</B>();</PRE>
270   
271<P>
272    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>.
273</P>
274
275<A NAME="stream"></A>
276<H3>Class template <CODE>stream</CODE></H3>
277
278<H4>Description</H4>
279
280<P>
281    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>.
282</P>
283
284<P>
285    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..
286</P>
287
288
289<H4>Synopsis</H4>
290
291<PRE><SPAN CLASS="keyword">namespace</SPAN> boost { <SPAN CLASS="keyword">namespace</SPAN> iostreams {
292
293<SPAN CLASS="keyword">template</SPAN>&lt; <SPAN CLASS="keyword">typename</SPAN> <A CLASS="documented" HREF="#stream_params">T</A>,
294          <SPAN CLASS="keyword">typename</SPAN> <A CLASS="documented" HREF="#stream_params">Tr</A> = std::char_traits&lt;<SPAN CLASS="omitted">...</SPAN>&gt;,
295          <SPAN CLASS="keyword">typename</SPAN> <A CLASS="documented" HREF="#stream_params">Alloc</A> = std::allocator&lt;<SPAN CLASS="omitted">...</SPAN>&gt;,
296          <SPAN CLASS="keyword">typename</SPAN> <A CLASS="documented" HREF="#stream_params">Mode</A> = <SPAN CLASS="omitted">...</SPAN> &gt;
297<SPAN CLASS="keyword">class</SPAN> <A CLASS="documented" HREF="#stream_params">stream</A> : <SPAN CLASS="keyword">public</SPAN> [<SPAN CLASS='omitted'>see Description</SPAN>] {
298<SPAN CLASS="keyword">public</SPAN>:
299    <SPAN CLASS="keyword">typedef</SPAN> <SPAN CLASS="keyword">typename</SPAN> char_type_of&lt;T&gt;::type  char_type;
300    <SPAN CLASS="keyword">typedef</SPAN> <SPAN CLASS="keyword">typename</SPAN> Tr                     traits_type;
301
302    [<SPAN CLASS="omitted">Standard stream buffer typedefs: int_type, off_type, etc.</SPAN>]
303
304    <A CLASS="documented" HREF="#stream_default_constructor">stream</A>();
305    <A CLASS="documented" HREF="#stream_policy_constructor">stream</A>( <SPAN CLASS="keyword">const</SPAN> T& t,
306            std::streamsize buffer_size = <SPAN CLASS="omitted">default_value</SPAN>,
307            std::streamsize pback_size = <SPAN CLASS="omitted">default_value</SPAN> );
308
309        <SPAN CLASS="comment">// Forwarding constructors</SPAN>
310
311    <SPAN CLASS="keyword">template</SPAN>&lt;<SPAN CLASS="keyword">typename</SPAN> U&gt;
312    <A CLASS="documented" HREF="#stream_forwarding_constructors">stream</A>([<SPAN CLASS="keyword">const</SPAN>] U& u);
313
314    <SPAN CLASS="keyword">template</SPAN>&lt;<SPAN CLASS="keyword">typename</SPAN> U1, <SPAN CLASS="keyword">typename</SPAN> U2&gt;
315    <A CLASS="documented" HREF="#stream_forwarding_constructors">stream</A>([<SPAN CLASS="keyword">const</SPAN>] U1& u1, <SPAN CLASS="keyword">const</SPAN> U2& u2);
316
317        <SPAN CLASS="omitted">...</SPAN>
318
319    <SPAN CLASS="keyword">template</SPAN>&lt;<SPAN CLASS="keyword">typename</SPAN> U1, <SPAN CLASS="omitted">...</SPAN>, <SPAN CLASS="keyword">typename</SPAN> UN&gt;
320    <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);
321
322    <SPAN CLASS="keyword">void</SPAN> <A CLASS="documented" HREF="#stream_open">open</A>( <SPAN CLASS="keyword">const</SPAN> T& t,
323               std::streamsize buffer_size = <SPAN CLASS="omitted">default_value</SPAN>,
324               std::streamsize pback_size = <SPAN CLASS="omitted">default_value</SPAN> );
325
326        <SPAN CLASS="comment">// Forwarding overloads of open()</SPAN>
327
328    <SPAN CLASS="keyword">template</SPAN>&lt;<SPAN CLASS="keyword">typename</SPAN> U&gt;
329    <SPAN CLASS="keyword">void</SPAN> <A CLASS="documented" HREF="#stream_forwarding_open">open</A>([<SPAN CLASS="keyword">const</SPAN>] U& u);
330
331    <SPAN CLASS="keyword">template</SPAN>&lt;<SPAN CLASS="keyword">typename</SPAN> U1, <SPAN CLASS="keyword">typename</SPAN> U2&gt;
332    <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);
333   
334        <SPAN CLASS="omitted">...</SPAN>
335
336    <SPAN CLASS="keyword">template</SPAN>&lt;<SPAN CLASS="keyword">typename</SPAN> U1, <SPAN CLASS="omitted">...</SPAN>, <SPAN CLASS="keyword">typename</SPAN> UN&gt;
337    <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);
338
339    <SPAN CLASS="keyword">bool</SPAN> <A CLASS="documented" HREF="#stream_is_open">is_open</A>() <SPAN CLASS="keyword">const</SPAN>;
340    <SPAN CLASS="keyword">void</SPAN> <A CLASS="documented" HREF="#stream_close">close</A>();
341
342        <SPAN CLASS="comment">// Device access</SPAN>
343   
344    T& <A CLASS='documented' HREF="#stream_operator_star"><SPAN CLASS="documented">operator</SPAN>*</A>();
345    T* <A CLASS='documented' HREF="#stream_operator_arrow"><SPAN CLASS="documented">operator-&gt;</SPAN></A>();
346};
347
348} } <SPAN CLASS="comment">// namespace boost::io</SPAN></PRE>
349
350<A NAME="stream_params"></A>
351<H4>Template parameters</H4>
352
353<TABLE STYLE="margin-left:2em" BORDER=0 CELLPADDING=2>
354<TR>
355    <TR>
356        <TD VALIGN="top"><A NAME="level"></A><I>T</I></TD><TD WIDTH="2em" VALIGN="top">-</TD>
357        <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>
358    </TR>
359    <TR>
360        <TD VALIGN="top"><A NAME="level"></A><I>Tr</I></TD><TD WIDTH="2em" VALIGN="top">-</TD>
361        <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>
362    </TR>
363    <TR>
364        <TD VALIGN="top"><A NAME="level"></A><I>Alloc</I></TD><TD WIDTH="2em" VALIGN="top">-</TD>
365        <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>
366    </TR>
367    <TR>
368        <TD VALIGN="top"><A NAME="level"></A><I>Mode</I></TD><TD WIDTH="2em" VALIGN="top">-</TD>
369        <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>
370    </TR>
371</TABLE>
372
373<H4><CODE>stream::stream</CODE></H4>
374
375<A NAME="stream_default_constructor"></A>
376<PRE>    <B>stream</B>();</PRE>
377   
378<P>
379    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.
380</P>
381
382<H4><CODE>stream::stream</CODE></H4>
383
384<A NAME="stream_policy_constructor"></A>
385<PRE>    <B>stream</B>( <SPAN CLASS="keyword">const</SPAN> T& t,
386            std::streamsize buffer_size,
387            std::streamsize pback_size );</PRE>
388   
389<P>
390    Constructs a <CODE>stream</CODE> which is ready to perform i/o, where the parameters have the following interpretations:
391
392<TABLE STYLE="margin-left:2em" BORDER=0 CELLPADDING=2>
393<TR>
394    <TR>
395        <TD VALIGN="top"><A NAME="level"></A><I>t</I></TD><TD WIDTH="2em" VALIGN="top">-</TD>
396        <TD>An instance of T</TD>
397    </TR>
398    <TR>
399        <TD VALIGN="top"><A NAME="level"></A><I>buffer_size</I></TD><TD WIDTH="2em" VALIGN="top">-</TD>
400        <TD>The size of any buffers that need to be allocated</TD>
401    </TR>
402    <TR>
403        <TD VALIGN="top"><A NAME="level"></A><I>pback_size</I></TD><TD WIDTH="2em" VALIGN="top">-</TD>
404        <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>
405    </TR>
406</TABLE>
407
408<A NAME="stream_forwarding_constructors"></A>
409<PRE>    <SPAN CLASS="keyword">template</SPAN>&lt;<SPAN CLASS="keyword">typename</SPAN> U&gt;
410    <B>stream</B>([<SPAN CLASS="keyword">const</SPAN>] U& u);
411
412    <SPAN CLASS="keyword">template</SPAN>&lt;<SPAN CLASS="keyword">typename</SPAN> U1, <SPAN CLASS="keyword">typename</SPAN> U2&gt;
413    <B>stream</B>([<SPAN CLASS="keyword">const</SPAN>] U1& u1, <SPAN CLASS="keyword">const</SPAN> U2& u2);
414
415        <SPAN CLASS="omitted">...</SPAN>
416
417    template&lt;<SPAN CLASS="keyword">typename</SPAN> U1, <SPAN CLASS="omitted">...</SPAN>, <SPAN CLASS="keyword">typename</SPAN> UN&gt;
418    <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>
419
420<P>
421    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.
422</P>
423<P>
424    It is not possible to specify a custom buffer size or putback buffer size using these constructors.
425</P>
426
427<H4><CODE>stream::open</CODE></H4>
428
429<A NAME="stream_open"></A>
430<PRE>    void <B>open</B>( <SPAN CLASS="keyword">const</SPAN> T& t,
431               std::streamsize buffer_size,
432               std::streamsize pback_size );</PRE>
433   
434<P>
435    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>.
436</P>
437
438<A NAME="stream_forwarding_open"></A>
439<PRE>    <SPAN CLASS="keyword">template</SPAN>&lt;<SPAN CLASS="keyword">typename</SPAN> U&gt;
440    <SPAN CLASS="keyword">void</SPAN> <B>open</B>([<SPAN CLASS="keyword">const</SPAN>] U& u);
441
442    <SPAN CLASS="keyword">template</SPAN>&lt;<SPAN CLASS="keyword">typename</SPAN> U1, <SPAN CLASS="keyword">typename</SPAN> U2&gt;
443    <SPAN CLASS="keyword">void</SPAN> <B>open</B>([<SPAN CLASS="keyword">const</SPAN>] U1& u1, <SPAN CLASS="keyword">const</SPAN> U2& u2);
444
445        <SPAN CLASS="omitted">...</SPAN>
446
447    template&lt;<SPAN CLASS="keyword">typename</SPAN> U1, <SPAN CLASS="omitted">...</SPAN>, <SPAN CLASS="keyword">typename</SPAN> UN&gt;
448    <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>
449
450<P>
451    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.
452</P>
453<P>
454    It is not possible to specify a custom buffer size or putback buffer size using these members.
455</P>
456
457<A NAME="stream_is_open"></A>
458<H4><CODE>stream::is_open</CODE></H4>
459<PRE>    <SPAN CLASS="keyword">bool</SPAN> <B>is_open</B>() <SPAN CLASS="keyword">const</SPAN>;</PRE>
460   
461<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>
462
463<A NAME="stream_close"></A>
464<H4><CODE>stream::close</CODE></H4>
465<PRE>    <SPAN CLASS="keyword">void</SPAN> <B>close</B>();</PRE>
466   
467<P>
468    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>.
469</P>
470
471<A NAME="stream_operator_star"></A>
472<H4><CODE>stream::operator*</CODE></H4>
473<PRE>    T& <B>operator*</B>();</PRE>
474   
475<P>
476    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>.
477</P>
478
479<A NAME="stream_operator_arrow"></A>
480<H4><CODE>stream::operator-&gt;</CODE></H4>
481<PRE>    T* <B>operator-&gt;</B>();</PRE>
482   
483<P>
484    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>.
485</P>
486
487<A NAME="examples"></A>
488<H2>Examples</H2>
489
490<H4>Defining a simple <CODE>ofstream</CODE></H4>
491
492<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>.
493
494<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>
495    <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>
496         
497    <SPAN CLASS="keyword">typedef</SPAN> stream&lt;file_sink&gt; ofstream;
498
499    ofstream out(<SPAN CLASS="literal">"HeavyArtillery.txt"</SPAN>); <SPAN CLASS="comment">// Wilfred Owen</SPAN>
500    out &lt;&lt; <SPAN CLASS="literal">"Reach at that Arrogance which needs thy harm,\n"</SPAN>
501           <SPAN CLASS="literal">"And beat it down before its sins grow worse.\n"</SPAN>;
502    out.close();</PRE>
503
504<H4>Reading from an array</H4>
505
506<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.
507
508<PRE>    <SPAN CLASS="preprocessor">#include</SPAN> <SPAN CLASS="literal">&lt;cstring&gt;</SPAN>
509    <SPAN CLASS="preprocessor">#include</SPAN> <SPAN CLASS="literal">&lt;iostream&gt;</SPAN>
510    <SPAN CLASS="preprocessor">#include</SPAN> <SPAN CLASS="literal">&lt;string&gt;</SPAN>
511    <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>
512    <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>
513
514    const char*           h = <SPAN CLASS="literal">"Hello World!"</SPAN>;
515    stream&lt;array_source&gt;  in(h, std::strlen(h));
516    std::string           hello;
517    std::getline(in, hello);
518    std::cout &lt;&lt; hello &lt;&lt; "\n";  // <SPAN CLASS="comment">Prints "Hello World!"</SPAN></PRE>
519
520<!-- Begin Footer -->
521
522<HR>
523<P CLASS="copyright">Revised
524<!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->
52520 May, 2004
526<!--webbot bot="Timestamp" endspan i-checksum="38504" -->
527</P>
528
529<P CLASS="copyright">&copy; Copyright <A HREF="http://www.kangaroologic.com" TARGET="_top">Jonathan Turkanis</A>, 2004</P>
530<P CLASS="copyright"> 
531    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>)
532</P>
533
534<!-- End Footer -->
535
536</BODY>
Note: See TracBrowser for help on using the repository browser.