1 <!DOCTYPE HTML PUBLIC
"-//W3C//DTD HTML 4.01 Transitional//EN">
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>
13 <H1 CLASS=
"title">User's Guide
</H1>
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>
28 <H2>3.3 Generic Streams and Stream Buffers
</H2>
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>
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>
39 <DT><A href=
"#examples">Examples
</A></DT>
42 <HR STYLE=
"margin-top:1em">
44 <A NAME=
"overview"></A>
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>.
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>.
56 <A NAME=
"headers"></A>
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>
64 <A NAME=
"reference"></A>
67 <A NAME=
"stream_buffer"></A>
68 <H3>Class template
<CODE>stream_buffer
</CODE></H3>
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>.
78 <PRE><SPAN CLASS=
"keyword">namespace
</SPAN> boost {
<SPAN CLASS=
"keyword">namespace
</SPAN> iostreams {
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;
89 [
<SPAN CLASS=
"omitted">Standard stream buffer typedefs: int_type, off_type, etc.
</SPAN>]
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> );
96 <SPAN CLASS=
"comment">// Forwarding constructors
</SPAN>
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);
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);
104 <SPAN CLASS=
"omitted">...
</SPAN>
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);
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> );
113 <SPAN CLASS=
"comment">// Forwarding overloads of open()
</SPAN>
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);
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);
121 <SPAN CLASS=
"omitted">...
</SPAN>
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);
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>();
129 <SPAN CLASS=
"comment">// Device access
</SPAN>
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>();
135 } }
<SPAN CLASS=
"comment">// namespace boost::io
</SPAN></PRE>
137 <A NAME=
"stream_buffer_params"></A>
138 <H4>Template parameters
</H4>
140 <TABLE STYLE=
"margin-left:2em" BORDER=
0 CELLPADDING=
2>
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>
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>
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>
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>
160 <H4><CODE>stream_buffer::stream_buffer
</CODE></H4>
162 <A NAME=
"stream_buffer_default_constructor"></A>
163 <PRE> <B>stream_buffer
</B>();
</PRE>
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.
169 <H4><CODE>stream_buffer::stream_buffer
</CODE></H4>
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>
177 Constructs a
<CODE>stream_buffer
</CODE> which is ready to perform i/o, where the parameters have the following interpretations:
179 <TABLE STYLE=
"margin-left:2em" BORDER=
0 CELLPADDING=
2>
182 <TD VALIGN=
"top"><I>t
</I></TD><TD WIDTH=
"2em" VALIGN=
"top">-
</TD>
183 <TD>An instance of T
</TD>
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>
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>
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);
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);
202 <SPAN CLASS=
"omitted">...
</SPAN>
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>
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.
211 It is not possible to specify a custom buffer size or putback buffer size using these constructors.
214 <H4><CODE>stream_buffer::open
</CODE></H4>
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>
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>.
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);
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);
232 <SPAN CLASS=
"omitted">...
</SPAN>
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>
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.
241 It is not possible to specify a custom buffer size or putback buffer size using these members.
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>
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>
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>
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>.
258 <A NAME=
"stream_buffer_operator_star"></A>
259 <H4><CODE>stream_buffer::operator*
</CODE></H4>
260 <PRE> T
& <B>operator*
</B>();
</PRE>
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>.
266 <A NAME=
"stream_buffer_operator_arrow"></A>
267 <H4><CODE>stream_buffer::operator-
></CODE></H4>
268 <PRE> T*
<B>operator-
></B>();
</PRE>
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>.
274 <A NAME=
"stream"></A>
275 <H3>Class template
<CODE>stream
</CODE></H3>
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>.
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..
290 <PRE><SPAN CLASS=
"keyword">namespace
</SPAN> boost {
<SPAN CLASS=
"keyword">namespace
</SPAN> iostreams {
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;
301 [
<SPAN CLASS=
"omitted">Standard stream buffer typedefs: int_type, off_type, etc.
</SPAN>]
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> );
308 <SPAN CLASS=
"comment">// Forwarding constructors
</SPAN>
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);
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);
316 <SPAN CLASS=
"omitted">...
</SPAN>
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);
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> );
325 <SPAN CLASS=
"comment">// Forwarding overloads of open()
</SPAN>
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);
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);
333 <SPAN CLASS=
"omitted">...
</SPAN>
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);
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>();
341 <SPAN CLASS=
"comment">// Device access
</SPAN>
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>();
347 } }
<SPAN CLASS=
"comment">// namespace boost::io
</SPAN></PRE>
349 <A NAME=
"stream_params"></A>
350 <H4>Template parameters
</H4>
352 <TABLE STYLE=
"margin-left:2em" BORDER=
0 CELLPADDING=
2>
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>
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>
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>
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>
372 <H4><CODE>stream::stream
</CODE></H4>
374 <A NAME=
"stream_default_constructor"></A>
375 <PRE> <B>stream
</B>();
</PRE>
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.
381 <H4><CODE>stream::stream
</CODE></H4>
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>
389 Constructs a
<CODE>stream
</CODE> which is ready to perform i/o, where the parameters have the following interpretations:
391 <TABLE STYLE=
"margin-left:2em" BORDER=
0 CELLPADDING=
2>
394 <TD VALIGN=
"top"><I>t
</I></TD><TD WIDTH=
"2em" VALIGN=
"top">-
</TD>
395 <TD>An instance of T
</TD>
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>
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>
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);
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);
414 <SPAN CLASS=
"omitted">...
</SPAN>
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>
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.
423 It is not possible to specify a custom buffer size or putback buffer size using these constructors.
426 <H4><CODE>stream::open
</CODE></H4>
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>
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>.
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);
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);
444 <SPAN CLASS=
"omitted">...
</SPAN>
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>
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.
453 It is not possible to specify a custom buffer size or putback buffer size using these members.
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>
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>
462 <A NAME=
"stream_close"></A>
463 <H4><CODE>stream::close
</CODE></H4>
464 <PRE> <SPAN CLASS=
"keyword">void
</SPAN> <B>close
</B>();
</PRE>
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>.
470 <A NAME=
"stream_operator_star"></A>
471 <H4><CODE>stream::operator*
</CODE></H4>
472 <PRE> T
& <B>operator*
</B>();
</PRE>
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>.
478 <A NAME=
"stream_operator_arrow"></A>
479 <H4><CODE>stream::operator-
></CODE></H4>
480 <PRE> T*
<B>operator-
></B>();
</PRE>
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>.
486 <A NAME=
"examples"></A>
489 <H4>Defining a simple
<CODE>ofstream
</CODE></H4>
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>.
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>
496 <SPAN CLASS=
"keyword">typedef
</SPAN> stream
<file_sink
> ofstream;
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>;
503 <H4>Reading from an array
</H4>
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.
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>
513 const char* h =
<SPAN CLASS=
"literal">"Hello World!"</SPAN>;
514 stream
<array_source
> in(h, std::strlen(h));
516 std::getline(in, hello);
517 std::cout
<< hello
<< "\n"; //
<SPAN CLASS=
"comment">Prints
"Hello World!"</SPAN></PRE>
519 <!-- Begin Footer -->
523 <P CLASS=
"copyright">© Copyright
2008 <a href=
"http://www.coderage.com/" target=
"_top">CodeRage, LLC
</a><br/>© 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>)