]> git.proxmox.com Git - ceph.git/blame - ceph/src/boost/libs/iostreams/doc/classes/filtering_streambuf.html
projects / ceph.git / blame
? search:
summary | shortlog | log | commit | commitdiff | tree
blob | blame (incremental) | history | HEAD
bump version to 12.2.2-pve1
[ceph.git] / ceph / src / boost / libs / iostreams / doc / classes / filtering_streambuf.html
CommitLineData
7c673cae
FG		 1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
2<HTML>
3<HEAD>
4 <TITLE>Class Template filtering_streambuf</TITLE>
5 <LINK REL="stylesheet" HREF="../../../../boost.css">
6 <LINK REL="stylesheet" HREF="../theme/iostreams.css">
7</HEAD>
8<BODY>
9
10<!-- Begin Banner -->
11
12 <H1 CLASS="title">Class Template <CODE>filtering_streambuf</CODE></H1>
13 <HR CLASS="banner">
14
15<!-- End Banner -->
16
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>
21</DL>
22
23<HR>
24
25<A NAME="description"></A>
26<H2>Description</H2>
27
28<P>
29 Derived class of <CODE>std::basic_streambuf</CODE>, used to perform filtering. Each <CODE>filtering_streambuf</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_streambuf</CODE> is <I>complete</I> and can be used to perform i/o. When a <CODE>filtering_streambuf</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_streambuf</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_streambuf</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>.
30</P>
31
32<A NAME="headers"></A>
33<H2>Headers</H2>
34
35<DL class="page-index">
36 <DT><A CLASS="header" HREF="../../../../boost/iostreams/filtering_streambuf.hpp"><CODE>&lt;boost/iostreams/filtering_streambuf.hpp&gt;</CODE></A></DT>
37</DL>
38
39<A NAME="reference"></A>
40<H2>Reference</H2>
41
42<A NAME="synopsis"></A>
43<H3>Synopsis</H3>
44
45<PRE CLASS="broken_ie"><SPAN CLASS="keyword">namespace</SPAN> boost { <SPAN CLASS="keyword">namespace</SPAN> iostreams {
46
47<SPAN CLASS="keyword">template</SPAN>&lt; <SPAN CLASS="keyword">typename</SPAN> <A CLASS="documented" HREF="#template_params">Mode</A>,
48 <SPAN CLASS="keyword">typename</SPAN> <A CLASS="documented" HREF="#template_params">Ch</A> = <SPAN CLASS="keyword">char</SPAN>,
49 <SPAN CLASS="keyword">typename</SPAN> <A CLASS="documented" HREF="#template_params">Tr</A> = std::char_traits&lt;Ch&gt;,
50 <SPAN CLASS="keyword">typename</SPAN> <A CLASS="documented" HREF="#template_params">Alloc</A> = std::allocator&lt;<CODE>Ch</CODE>&gt;,
51 <SPAN CLASS="keyword">typename</SPAN> <A CLASS="documented" HREF="#template_params">Access</A> = public_ &gt;
52<SPAN CLASS="keyword">class</SPAN> <A CLASS="documented" HREF="#template_params">filtering_streambuf</A>;
53
54<SPAN CLASS="keyword">template</SPAN>&lt; <SPAN CLASS="keyword">typename</SPAN> <A CLASS="documented" HREF="#template_params">Mode</A>,
55 <SPAN CLASS="keyword">typename</SPAN> <A CLASS="documented" HREF="#template_params">Ch</A> = <SPAN CLASS="keyword">wchar_t</SPAN>,
56 <SPAN CLASS="keyword">typename</SPAN> <A CLASS="documented" HREF="#template_params">Tr</A> = std::char_traits&lt;Ch&gt;,
57 <SPAN CLASS="keyword">typename</SPAN> <A CLASS="documented" HREF="#template_params">Alloc</A> = std::allocator&lt;<CODE>Ch</CODE>&gt;,
58 <SPAN CLASS="keyword">typename</SPAN> <A CLASS="documented" HREF="#template_params">Access</A> = public_ &gt;
59<SPAN CLASS="keyword">class</SPAN> <A CLASS="documented" HREF="#filtering_wstreambuf">filtering_wstreambuf</A>;
60
61<SPAN CLASS="keyword">typedef</SPAN> filtering_streambuf&lt;input&gt; <SPAN CLASS="defined">filtering_istream</SPAN>;
62<SPAN CLASS="keyword">typedef</SPAN> filtering_streambuf&lt;output&gt; <SPAN CLASS="defined">filtering_ostream</SPAN>;
63<SPAN CLASS="keyword">typedef</SPAN> filtering_wstreambuf&lt;input&gt; <SPAN CLASS="defined">filtering_wistream</SPAN>;
64<SPAN CLASS="keyword">typedef</SPAN> filtering_wstreambuf&lt;output&gt; <SPAN CLASS="defined">filtering_wostream</SPAN>;
65
66<SPAN CLASS="keyword">template</SPAN>&lt; <SPAN CLASS="keyword">typename</SPAN> <A CLASS="documented" HREF="#template_params">Mode</A>,
67 <SPAN CLASS="keyword">typename</SPAN> <A CLASS="documented" HREF="#template_params">Ch</A> = <SPAN CLASS="keyword">char</SPAN>,
68 <SPAN CLASS="keyword">typename</SPAN> <A CLASS="documented" HREF="#template_params">Tr</A> = std::char_traits&lt;Ch&gt;,
69 <SPAN CLASS="keyword">typename</SPAN> <A CLASS="documented" HREF="#template_params">Alloc</A> = std::allocator&lt;<CODE>Ch</CODE>&gt;,
70 <SPAN CLASS="keyword">typename</SPAN> <A CLASS="documented" HREF="#template_params">Access</A> = public_ &gt;
71<SPAN CLASS="keyword">class</SPAN> <A CLASS="documented" HREF="#filtering_streambuf">filtering_streambuf</A> : <SPAN CLASS="keyword">public</SPAN> <SPAN CLASS="omitted">implementation-defined stream type</SPAN> {
72<SPAN CLASS="keyword">public</SPAN>:
73 <SPAN CLASS="keyword">typedef</SPAN> Ch char_type;
74 <SPAN CLASS="keyword">typedef</SPAN> Mode mode;
75 <SPAN CLASS="keyword">typedef</SPAN> Alloc allocator_type;
76 <SPAN CLASS="keyword">typedef</SPAN> <SPAN CLASS="omitted">implementation-defined</SPAN> size_type;
77
78 <A CLASS="documented" HREF="#default_ctor">filtering_streambuf</A>();
79
80 <SPAN CLASS="keyword">template</SPAN>&lt;<SPAN CLASS="keyword">typename</SPAN> T&gt;
81 <A CLASS="documented" HREF="#policy_ctor">filtering_streambuf</A>( <SPAN CLASS="keyword">const</SPAN> T&amp; t,
82 std::streamsize buffer_size = <SPAN CLASS="omitted">default value</SPAN>,
83 std::streamsize pback_size = <SPAN CLASS="omitted">default value</SPAN> );
84
85 <SPAN CLASS="keyword">template</SPAN>&lt;<SPAN CLASS="keyword">typename</SPAN> StreamOrStreambuf&gt;
86 <A CLASS="documented" HREF="#stream_ctor">filtering_streambuf</A>( StreamOrStreambuf&amp; t,
87 std::streamsize buffer_size = <SPAN CLASS="omitted">default value</SPAN>,
88 std::streamsize pback_size = <SPAN CLASS="omitted">default value</SPAN> );
89
90 <SPAN CLASS='keyword'>const</SPAN> std::type_info&amp; <A CLASS='documented' HREF='#component_type'>component_type</A>(<SPAN CLASS="keyword">int</SPAN> n) <SPAN CLASS='keyword'>const</SPAN>;
91
92 <SPAN CLASS='keyword'>template</SPAN>&lt;<SPAN CLASS='keyword'>typename</SPAN> T&gt;
93 T* <A CLASS='documented' HREF='#component'>component</A>(<SPAN CLASS="keyword">int</SPAN> n) <SPAN CLASS='keyword'>const</SPAN>;
94
95 <SPAN CLASS="keyword">template</SPAN>&lt;<SPAN CLASS="keyword">typename</SPAN> T&gt;
96 <SPAN CLASS="keyword">void</SPAN> <A CLASS="documented" HREF="#policy_push">push</A>( <SPAN CLASS="keyword">const</SPAN> T&amp; t,
97 std::streamsize buffer_size = <SPAN CLASS="omitted">default value</SPAN>,
98 std::streamsize pback_size = <SPAN CLASS="omitted">default value</SPAN> );
99
100 <SPAN CLASS="keyword">template</SPAN>&lt;<SPAN CLASS="keyword">typename</SPAN> StreamOrStreambuf&gt;
101 <SPAN CLASS="keyword">void</SPAN> <A CLASS="documented" HREF="#stream_push">push</A>( StreamOrStreambuf&amp; t,
102 std::streamsize buffer_size = <SPAN CLASS="omitted">default value</SPAN>,
103 std::streamsize pback_size = <SPAN CLASS="omitted">default value</SPAN> );
104 <SPAN CLASS="keyword">void</SPAN> <A CLASS="documented" HREF="#pop">pop</A>();
105 <SPAN CLASS="keyword">bool</SPAN> <A CLASS="documented" HREF="#empty">empty</A>() <SPAN CLASS="keyword">const</SPAN>;
106 size_type <A CLASS="documented" HREF="#size">size</A>() <SPAN CLASS="keyword">const</SPAN>;
107 <SPAN CLASS="keyword">void</SPAN> <A CLASS="documented" HREF="#reset">reset</A>();
108 <SPAN CLASS="keyword">bool</SPAN> <A CLASS="documented" HREF="#is_complete">is_complete</A>() <SPAN CLASS="keyword">const</SPAN>;
109 <SPAN CLASS="keyword">bool</SPAN> <A CLASS="documented" HREF="#auto_close">auto_close</A>() <SPAN CLASS="keyword">const</SPAN>;
110 <SPAN CLASS="keyword">void</SPAN> <A CLASS="documented" HREF="#set_auto_close">set_auto_close</A>(<SPAN CLASS='keyword'>bool</SPAN> close);
111 <SPAN CLASS="keyword">bool</SPAN> <A CLASS="documented" HREF="#sync">sync</A>();
112 <SPAN CLASS="keyword">bool</SPAN> <A CLASS="documented" HREF="#strict_sync">strict_sync</A>();
113
114 <SPAN CLASS='comment'>// Deprecated members</SPAN>
115
116 <SPAN CLASS='keyword'>template</SPAN>&lt;<SPAN CLASS='keyword'>int</SPAN> N&gt;
117 <SPAN CLASS='keyword'>const</SPAN> std::type_info&amp; <A CLASS='documented' HREF='#component_type'>component_type</A>() <SPAN CLASS='keyword'>const</SPAN>;
118
119 <SPAN CLASS='keyword'>template</SPAN>&lt;<SPAN CLASS='keyword'>int</SPAN> N, <SPAN CLASS='keyword'>typename</SPAN> T&gt;
120 T* <A CLASS='documented' HREF='#component'>component</A>() <SPAN CLASS='keyword'>const</SPAN>;
121};
122
123} } // End namespace boost::io</PRE>
124
125<A NAME="filtering_streambuf"></A>
126<H3>Class Template <CODE>filtering_streambuf</CODE></H3>
127
128<A NAME="template_params"></A>
129<H4>Template parameters</H4>
130
131<TABLE STYLE="margin-left:2em" BORDER=0 CELLPADDING=2>
132 <TR>
133 <TD VALIGN="top"><I>Mode</I></TD><TD WIDTH="2em" VALIGN="top">-</TD>
134 <TD>A <A HREF="../guide/modes.html#mode_tags">mode tag</A>.</TD>
135 </TR>
136 <TR>
137 <TD VALIGN="top"><I>Ch</I></TD><TD WIDTH="2em" VALIGN="top">-</TD>
138 <TD>The character type</TD>
139 </TR>
140 <TR>
141 <TD VALIGN="top"><I>Tr</I></TD><TD WIDTH="2em" VALIGN="top">-</TD>
142 <TD>The traits type</TD>
143 </TR>
144 <TR>
145 <TD VALIGN="top"><I>Alloc</I></TD><TD WIDTH="2em" VALIGN="top">-</TD>
146 <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>
147 </TR>
148 <TR>
149 <TD VALIGN="top"><I>Access</I></TD><TD WIDTH="2em" VALIGN="top">-</TD>
150 <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_streambuf</CODE></A></TD>
151 </TR>
152</TABLE>
153
154<A NAME="default_ctor"></A>
155<H4><CODE>filtering_streambuf::filtering_streambuf</CODE></H4>
156
157<PRE CLASS="broken_ie"> filtering_streambuf();</PRE>
158
159<P>
160 Constructs a <CODE>filtering_streambuf</CODE> with an empty chain of Filters and Devices.
161</P>
162
163<A NAME="policy_ctor"></A>
164<H4><CODE>filtering_streambuf::filtering_streambuf</CODE></H4>
165<PRE CLASS="broken_ie"> <SPAN CLASS="keyword">template</SPAN>&lt;<SPAN CLASS="keyword">typename</SPAN> T&gt;
166 filtering_streambuf( <SPAN CLASS="keyword">const</SPAN> T&amp; t,
167 std::streamsize buffer_size,
168 std::streamsize pback_size );</PRE>
169<P>
170 Constructs a <CODE>filtering_streambuf</CODE> whose chain contains a copy of <CODE>t</CODE>. The parameters have the following interpretations:
171</P>
172
173<TABLE STYLE="margin-left:2em" BORDER=0 CELLPADDING=2 ID="Table1">
174 <TR>
175 <TD VALIGN="top"><I>T</I></TD><TD WIDTH="2em" VALIGN="top">-</TD>
176 <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>
177 </TR>
178 <TR>
179 <TD VALIGN="top"><I>t</I></TD><TD WIDTH="2em" VALIGN="top">-</TD>
180 <TD>An instance of <I>T</I></TD>
181 </TR>
182 <TR>
183 <TD VALIGN="top"><I>buffer_size</I></TD><TD WIDTH="2em" VALIGN="top">-</TD>
184 <TD>The size of any buffers that need to be allocated</TD>
185 </TR>
186 <TR>
187 <TD VALIGN="top"><I>pback_size</I></TD><TD WIDTH="2em" VALIGN="top">-</TD>
188 <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>
189 </TR>
190</TABLE>
191
192<P>
193 A <CODE>filtering_streambuf</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:
194</P>
195<UL>
196 <LI>by using a <A HREF="../../../../doc/html/ref.html" TARGET="_top">reference wrapper</A>, or
197 <LI>if <CODE>T</CODE> is a standard stream or stream buffer type, by using the constructor taking a non-<CODE>const</CODE> reference.
198</UL>
199<P>
200 If T is a Device, the <CODE>filtering_streambuf</CODE> will become <I>complete</I> upon construction, and can then be used to perform i/o.
201</P>
202
203<A NAME="stream_ctor"></A>
204<PRE CLASS="broken_ie"> <SPAN CLASS="keyword">template</SPAN>&lt;<SPAN CLASS="keyword">typename</SPAN> StreamOrStreambuffer&gt;
205 filtering_streambuf( StreamOrStreambuffer&amp; t,
206 std::streamsize buffer_size,
207 std::streamsize pback_size );</PRE>
208
209<P>
210 Constructs a <CODE>filtering_streambuf</CODE> whose chain contains a reference to the given stream or stream buffer. The parameters have the following interpretations:
211</P>
212
213<TABLE STYLE="margin-left:2em" BORDER=0 CELLPADDING=2 ID="Table2">
214 <TR>
215 <TD VALIGN="top"><I>StreamOrStreambuffer</I></TD><TD WIDTH="2em" VALIGN="top">-</TD>
216 <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>
217 </TR>
218 <TR>
219 <TD VALIGN="top"><I>buffer_size</I></TD><TD WIDTH="2em" VALIGN="top">-</TD>
220 <TD>The size of any buffers that need to be allocated</TD>
221 </TR>
222 <TR>
223 <TD VALIGN="top"><I>pback_size</I></TD><TD WIDTH="2em" VALIGN="top">-</TD>
224 <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>
225 </TR>
226</TABLE>
227
228<P>
229 The <CODE>filtering_streambuf</CODE> will become <I>complete</I> upon construction, and can then be used to perform i/o.
230</P>
231
232<A NAME="component_type"></A>
233<H4><CODE>filtering_streambuf::component_type</CODE></H4>
234
235<PRE CLASS="broken_ie"> <SPAN CLASS='keyword'>const</SPAN> std::type_info&amp; component_type(<SPAN CLASS="keyword">int</SPAN> n) <SPAN CLASS='keyword'>const</SPAN>;
236</PRE>
237
238<P>
239 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.
240</P>
241
242<PRE CLASS="broken_ie"> <SPAN CLASS='comment'>// Deprecated</SPAN>
243 <SPAN CLASS='keyword'>template</SPAN>&lt;<SPAN CLASS='keyword'>int</SPAN> N&gt;
244 <SPAN CLASS='keyword'>const</SPAN> std::type_info&amp; component_type() <SPAN CLASS='keyword'>const</SPAN>;
245</PRE>
246
247<P>
248 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.
249</P>
250
251<P>
252 <I>This member is deprecated; use the overload of <CODE>component_type</CODE> that takes an <CODE>int</CODE> argument instead.</I>
253</P>
254
255<A NAME="component"></A>
256<H4><CODE>filtering_streambuf::component</CODE></H4>
257
258<PRE CLASS="broken_ie"> <SPAN CLASS='keyword'>template</SPAN>&lt;<SPAN CLASS='keyword'>typename</SPAN> T&gt;
259 T* component(<SPAN CLASS="keyword">int</SPAN> n) <SPAN CLASS='keyword'>const</SPAN>;
260</PRE>
261
262<P>
263 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.
264</P>
265<P>
266 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.
267</P>
268
269<PRE CLASS="broken_ie"> <SPAN CLASS='comment'>// Deprecated</SPAN>
270 <SPAN CLASS='keyword'>template</SPAN>&lt;<SPAN CLASS='keyword'>int</SPAN> N, <SPAN CLASS='keyword'>typename</SPAN> T&gt;
271 T* component() <SPAN CLASS='keyword'>const</SPAN>;
272</PRE>
273
274<P>
275 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.
276</P>
277<P>
278 <I>This member is deprecated; use the overload of <CODE>component</CODE> that takes an <CODE>int</CODE> argument instead.</I>
279</P>
280
281<A NAME="policy_push"></A>
282<H4><CODE>filtering_streambuf::push</CODE></H4>
283<PRE CLASS="broken_ie"> <SPAN CLASS="keyword">template</SPAN>&lt;<SPAN CLASS="keyword">typename</SPAN> T&gt;
284 void push( <SPAN CLASS="keyword">const</SPAN> T&amp; t,
285 std::streamsize buffer_size,
286 std::streamsize pback_size );</PRE>
287<P>
288 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:
289</P>
290
291<TABLE STYLE="margin-left:2em" BORDER=0 CELLPADDING=2 ID="Table3">
292 <TR>
293 <TD VALIGN="top"><I>T</I></TD><TD WIDTH="2em" VALIGN="top">-</TD>
294 <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>
295 </TR>
296 <TR>
297 <TD VALIGN="top"><I>t</I></TD><TD WIDTH="2em" VALIGN="top">-</TD>
298 <TD>An instance of <I>T</I></TD>
299 </TR>
300 <TR>
301 <TD VALIGN="top"><I>buffer_size</I></TD><TD WIDTH="2em" VALIGN="top">-</TD>
302 <TD>The size of any buffers that need to be allocated</TD>
303 </TR>
304 <TR>
305 <TD VALIGN="top"><I>pback_size</I></TD><TD WIDTH="2em" VALIGN="top">-</TD>
306 <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>
307 </TR>
308</TABLE>
309
310<P>
311 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:
312</P>
313<UL>
314 <LI>by using a <A HREF="../../../../doc/html/ref.html" TARGET="_top">reference wrapper</A>, or
315 <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.
316</UL>
317<P>
318 If T is a Device, this <CODE>filtering_streambuf</CODE> will become <I>complete</I> upon the return of this function, and can then be used to perform i/o.
319</P>
320
321<A NAME="stream_push"></A>
322<PRE CLASS="broken_ie"> <SPAN CLASS="keyword">template</SPAN>&lt;<SPAN CLASS="keyword">typename</SPAN> StreamOrStreambuffer&gt;
323 void push( StreamOrStreambuffer&amp; t,
324 std::streamsize buffer_size,
325 std::streamsize pback_size );</PRE>
326
327<P>
328 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:
329</P>
330
331<TABLE STYLE="margin-left:2em" BORDER=0 CELLPADDING=2 ID="Table4">
332 <TR>
333 <TD VALIGN="top"><I>StreamOrStreambuffer</I></TD><TD WIDTH="2em" VALIGN="top">-</TD>
334 <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>
335 </TR>
336 <TR>
337 <TD VALIGN="top"><I>buffer_size</I></TD><TD WIDTH="2em" VALIGN="top">-</TD>
338 <TD>The size of any buffers that need to be allocated</TD>
339 </TR>
340 <TR>
341 <TD VALIGN="top"><I>pback_size</I></TD><TD WIDTH="2em" VALIGN="top">-</TD>
342 <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>
343 </TR>
344</TABLE>
345
346<P>
347 This <CODE>filtering_streambuf</CODE> will become <I>complete</I> upon the return of this function, and can then be used to perform i/o.
348</P>
349
350<A NAME="pop"></A>
351<H4><CODE>filtering_streambuf::pop</CODE></H4>
352<PRE CLASS="broken_ie"> <SPAN CLASS="keyword">void</SPAN> pop();</PRE>
353
354<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>
355
356<A NAME="empty"></A>
357<H4><CODE>filtering_streambuf::empty</CODE></H4>
358<PRE CLASS="broken_ie"> <SPAN CLASS="keyword">bool</SPAN> empty() <SPAN CLASS="keyword">const</SPAN>;</PRE>
359
360<P>Returns <CODE>true</CODE> if the underlying chain is empty.</P>
361
362<A NAME="size"></A>
363<H4><CODE>filtering_streambuf::size</CODE></H4>
364<PRE CLASS="broken_ie"> size_type size() <SPAN CLASS="keyword">const</SPAN>;</PRE>
365
366<P>Returns the number Filters and Devices in the underlying chain.</P>
367
368<A NAME="reset"></A>
369<H4><CODE>filtering_streambuf::reset</CODE></H4>
370<PRE CLASS="broken_ie"> <SPAN CLASS="keyword">void</SPAN> reset();</PRE>
371
372<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>
373
374<A NAME="is_complete"></A>
375<H4><CODE>filtering_streambuf::is_complete</CODE></H4>
376<PRE CLASS="broken_ie"> <SPAN CLASS="keyword">bool</SPAN> is_complete() <SPAN CLASS="keyword">const</SPAN>;</PRE>
377
378<P>Returns <CODE>true</CODE> if the underlying chain ends in a <A HREF="../concepts/device.html">Device</A>. </P>
379
380<A NAME="auto_close"></A>
381<H4><CODE>filtering_streambuf::auto_close</CODE></H4>
382<PRE CLASS="broken_ie"> <SPAN CLASS="keyword">bool</SPAN> auto_close() <SPAN CLASS="keyword">const</SPAN>;</PRE>
383
384<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>
385
386<A NAME="set_auto_close"></A>
387<H4><CODE>filtering_streambuf::set_auto_close</CODE></H4>
388<PRE CLASS="broken_ie"> <SPAN CLASS="keyword">void</SPAN> set_auto_close(<SPAN CLASS='keyword'>bool</SPAN> close);</PRE>
389
390<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>
391
392<A NAME="sync"></A>
393<H4><CODE>filtering_streambuf::sync</CODE></H4>
394<PRE CLASS="broken_ie"> <SPAN CLASS="keyword">bool</SPAN> sync();</PRE>
395
396<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>
397
398<A NAME="strict_sync"></A>
399<H4><CODE>filtering_streambuf::strict_sync</CODE></H4>
400<PRE CLASS="broken_ie"> <SPAN CLASS="keyword">bool</SPAN> strict_sync();</PRE>
401
402<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>
403
404<A NAME="filtering_wstreambuf"></A>
405<H3>Class Template <CODE>filtering_wstreambuf</CODE></H3>
406
407<PRE CLASS="broken_ie"><SPAN CLASS="keyword">template</SPAN>&lt; <SPAN CLASS="keyword">typename</SPAN> Mode,
408 <SPAN CLASS="keyword">typename</SPAN> Ch = <SPAN CLASS="keyword">wchar_t</SPAN>,
409 <SPAN CLASS="keyword">typename</SPAN> Tr = std::char_traits&lt;Ch&gt;,
410 <SPAN CLASS="keyword">typename</SPAN> Alloc = std::allocator&lt;<CODE>Ch</CODE>&gt;,
411 <SPAN CLASS="keyword">typename</SPAN> Access = public_ &gt;
412<SPAN CLASS="keyword">class</SPAN> filtering_wstreambuf;</PRE>
413
414<P>Identical to <CODE>filtering_streambuf</CODE>, except for the default character type.
415<!-- Begin Footer -->
416
417<HR>
418
419<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>
420<P CLASS="copyright">
421 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>)
422</P>
423
424<!-- End Footer -->
425
426</BODY>
Ceph