1 <!DOCTYPE HTML PUBLIC
"-//W3C//DTD HTML 4.01 Transitional//EN">
4 <TITLE>Class Template filtering_stream
</TITLE>
5 <LINK REL=
"stylesheet" HREF=
"../../../../boost.css">
6 <LINK REL=
"stylesheet" HREF=
"../theme/iostreams.css">
12 <H1 CLASS=
"title">Class Template
<CODE>filtering_stream
</CODE></H1>
17 <DL class=
"page-index">
18 <DT><A href=
"#description">Description
</A></DT>
19 <DT><A href=
"#headers">Headers
</A></DT>
20 <DT><A href=
"#reference">Reference
</A></DT>
25 <A NAME=
"description"></A>
29 Derived class of
<CODE>std::basic_istream
</CODE>,
<CODE>std::basic_ostream
</CODE> or
<CODE>std::basic_iostream
</CODE>, used to perform filtering. Each
<CODE>filtering_stream
</CODE> contains a
<A HREF=
"chain.html">chain
</A> of zero or more Filters with an optional Device at the end. If the chain contains a Device, the
<CODE>filtering_stream
</CODE> is
<I>complete
</I> and can be used to perform i/o. When a
<CODE>filtering_stream
</CODE> is used for output, data passes through the first filter in the chain, then through the second filter, and so on, and eventually reaches the Device at the end of the chain. When a
<CODE>filtering_stream
</CODE> is used for input, data travels in the opposite direction, beginning at the Device at the end of the chain, then passing through the filters in reverse order. By default, if the Device at the end of the chain is popped or if the
<CODE>filtering_stream
</CODE> is complete when it is destroyed, all the filters and devices in the chain are closed using the function
<A HREF='../functions/close.html'
><CODE>close
</CODE></A>. This behavior can be modified using the member function
<A HREF=
"#set_auto_close"><CODE>set_auto_close
</CODE></A>.
33 <CODE>filtering_stream
</CODE> derives from
<CODE>std::basic_istream
</CODE>,
<CODE>std::basic_ostream
</CODE> or
<CODE>std::basic_iostream
</CODE>, depending on its
<A HREF=
"#template_params"><CODE>Mode
</CODE></A> parameter.
36 <A NAME=
"headers"></A>
39 <DL class=
"page-index">
40 <DT><A CLASS=
"header" HREF=
"../../../../boost/iostreams/filtering_stream.hpp"><CODE><boost/iostreams/filtering_stream.hpp
></CODE></A></DT>
43 <A NAME=
"reference"></A>
46 <A NAME=
"synopsis"></A>
49 <PRE CLASS=
"broken_ie"><SPAN CLASS=
"keyword">namespace
</SPAN> boost {
<SPAN CLASS=
"keyword">namespace
</SPAN> iostreams {
51 <SPAN CLASS=
"keyword">template
</SPAN>< <SPAN CLASS=
"keyword">typename
</SPAN> <A CLASS=
"documented" HREF=
"#template_params">Mode
</A>,
52 <SPAN CLASS=
"keyword">typename
</SPAN> <A CLASS=
"documented" HREF=
"#template_params">Ch
</A> =
<SPAN CLASS=
"keyword">char
</SPAN>,
53 <SPAN CLASS=
"keyword">typename
</SPAN> <A CLASS=
"documented" HREF=
"#template_params">Tr
</A> = std::char_traits
<Ch
>,
54 <SPAN CLASS=
"keyword">typename
</SPAN> <A CLASS=
"documented" HREF=
"#template_params">Alloc
</A> = std::allocator
<<CODE>Ch
</CODE>>,
55 <SPAN CLASS=
"keyword">typename
</SPAN> <A CLASS=
"documented" HREF=
"#template_params">Access
</A> = public_
>
56 <SPAN CLASS=
"keyword">class
</SPAN> <A CLASS=
"documented" HREF=
"#template_params">filtering_stream
</A>;
58 <SPAN CLASS=
"keyword">template
</SPAN>< <SPAN CLASS=
"keyword">typename
</SPAN> <A CLASS=
"documented" HREF=
"#template_params">Mode
</A>,
59 <SPAN CLASS=
"keyword">typename
</SPAN> <A CLASS=
"documented" HREF=
"#template_params">Ch
</A> =
<SPAN CLASS=
"keyword">wchar_t
</SPAN>,
60 <SPAN CLASS=
"keyword">typename
</SPAN> <A CLASS=
"documented" HREF=
"#template_params">Tr
</A> = std::char_traits
<Ch
>,
61 <SPAN CLASS=
"keyword">typename
</SPAN> <A CLASS=
"documented" HREF=
"#template_params">Alloc
</A> = std::allocator
<<CODE>Ch
</CODE>>,
62 <SPAN CLASS=
"keyword">typename
</SPAN> <A CLASS=
"documented" HREF=
"#template_params">Access
</A> = public_
>
63 <SPAN CLASS=
"keyword">class
</SPAN> <A CLASS=
"documented" HREF=
"#filtering_wstream">filtering_wstream
</A>;
65 <SPAN CLASS=
"keyword">typedef
</SPAN> filtering_stream
<input
> <SPAN CLASS=
"defined">filtering_istream
</SPAN>;
66 <SPAN CLASS=
"keyword">typedef
</SPAN> filtering_stream
<output
> <SPAN CLASS=
"defined">filtering_ostream
</SPAN>;
67 <SPAN CLASS=
"keyword">typedef
</SPAN> filtering_wstream
<input
> <SPAN CLASS=
"defined">filtering_wistream
</SPAN>;
68 <SPAN CLASS=
"keyword">typedef
</SPAN> filtering_wstream
<output
> <SPAN CLASS=
"defined">filtering_wostream
</SPAN>;
70 <SPAN CLASS=
"keyword">template
</SPAN>< <SPAN CLASS=
"keyword">typename
</SPAN> <A CLASS=
"documented" HREF=
"#template_params">Mode
</A>,
71 <SPAN CLASS=
"keyword">typename
</SPAN> <A CLASS=
"documented" HREF=
"#template_params">Ch
</A> =
<SPAN CLASS=
"keyword">char
</SPAN>,
72 <SPAN CLASS=
"keyword">typename
</SPAN> <A CLASS=
"documented" HREF=
"#template_params">Tr
</A> = std::char_traits
<Ch
>,
73 <SPAN CLASS=
"keyword">typename
</SPAN> <A CLASS=
"documented" HREF=
"#template_params">Alloc
</A> = std::allocator
<<CODE>Ch
</CODE>>,
74 <SPAN CLASS=
"keyword">typename
</SPAN> <A CLASS=
"documented" HREF=
"#template_params">Access
</A> = public_
>
75 <SPAN CLASS=
"keyword">class
</SPAN> <A CLASS=
"documented" HREF=
"#filtering_stream">filtering_stream
</A> :
<SPAN CLASS=
"keyword">public
</SPAN> <SPAN CLASS=
"omitted">implementation-defined stream type
</SPAN> {
76 <SPAN CLASS=
"keyword">public
</SPAN>:
77 <SPAN CLASS=
"keyword">typedef
</SPAN> Ch char_type;
78 <SPAN CLASS=
"keyword">typedef
</SPAN> Mode mode;
79 <SPAN CLASS=
"keyword">typedef
</SPAN> Alloc allocator_type;
80 <SPAN CLASS=
"keyword">typedef
</SPAN> <SPAN CLASS=
"omitted">implementation-defined
</SPAN> size_type;
82 <A CLASS=
"documented" HREF=
"#default_ctor">filtering_stream
</A>();
84 <SPAN CLASS=
"keyword">template
</SPAN><<SPAN CLASS=
"keyword">typename
</SPAN> T
>
85 <A CLASS=
"documented" HREF=
"#policy_ctor">filtering_stream
</A>(
<SPAN CLASS=
"keyword">const
</SPAN> T
& t,
86 std::streamsize buffer_size =
<SPAN CLASS=
"omitted">default value
</SPAN>,
87 std::streamsize pback_size =
<SPAN CLASS=
"omitted">default value
</SPAN> );
89 <SPAN CLASS=
"keyword">template
</SPAN><<SPAN CLASS=
"keyword">typename
</SPAN> StreamOrStreambuf
>
90 <A CLASS=
"documented" HREF=
"#stream_ctor">filtering_stream
</A>( StreamOrStreambuf
& t,
91 std::streamsize buffer_size =
<SPAN CLASS=
"omitted">default value
</SPAN>,
92 std::streamsize pback_size =
<SPAN CLASS=
"omitted">default value
</SPAN> );
94 <SPAN CLASS='keyword'
>const
</SPAN> std::type_info
& <A CLASS='documented' HREF='#component_type'
>component_type
</A>(
<SPAN CLASS=
"keyword">int
</SPAN> n)
<SPAN CLASS='keyword'
>const
</SPAN>;
96 <SPAN CLASS='keyword'
>template
</SPAN><<SPAN CLASS='keyword'
>typename
</SPAN> T
>
97 T*
<A CLASS='documented' HREF='#component'
>component
</A>(
<SPAN CLASS=
"keyword">int
</SPAN> n)
<SPAN CLASS='keyword'
>const
</SPAN>;
99 <SPAN CLASS=
"keyword">template
</SPAN><<SPAN CLASS=
"keyword">typename
</SPAN> T
>
100 <SPAN CLASS=
"keyword">void
</SPAN> <A CLASS=
"documented" HREF=
"#policy_push">push
</A>(
<SPAN CLASS=
"keyword">const
</SPAN> T
& t,
101 std::streamsize buffer_size =
<SPAN CLASS=
"omitted">default value
</SPAN>,
102 std::streamsize pback_size =
<SPAN CLASS=
"omitted">default value
</SPAN> );
104 <SPAN CLASS=
"keyword">template
</SPAN><<SPAN CLASS=
"keyword">typename
</SPAN> StreamOrStreambuf
>
105 <SPAN CLASS=
"keyword">void
</SPAN> <A CLASS=
"documented" HREF=
"#stream_push">push
</A>( StreamOrStreambuf
& t,
106 std::streamsize buffer_size =
<SPAN CLASS=
"omitted">default value
</SPAN>,
107 std::streamsize pback_size =
<SPAN CLASS=
"omitted">default value
</SPAN> );
108 <SPAN CLASS=
"keyword">void
</SPAN> <A CLASS=
"documented" HREF=
"#pop">pop
</A>();
109 <SPAN CLASS=
"keyword">bool
</SPAN> <A CLASS=
"documented" HREF=
"#empty">empty
</A>()
<SPAN CLASS=
"keyword">const
</SPAN>;
110 size_type
<A CLASS=
"documented" HREF=
"#size">size
</A>()
<SPAN CLASS=
"keyword">const
</SPAN>;
111 <SPAN CLASS=
"keyword">void
</SPAN> <A CLASS=
"documented" HREF=
"#reset">reset
</A>();
112 <SPAN CLASS=
"keyword">bool
</SPAN> <A CLASS=
"documented" HREF=
"#is_complete">is_complete
</A>()
<SPAN CLASS=
"keyword">const
</SPAN>;
113 <SPAN CLASS=
"keyword">bool
</SPAN> <A CLASS=
"documented" HREF=
"#auto_close">auto_close
</A>()
<SPAN CLASS=
"keyword">const
</SPAN>;
114 <SPAN CLASS=
"keyword">void
</SPAN> <A CLASS=
"documented" HREF=
"#set_auto_close">set_auto_close
</A>(
<SPAN CLASS='keyword'
>bool
</SPAN> close);
115 <SPAN CLASS=
"keyword">bool
</SPAN> <A CLASS=
"documented" HREF=
"#sync">sync
</A>();
116 <SPAN CLASS=
"keyword">bool
</SPAN> <A CLASS=
"documented" HREF=
"#strict_sync">strict_sync
</A>();
118 <SPAN CLASS='comment'
>// Deprecated members
</SPAN>
120 <SPAN CLASS='keyword'
>template
</SPAN><<SPAN CLASS='keyword'
>int
</SPAN> N
>
121 <SPAN CLASS='keyword'
>const
</SPAN> std::type_info
& <A CLASS='documented' HREF='#component_type'
>component_type
</A>()
<SPAN CLASS='keyword'
>const
</SPAN>;
123 <SPAN CLASS='keyword'
>template
</SPAN><<SPAN CLASS='keyword'
>int
</SPAN> N,
<SPAN CLASS='keyword'
>typename
</SPAN> T
>
124 T*
<A CLASS='documented' HREF='#component'
>component
</A>()
<SPAN CLASS='keyword'
>const
</SPAN>;
127 } } // End namespace boost::io
</PRE>
129 <A NAME=
"filtering_stream"></A>
130 <H3>Class Template
<CODE>filtering_stream
</CODE></H3>
132 <A NAME=
"template_params"></A>
133 <H4>Template parameters
</H4>
135 <TABLE STYLE=
"margin-left:2em" BORDER=
0 CELLPADDING=
2>
137 <TD VALIGN=
"top"><I>Mode
</I></TD><TD WIDTH=
"2em" VALIGN=
"top">-
</TD>
138 <TD>A
<A HREF=
"../guide/modes.html#mode_tags">mode tag
</A>.
</TD>
141 <TD VALIGN=
"top"><I>Ch
</I></TD><TD WIDTH=
"2em" VALIGN=
"top">-
</TD>
142 <TD>The character type
</TD>
145 <TD VALIGN=
"top"><I>Tr
</I></TD><TD WIDTH=
"2em" VALIGN=
"top">-
</TD>
146 <TD>The traits type
</TD>
149 <TD VALIGN=
"top"><I>Alloc
</I></TD><TD WIDTH=
"2em" VALIGN=
"top">-
</TD>
150 <TD>A standard library allocator type (
<A CLASS=
"bib_ref" HREF=
"../bibliography.html#iso">[ISO]
</A>,
20.1.5), used to allocate character buffers
</TD>
153 <TD VALIGN=
"top"><I>Access
</I></TD><TD WIDTH=
"2em" VALIGN=
"top">-
</TD>
154 <TD>One of
<CODE>public_
</CODE> or
<CODE>protected_
</CODE>, indicating the level of access of the chain interface. Used to hide the chain interface when defining a derived class of
<CODE>filtering_stream
</CODE></TD>
158 <A NAME=
"default_ctor"></A>
159 <H4><CODE>filtering_stream::filtering_stream
</CODE></H4>
161 <PRE CLASS=
"broken_ie"> filtering_stream();
</PRE>
164 Constructs a
<CODE>filtering_stream
</CODE> with an empty chain of Filters and Devices.
167 <A NAME=
"policy_ctor"></A>
168 <H4><CODE>filtering_stream::filtering_stream
</CODE></H4>
169 <PRE CLASS=
"broken_ie"> <SPAN CLASS=
"keyword">template
</SPAN><<SPAN CLASS=
"keyword">typename
</SPAN> T
>
170 filtering_stream(
<SPAN CLASS=
"keyword">const
</SPAN> T
& t,
171 std::streamsize buffer_size,
172 std::streamsize pback_size );
</PRE>
174 Constructs a
<CODE>filtering_stream
</CODE> whose chain contains a copy of
<CODE>t
</CODE>. The parameters have the following interpretations:
177 <TABLE STYLE=
"margin-left:2em" BORDER=
0 CELLPADDING=
2 ID=
"Table1">
179 <TD VALIGN=
"top"><I>T
</I></TD><TD WIDTH=
"2em" VALIGN=
"top">-
</TD>
180 <TD>A
<A HREF=
"../../../../doc/html/CopyConstructible.html" TARGET=
"_top">CopyConstructible
</A> model of one of the
<A HREF=
"../guide/concepts.html#filter_concepts">Filter
</A> or
<A HREF=
"../guide/concepts.html#device_concepts">Device
</A> concepts whose
<A HREF=
"../guide/traits.html#char_type">character type
</A> is
<A HREF=
"#template_params"><CODE>Ch
</CODE></A> and whose
<A HREF=
"../guide/modes.html">mode
</A> refines
<A HREF=
"#template_params"><CODE>Mode
</CODE></A></TD>
183 <TD VALIGN=
"top"><I>t
</I></TD><TD WIDTH=
"2em" VALIGN=
"top">-
</TD>
184 <TD>An instance of
<I>T
</I></TD>
187 <TD VALIGN=
"top"><I>buffer_size
</I></TD><TD WIDTH=
"2em" VALIGN=
"top">-
</TD>
188 <TD>The size of any buffers that need to be allocated
</TD>
191 <TD VALIGN=
"top"><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=
"../guide/modes.html#input"><CODE>input
</CODE></A></TD>
197 A
<CODE>filtering_stream
</CODE> may be constructed from an instance of a Filter or Device type
<CODE>T
</CODE> which is not
<A HREF=
"../../../../doc/html/CopyConstructible.html" TARGET=
"_top">CopyConstructible
</A> in one of two ways:
200 <LI>by using a
<A HREF=
"../../../../doc/html/ref.html" TARGET=
"_top">reference wrapper
</A>, or
201 <LI>if
<CODE>T
</CODE> is a standard stream or stream buffer type, by using the constructor taking a non-
<CODE>const
</CODE> reference.
204 If T is a Device, the
<CODE>filtering_stream
</CODE> will become
<I>complete
</I> upon construction, and can then be used to perform i/o.
207 <A NAME=
"stream_ctor"></A>
208 <PRE CLASS=
"broken_ie"> <SPAN CLASS=
"keyword">template
</SPAN><<SPAN CLASS=
"keyword">typename
</SPAN> StreamOrStreambuffer
>
209 filering_stream( StreamOrStreambuffer
& t,
210 std::streamsize buffer_size,
211 std::streamsize pback_size );
</PRE>
214 Constructs a
<CODE>filtering_stream
</CODE> whose chain contains a reference to the given stream or stream buffer. The parameters have the following interpretations:
217 <TABLE STYLE=
"margin-left:2em" BORDER=
0 CELLPADDING=
2 ID=
"Table2">
219 <TD VALIGN=
"top"><I>StreamOrStreambuffer
</I></TD><TD WIDTH=
"2em" VALIGN=
"top">-
</TD>
220 <TD>A standard stream or stream buffer type whose
<A HREF=
"../guide/traits.html#char_type">character type
</A> is
<A HREF=
"#template_params"><CODE>Ch
</CODE></A> and whose
<A HREF=
"../guide/modes.html">mode
</A> refines
<A HREF=
"#template_params"><CODE>Mode
</CODE></A></TD>
223 <TD VALIGN=
"top"><I>buffer_size
</I></TD><TD WIDTH=
"2em" VALIGN=
"top">-
</TD>
224 <TD>The size of any buffers that need to be allocated
</TD>
227 <TD VALIGN=
"top"><I>pback_size
</I></TD><TD WIDTH=
"2em" VALIGN=
"top">-
</TD>
228 <TD>The size of the putback buffer, relevant only if
<CODE>Mode
</CODE> is a refinement of
<A HREF=
"../guide/modes.html#input"><CODE>input
</CODE></A></TD>
233 The
<CODE>filtering_stream
</CODE> will become
<I>complete
</I> upon construction, and can then be used to perform i/o.
236 <A NAME=
"component_type"></A>
237 <H4><CODE>filtering_stream::component_type
</CODE></H4>
239 <PRE CLASS=
"broken_ie"> <SPAN CLASS='keyword'
>const
</SPAN> std::type_info
& component_type(
<SPAN CLASS=
"keyword">int
</SPAN> n)
<SPAN CLASS='keyword'
>const
</SPAN>;
243 Returns a reference to an instance
<CODE>std::type_info
</CODE> corresponding to the type of the
<CODE>n
</CODE><I>th
</I> Filter or Device in the underlying chain, which must have size at least
<CODE>n +
1</CODE>. Components are numbered beginning at zero.
246 <PRE CLASS=
"broken_ie"> <SPAN CLASS='comment'
>// Deprecated
</SPAN>
247 <SPAN CLASS='keyword'
>template
</SPAN><<SPAN CLASS='keyword'
>int
</SPAN> N
>
248 <SPAN CLASS='keyword'
>const
</SPAN> std::type_info
& component_type()
<SPAN CLASS='keyword'
>const
</SPAN>;
252 Returns a reference to an instance
<CODE>std::type_info
</CODE> corresponding to the type of the
<CODE>N
</CODE><I>th
</I> Filter or Device in the underlying chain, which must have size at least
<CODE>N +
1</CODE>. Components are numbered beginning at zero. The template argument
<CODE>N
</CODE> cannot be deduced, and must therefore be explicitly specified.
256 <I>This member is deprecated; use the overload of
<CODE>component_type
</CODE> that takes an
<CODE>int
</CODE> argument instead.
</I>
259 <A NAME=
"component"></A>
260 <H4><CODE>filtering_stream::component
</CODE></H4>
262 <PRE CLASS=
"broken_ie"> <SPAN CLASS='keyword'
>template
</SPAN><<SPAN CLASS='keyword'
>typename
</SPAN> T
>
263 T* component(
<SPAN CLASS=
"keyword">int
</SPAN> n)
<SPAN CLASS='keyword'
>const
</SPAN>;
267 Returns a pointer to the
<CODE>n
</CODE><I>th
</I> Filter or Device in the underlying chain, if the chain has size at least
<CODE>n +
1</CODE> and the type of the
<CODE>n
</CODE><I>th
</I> Filter or Device is equal to
<CODE>T
</CODE>. Otherwise, returns a null pointer. The template argument
<CODE>T
</CODE> cannot be deduced, and must therefore be explicitly specified.
270 Users of Microsoft Visual Studio versions
6.0-
7.0 must use the macro
<A HREF='../macros/workarounds.html#boost_iostreams_component'
><CODE>BOOST_IOSTREAMS_COMPONENT
</CODE></A> instead of this function.
273 <PRE CLASS=
"broken_ie"> <SPAN CLASS='comment'
>// Deprecated
</SPAN>
274 <SPAN CLASS='keyword'
>template
</SPAN><<SPAN CLASS='keyword'
>int
</SPAN> N,
<SPAN CLASS='keyword'
>typename
</SPAN> T
>
275 T* component()
<SPAN CLASS='keyword'
>const
</SPAN>;
279 Returns a pointer to the
<CODE>N
</CODE><I>th
</I> Filter or Device in the underlying chain, if the chain has size at least
<CODE>N +
1</CODE> and the type of the
<CODE>N
</CODE><I>th
</I> Filter or Device is equal to
<CODE>T
</CODE>. Otherwise, returns a null pointer. The template arguments
<CODE>N
</CODE> and
<CODE>T
</CODE> cannot be deduced, and must therefore be explicitly specified.
282 <I>This member is deprecated; use the overload of
<CODE>component
</CODE> that takes an
<CODE>int
</CODE> argument instead.
</I>
285 <A NAME=
"policy_push"></A>
286 <H4><CODE>filtering_stream::push
</CODE></H4>
287 <PRE CLASS=
"broken_ie"> <SPAN CLASS=
"keyword">template
</SPAN><<SPAN CLASS=
"keyword">typename
</SPAN> T
>
288 void push(
<SPAN CLASS=
"keyword">const
</SPAN> T
& t,
289 std::streamsize buffer_size,
290 std::streamsize pback_size );
</PRE>
292 Appends a copy of
<CODE>t
</CODE> to the underlying chain, which must not be
<A HREF=
"#is_complete">complete
</A>. The parameters have the following interpretations:
295 <TABLE STYLE=
"margin-left:2em" BORDER=
0 CELLPADDING=
2 ID=
"Table3">
297 <TD VALIGN=
"top"><I>T
</I></TD><TD WIDTH=
"2em" VALIGN=
"top">-
</TD>
298 <TD>A
<A HREF=
"../../../../doc/html/CopyConstructible.html" TARGET=
"_top">CopyConstructible
</A> model of one of the
<A HREF=
"../guide/concepts.html#filter_concepts">Filter
</A> or
<A HREF=
"../guide/concepts.html#device_concepts">Device
</A> concepts whose
<A HREF=
"../guide/traits.html#char_type">character type
</A> is
<A HREF=
"#template_params"><CODE>Ch
</CODE></A> and whose
<A HREF=
"../guide/modes.html">mode
</A> refines
<A HREF=
"#template_params"><CODE>Mode
</CODE></A></TD>
301 <TD VALIGN=
"top"><I>t
</I></TD><TD WIDTH=
"2em" VALIGN=
"top">-
</TD>
302 <TD>An instance of
<I>T
</I></TD>
305 <TD VALIGN=
"top"><I>buffer_size
</I></TD><TD WIDTH=
"2em" VALIGN=
"top">-
</TD>
306 <TD>The size of any buffers that need to be allocated
</TD>
309 <TD VALIGN=
"top"><I>pback_size
</I></TD><TD WIDTH=
"2em" VALIGN=
"top">-
</TD>
310 <TD>The size of the putback buffer, relevant only if
<CODE>Mode
</CODE> is a refinement of
<A HREF=
"../guide/modes.html#input"><CODE>input
</CODE></A></TD>
315 An instance of a Filter or Device type
<CODE>T
</CODE> which is not
<A HREF=
"../../../../doc/html/CopyConstructible.html" TARGET=
"_top">CopyConstructible
</A> may be appended to the chain in one of two ways:
318 <LI>by using a
<A HREF=
"../../../../doc/html/ref.html" TARGET=
"_top">reference wrapper
</A>, or
319 <LI>if
<CODE>T
</CODE> is a standard stream or stream buffer type, by using the templated overload of
<A HREF=
"#stream_push"><CODE>push
</CODE></A> taking a non-
<CODE>const
</CODE> reference.
322 If T is a Device, this
<CODE>filtering_stream
</CODE> will become
<I>complete
</I> upon the return of this function, and can then be used to perform i/o.
325 <A NAME=
"stream_push"></A>
326 <PRE CLASS=
"broken_ie"> <SPAN CLASS=
"keyword">template
</SPAN><<SPAN CLASS=
"keyword">typename
</SPAN> StreamOrStreambuffer
>
327 void push( StreamOrStreambuffer
& t,
328 std::streamsize buffer_size,
329 std::streamsize pback_size );
</PRE>
332 Appends the given stream or stream buffer to the underlying chain, which must not be
<A HREF=
"#is_complete">complete
</A>. The parameters have the following interpretations:
335 <TABLE STYLE=
"margin-left:2em" BORDER=
0 CELLPADDING=
2 ID=
"Table4">
337 <TD VALIGN=
"top"><I>StreamOrStreambuffer
</I></TD><TD WIDTH=
"2em" VALIGN=
"top">-
</TD>
338 <TD>A standard stream or stream buffer type whose
<A HREF=
"../guide/traits.html#char_type">character type
</A> is
<A HREF=
"#template_params"><CODE>Ch
</CODE></A> and whose
<A HREF=
"../guide/modes.html">mode
</A> refines
<A HREF=
"#template_params"><CODE>Mode
</CODE></A></TD>
341 <TD VALIGN=
"top"><I>buffer_size
</I></TD><TD WIDTH=
"2em" VALIGN=
"top">-
</TD>
342 <TD>The size of any buffers that need to be allocated
</TD>
345 <TD VALIGN=
"top"><I>pback_size
</I></TD><TD WIDTH=
"2em" VALIGN=
"top">-
</TD>
346 <TD>The size of the putback buffer, relevant only if
<CODE>Mode
</CODE> is a refinement of
<A HREF=
"../guide/modes.html#input"><CODE>input
</CODE></A></TD>
351 This
<CODE>filtering_stream
</CODE> will become
<I>complete
</I> upon the return of this function, and can then be used to perform i/o.
355 <H4><CODE>filtering_stream::pop
</CODE></H4>
356 <PRE CLASS=
"broken_ie"> <SPAN CLASS=
"keyword">void
</SPAN> pop();
</PRE>
358 <P>Removes the final Filter or Device from the underlying chain, which must be non-empty. If the chain is initially
<A HREF=
"#is_complete">complete
</A>, causes each Filter and Device in the chain to be closed using the function
<A HREF=
"../functions/close.html"><CODE>close
</CODE></A>, unless the auto-close feature has been disabled using
<A HREF=
"#set_auto_close"><CODE>set_auto_close
</CODE></A></P>
361 <H4><CODE>filtering_stream::empty
</CODE></H4>
362 <PRE CLASS=
"broken_ie"> <SPAN CLASS=
"keyword">bool
</SPAN> empty()
<SPAN CLASS=
"keyword">const
</SPAN>;
</PRE>
364 <P>Returns
<CODE>true
</CODE> if the underlying chain is empty.
</P>
367 <H4><CODE>filtering_stream::size
</CODE></H4>
368 <PRE CLASS=
"broken_ie"> size_type size()
<SPAN CLASS=
"keyword">const
</SPAN>;
</PRE>
370 <P>Returns the number Filters and Devices in the underlying chain.
</P>
373 <H4><CODE>filtering_stream::reset
</CODE></H4>
374 <PRE CLASS=
"broken_ie"> <SPAN CLASS=
"keyword">void
</SPAN> reset();
</PRE>
376 <P>Clears the underlying chain. If the chain is initially
<A HREF=
"#is_complete">complete
</A>, causes each Filter and Device in the chain to be closed using the function
<A HREF=
"../functions/close.html"><CODE>close
</CODE></A>.
</P>
378 <A NAME=
"is_complete"></A>
379 <H4><CODE>filtering_stream::is_complete
</CODE></H4>
380 <PRE CLASS=
"broken_ie"> <SPAN CLASS=
"keyword">bool
</SPAN> is_complete()
<SPAN CLASS=
"keyword">const
</SPAN>;
</PRE>
382 <P>Returns
<CODE>true
</CODE> if the underlying chain ends in a
<A HREF=
"../concepts/device.html">Device
</A>.
</P>
384 <A NAME=
"auto_close"></A>
385 <H4><CODE>filtering_stream::auto_close
</CODE></H4>
386 <PRE CLASS=
"broken_ie"> <SPAN CLASS=
"keyword">bool
</SPAN> auto_close()
<SPAN CLASS=
"keyword">const
</SPAN>;
</PRE>
388 <P>Indicates whether the Filters and Devices in the underlying chain will be closed automatically if
<A HREF='#pop'
><CODE>pop
</CODE></A> is invoked while the chain is complete. Returns
<CODE>true
</CODE> unless the auto-close feature has been disabled using
<A HREF='#set_auto_close'
><CODE>set_auto_close
</CODE></A>.
</P>
390 <A NAME=
"set_auto_close"></A>
391 <H4><CODE>filtering_stream::set_auto_close
</CODE></H4>
392 <PRE CLASS=
"broken_ie"> <SPAN CLASS=
"keyword">void
</SPAN> set_auto_close(
<SPAN CLASS='keyword'
>bool
</SPAN> close);
</PRE>
394 <P>Specifies whether the Filters and Devices in the underlying chain will be closed automatically if
<A HREF='#pop'
><CODE>pop
</CODE></A> is invoked while the chain is complete. Does
<I>not
</I> prevent the Filters and Devices in the chain from being closed automatically if the chain is complete at destruction.
</P>
397 <H4><CODE>filtering_stream::sync
</CODE></H4>
398 <PRE CLASS=
"broken_ie"> <SPAN CLASS=
"keyword">bool
</SPAN> sync();
</PRE>
400 <P>Invokes the function
<A HREF='../functions/flush.html'
><CODE>flush
</CODE></A> on each Filter and Device in the underlying chain, which must be complete. Returns
<CODE>true
</CODE> unless at least one of these components is
<A HREF='../concepts/flushable.html'
>Flushable
</A> and
<A HREF='../functions/flush.html'
><CODE>flush
</CODE></A> returns
<CODE>false
</CODE> when invoked on that component. A return value of
<CODE>true
</CODE> indicates that no error occurred, but does
<I>not
</I> guarantee that all buffered data has been successfully forwarded.
</P>
402 <A NAME=
"strict_sync"></A>
403 <H4><CODE>filtering_stream::strict_sync
</CODE></H4>
404 <PRE CLASS=
"broken_ie"> <SPAN CLASS=
"keyword">bool
</SPAN> strict_sync();
</PRE>
406 <P>Identical to
<CODE>sync
</CODE> except for the return value, which is
<CODE>false
</CODE> unless
<I>each
</I> Filter in the underlying chain is
<A HREF='../concepts/flushable.html'
>Flushable
</A> and
<A HREF='../functions/flush.html'
><CODE>flush
</CODE></A> returns
<CODE>true
</CODE> when invoked on
<I>each
</I> component. A return value of
<CODE>true
</CODE> guarantees that all buffered data has been successfully forwarded.
</P>
408 <A NAME=
"filtering_wstream"></A>
409 <H3>Class Template
<CODE>filtering_wstream
</CODE></H3>
411 <PRE CLASS=
"broken_ie"><SPAN CLASS=
"keyword">template
</SPAN>< <SPAN CLASS=
"keyword">typename
</SPAN> Mode,
412 <SPAN CLASS=
"keyword">typename
</SPAN> Ch =
<SPAN CLASS=
"keyword">wchar_t
</SPAN>,
413 <SPAN CLASS=
"keyword">typename
</SPAN> Tr = std::char_traits
<Ch
>,
414 <SPAN CLASS=
"keyword">typename
</SPAN> Alloc = std::allocator
<<CODE>Ch
</CODE>>,
415 <SPAN CLASS=
"keyword">typename
</SPAN> Access = public_
>
416 <SPAN CLASS=
"keyword">class
</SPAN> filtering_wstream;
</PRE>
418 <P>Identical to
<CODE>filtering_stream
</CODE>, except for the default character type.
419 <!-- Begin Footer -->
423 <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>
424 <P CLASS=
"copyright">
425 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>)