ceph/src/boost/libs/iostreams/doc/classes/filtering_stream.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
   2 <HTML>
   3 <HEAD>
   4     <TITLE>Class Template filtering_stream</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_stream</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_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>.
  30 </P>
  31
  32 <P>
  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.
  34 </P>
  35
  36 <A NAME="headers"></A>
  37 <H2>Headers</H2>
  38
  39 <DL class="page-index">
  40   <DT><A CLASS="header" HREF="../../../../boost/iostreams/filtering_stream.hpp"><CODE>&lt;boost/iostreams/filtering_stream.hpp&gt;</CODE></A></DT>
  41 </DL>
  42
  43 <A NAME="reference"></A>
  44 <H2>Reference</H2>
  45
  46 <A NAME="synopsis"></A>
  47 <H3>Synopsis</H3>
  48
  49 <PRE CLASS="broken_ie"><SPAN CLASS="keyword">namespace</SPAN> boost { <SPAN CLASS="keyword">namespace</SPAN> iostreams {
  50
  51 <SPAN CLASS="keyword">template</SPAN>&lt; <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&lt;Ch&gt;,
  54           <SPAN CLASS="keyword">typename</SPAN> <A CLASS="documented" HREF="#template_params">Alloc</A>  = std::allocator&lt;<CODE>Ch</CODE>&gt;,
  55           <SPAN CLASS="keyword">typename</SPAN> <A CLASS="documented" HREF="#template_params">Access</A> = public_ &gt;
  56 <SPAN CLASS="keyword">class</SPAN> <A CLASS="documented" HREF="#template_params">filtering_stream</A>;
  57
  58 <SPAN CLASS="keyword">template</SPAN>&lt; <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&lt;Ch&gt;,
  61           <SPAN CLASS="keyword">typename</SPAN> <A CLASS="documented" HREF="#template_params">Alloc</A>  = std::allocator&lt;<CODE>Ch</CODE>&gt;,
  62           <SPAN CLASS="keyword">typename</SPAN> <A CLASS="documented" HREF="#template_params">Access</A> = public_ &gt;
  63 <SPAN CLASS="keyword">class</SPAN> <A CLASS="documented" HREF="#filtering_wstream">filtering_wstream</A>;
  64
  65 <SPAN CLASS="keyword">typedef</SPAN> filtering_stream&lt;input&gt;    <SPAN CLASS="defined">filtering_istream</SPAN>;
  66 <SPAN CLASS="keyword">typedef</SPAN> filtering_stream&lt;output&gt;   <SPAN CLASS="defined">filtering_ostream</SPAN>;
  67 <SPAN CLASS="keyword">typedef</SPAN> filtering_wstream&lt;input&gt;   <SPAN CLASS="defined">filtering_wistream</SPAN>;
  68 <SPAN CLASS="keyword">typedef</SPAN> filtering_wstream&lt;output&gt;  <SPAN CLASS="defined">filtering_wostream</SPAN>;
  69
  70 <SPAN CLASS="keyword">template</SPAN>&lt; <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&lt;Ch&gt;,
  73           <SPAN CLASS="keyword">typename</SPAN> <A CLASS="documented" HREF="#template_params">Alloc</A>  = std::allocator&lt;<CODE>Ch</CODE>&gt;,
  74           <SPAN CLASS="keyword">typename</SPAN> <A CLASS="documented" HREF="#template_params">Access</A> = public_ &gt;
  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;
  81
  82     <A CLASS="documented" HREF="#default_ctor">filtering_stream</A>();
  83
  84     <SPAN CLASS="keyword">template</SPAN>&lt;<SPAN CLASS="keyword">typename</SPAN> T&gt;
  85     <A CLASS="documented" HREF="#policy_ctor">filtering_stream</A>( <SPAN CLASS="keyword">const</SPAN> T&amp; t,
  86                       std::streamsize buffer_size = <SPAN CLASS="omitted">default value</SPAN>,
  87                       std::streamsize pback_size = <SPAN CLASS="omitted">default value</SPAN> );
  88
  89     <SPAN CLASS="keyword">template</SPAN>&lt;<SPAN CLASS="keyword">typename</SPAN> StreamOrStreambuf&gt;
  90     <A CLASS="documented" HREF="#stream_ctor">filtering_stream</A>( StreamOrStreambuf&amp; t,
  91                       std::streamsize buffer_size = <SPAN CLASS="omitted">default value</SPAN>,
  92                       std::streamsize pback_size = <SPAN CLASS="omitted">default value</SPAN> );
  93
  94     <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>;
  95
  96     <SPAN CLASS='keyword'>template</SPAN>&lt;<SPAN CLASS='keyword'>typename</SPAN> T&gt;
  97     T* <A CLASS='documented' HREF='#component'>component</A>(<SPAN CLASS="keyword">int</SPAN> n) <SPAN CLASS='keyword'>const</SPAN>;
  98
  99     <SPAN CLASS="keyword">template</SPAN>&lt;<SPAN CLASS="keyword">typename</SPAN> T&gt;
 100     <SPAN CLASS="keyword">void</SPAN> <A CLASS="documented" HREF="#policy_push">push</A>( <SPAN CLASS="keyword">const</SPAN> T&amp; t,
 101                std::streamsize buffer_size = <SPAN CLASS="omitted">default value</SPAN>,
 102                std::streamsize pback_size = <SPAN CLASS="omitted">default value</SPAN> );
 103
 104     <SPAN CLASS="keyword">template</SPAN>&lt;<SPAN CLASS="keyword">typename</SPAN> StreamOrStreambuf&gt;
 105     <SPAN CLASS="keyword">void</SPAN> <A CLASS="documented" HREF="#stream_push">push</A>( StreamOrStreambuf&amp; 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>();
 117
 118         <SPAN CLASS='comment'>// Deprecated members</SPAN>
 119
 120     <SPAN CLASS='keyword'>template</SPAN>&lt;<SPAN CLASS='keyword'>int</SPAN> N&gt;
 121     <SPAN CLASS='keyword'>const</SPAN> std::type_info&amp; <A CLASS='documented' HREF='#component_type'>component_type</A>() <SPAN CLASS='keyword'>const</SPAN>;
 122
 123     <SPAN CLASS='keyword'>template</SPAN>&lt;<SPAN CLASS='keyword'>int</SPAN> N, <SPAN CLASS='keyword'>typename</SPAN> T&gt;
 124     T* <A CLASS='documented' HREF='#component'>component</A>() <SPAN CLASS='keyword'>const</SPAN>;
 125 };
 126
 127 } } // End namespace boost::io</PRE>
 128
 129 <A NAME="filtering_stream"></A>
 130 <H3>Class Template <CODE>filtering_stream</CODE></H3>
 131
 132 <A NAME="template_params"></A>
 133 <H4>Template parameters</H4>
 134
 135 <TABLE STYLE="margin-left:2em" BORDER=0 CELLPADDING=2>
 136     <TR>
 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>
 139     </TR>
 140     <TR>
 141         <TD VALIGN="top"><I>Ch</I></TD><TD WIDTH="2em" VALIGN="top">-</TD>
 142         <TD>The character type</TD>
 143     </TR>
 144     <TR>
 145         <TD VALIGN="top"><I>Tr</I></TD><TD WIDTH="2em" VALIGN="top">-</TD>
 146         <TD>The traits type</TD>
 147     </TR>
 148     <TR>
 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>
 151     </TR>
 152     <TR>
 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>
 155     </TR>
 156 </TABLE>
 157
 158 <A NAME="default_ctor"></A>
 159 <H4><CODE>filtering_stream::filtering_stream</CODE></H4>
 160
 161 <PRE CLASS="broken_ie">    filtering_stream();</PRE>
 162
 163 <P>
 164     Constructs a <CODE>filtering_stream</CODE> with an empty chain of Filters and Devices.
 165 </P>
 166
 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>&lt;<SPAN CLASS="keyword">typename</SPAN> T&gt;
 170     filtering_stream( <SPAN CLASS="keyword">const</SPAN> T&amp; t,
 171                       std::streamsize buffer_size,
 172                       std::streamsize pback_size );</PRE>
 173 <P>
 174     Constructs a <CODE>filtering_stream</CODE> whose chain contains a copy of <CODE>t</CODE>. The parameters have the following interpretations:
 175 </P>
 176
 177 <TABLE STYLE="margin-left:2em" BORDER=0 CELLPADDING=2 ID="Table1">
 178     <TR>
 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>
 181     </TR>
 182     <TR>
 183         <TD VALIGN="top"><I>t</I></TD><TD WIDTH="2em" VALIGN="top">-</TD>
 184         <TD>An instance of <I>T</I></TD>
 185     </TR>
 186     <TR>
 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>
 189     </TR>
 190     <TR>
 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>
 193     </TR>
 194 </TABLE>
 195
 196 <P>
 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:
 198 </P>
 199 <UL>
 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.
 202 </UL>
 203 <P>
 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.
 205 </P>
 206
 207 <A NAME="stream_ctor"></A>
 208 <PRE CLASS="broken_ie">    <SPAN CLASS="keyword">template</SPAN>&lt;<SPAN CLASS="keyword">typename</SPAN> StreamOrStreambuffer&gt;
 209     filering_stream( StreamOrStreambuffer&amp; t,
 210                      std::streamsize buffer_size,
 211                      std::streamsize pback_size );</PRE>
 212
 213 <P>
 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:
 215 </P>
 216
 217 <TABLE STYLE="margin-left:2em" BORDER=0 CELLPADDING=2 ID="Table2">
 218     <TR>
 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>
 221     </TR>
 222     <TR>
 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>
 225     </TR>
 226     <TR>
 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>
 229     </TR>
 230 </TABLE>
 231
 232 <P>
 233     The <CODE>filtering_stream</CODE> will become <I>complete</I> upon construction, and can then be used to perform i/o.
 234 </P>
 235
 236 <A NAME="component_type"></A>
 237 <H4><CODE>filtering_stream::component_type</CODE></H4>
 238
 239 <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>;
 240 </PRE>
 241
 242 <P>
 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.
 244 </P>
 245
 246 <PRE CLASS="broken_ie">    <SPAN CLASS='comment'>// Deprecated</SPAN>
 247     <SPAN CLASS='keyword'>template</SPAN>&lt;<SPAN CLASS='keyword'>int</SPAN> N&gt;
 248     <SPAN CLASS='keyword'>const</SPAN> std::type_info&amp; component_type() <SPAN CLASS='keyword'>const</SPAN>;
 249 </PRE>
 250
 251 <P>
 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.
 253 </P>
 254
 255 <P>
 256       <I>This member is deprecated; use the overload of <CODE>component_type</CODE> that takes an <CODE>int</CODE> argument instead.</I>
 257 </P>
 258
 259 <A NAME="component"></A>
 260 <H4><CODE>filtering_stream::component</CODE></H4>
 261
 262 <PRE CLASS="broken_ie">    <SPAN CLASS='keyword'>template</SPAN>&lt;<SPAN CLASS='keyword'>typename</SPAN> T&gt;
 263     T* component(<SPAN CLASS="keyword">int</SPAN> n) <SPAN CLASS='keyword'>const</SPAN>;
 264 </PRE>
 265
 266 <P>
 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.
 268 </P>
 269 <P>
 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.
 271 </P>
 272
 273 <PRE CLASS="broken_ie">    <SPAN CLASS='comment'>// Deprecated</SPAN>
 274     <SPAN CLASS='keyword'>template</SPAN>&lt;<SPAN CLASS='keyword'>int</SPAN> N, <SPAN CLASS='keyword'>typename</SPAN> T&gt;
 275     T* component() <SPAN CLASS='keyword'>const</SPAN>;
 276 </PRE>
 277
 278 <P>
 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.
 280 </P>
 281 <P>
 282       <I>This member is deprecated; use the overload of <CODE>component</CODE> that takes an <CODE>int</CODE> argument instead.</I>
 283 </P>
 284
 285 <A NAME="policy_push"></A>
 286 <H4><CODE>filtering_stream::push</CODE></H4>
 287 <PRE CLASS="broken_ie">    <SPAN CLASS="keyword">template</SPAN>&lt;<SPAN CLASS="keyword">typename</SPAN> T&gt;
 288     void push( <SPAN CLASS="keyword">const</SPAN> T&amp; t,
 289                std::streamsize buffer_size,
 290                std::streamsize pback_size );</PRE>
 291 <P>
 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:
 293 </P>
 294
 295 <TABLE STYLE="margin-left:2em" BORDER=0 CELLPADDING=2 ID="Table3">
 296     <TR>
 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>
 299     </TR>
 300     <TR>
 301         <TD VALIGN="top"><I>t</I></TD><TD WIDTH="2em" VALIGN="top">-</TD>
 302         <TD>An instance of <I>T</I></TD>
 303     </TR>
 304     <TR>
 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>
 307     </TR>
 308     <TR>
 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>
 311     </TR>
 312 </TABLE>
 313
 314 <P>
 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:
 316 </P>
 317 <UL>
 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.
 320 </UL>
 321 <P>
 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.
 323 </P>
 324
 325 <A NAME="stream_push"></A>
 326 <PRE CLASS="broken_ie">    <SPAN CLASS="keyword">template</SPAN>&lt;<SPAN CLASS="keyword">typename</SPAN> StreamOrStreambuffer&gt;
 327     void push( StreamOrStreambuffer&amp; t,
 328                std::streamsize buffer_size,
 329                std::streamsize pback_size );</PRE>
 330
 331 <P>
 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:
 333 </P>
 334
 335 <TABLE STYLE="margin-left:2em" BORDER=0 CELLPADDING=2 ID="Table4">
 336     <TR>
 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>
 339     </TR>
 340     <TR>
 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>
 343     </TR>
 344     <TR>
 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>
 347     </TR>
 348 </TABLE>
 349
 350 <P>
 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.
 352 </P>
 353
 354 <A NAME="pop"></A>
 355 <H4><CODE>filtering_stream::pop</CODE></H4>
 356 <PRE CLASS="broken_ie">    <SPAN CLASS="keyword">void</SPAN> pop();</PRE>
 357
 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>
 359
 360 <A NAME="empty"></A>
 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>
 363
 364 <P>Returns <CODE>true</CODE> if the underlying chain is empty.</P>
 365
 366 <A NAME="size"></A>
 367 <H4><CODE>filtering_stream::size</CODE></H4>
 368 <PRE CLASS="broken_ie">    size_type size() <SPAN CLASS="keyword">const</SPAN>;</PRE>
 369
 370 <P>Returns the number Filters and Devices in the underlying chain.</P>
 371
 372 <A NAME="reset"></A>
 373 <H4><CODE>filtering_stream::reset</CODE></H4>
 374 <PRE CLASS="broken_ie">    <SPAN CLASS="keyword">void</SPAN> reset();</PRE>
 375
 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>
 377
 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>
 381
 382 <P>Returns <CODE>true</CODE> if the underlying chain ends in a <A HREF="../concepts/device.html">Device</A>. </P>
 383
 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>
 387
 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>
 389
 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>
 393
 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>
 395
 396 <A NAME="sync"></A>
 397 <H4><CODE>filtering_stream::sync</CODE></H4>
 398 <PRE CLASS="broken_ie">    <SPAN CLASS="keyword">bool</SPAN> sync();</PRE>
 399
 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>
 401
 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>
 405
 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>
 407
 408 <A NAME="filtering_wstream"></A>
 409 <H3>Class Template <CODE>filtering_wstream</CODE></H3>
 410
 411 <PRE CLASS="broken_ie"><SPAN CLASS="keyword">template</SPAN>&lt; <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&lt;Ch&gt;,
 414           <SPAN CLASS="keyword">typename</SPAN> Alloc  = std::allocator&lt;<CODE>Ch</CODE>&gt;,
 415           <SPAN CLASS="keyword">typename</SPAN> Access = public_ &gt;
 416 <SPAN CLASS="keyword">class</SPAN> filtering_wstream;</PRE>
 417
 418 <P>Identical to <CODE>filtering_stream</CODE>, except for the default character type.
 419 <!-- Begin Footer -->
 420
 421 <HR>
 422
 423 <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>
 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>)
 426 </P>
 427
 428 <!-- End Footer -->
 429
 430 </BODY>