libs/iostreams/doc/classes/chain.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
   2 <HTML>
   3 <HEAD>
   4     <TITLE>Class Template chain</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>chain</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     Chains are used by <A HREF='../guide/filtering_streams.html'>filtering streams and stream buffers</A> to manage their underlying sequence of Filters and Devices. A chain represents a sequence of zero or more Filters with an optional Device at the end. If a chain contains a Device, it is considered <I>complete</I> and can be used to perform i/o. When a chain 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 chain 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 a chain is popped or if a chain 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 <P>
  32     The class template <CODE>chain</CODE> is parameterized by a <A HREF='../guide/modes.html'>mode</A>. All the Filters and Devices which constitute a chain must have modes which refine the mode of the chain. For example, the class <CODE>chain&lt;input&gt;</CODE> has mode <A HREF="../guide/modes.html#input">input</A>. All <A HREF="../concepts/filter.html">Filters</A> pushed onto such a chain must at least be <A HREF="../concepts/input_filter.html">InputFilters</A>. Any <A HREF="../concepts/device.html">Device</A> pushed onto such a chain must at least be a <A HREF="../concepts/source.html">Source</A>.
  33 </P>
  34 <P>
  35     Chains are <A HREF='../../../../doc/html/CopyConstructible.html' TARGET='_top'>CopyConstructible</A> and <A HREF='../../../../doc/html/Assignable.html' TARGET='_top'>Assignable</A>. A copy of a chain represents the same sequence of Filters and Devices as the original chain; the components are not copied.
  36 </P>
  37
  38 <A NAME="headers"></A>
  39 <H2>Headers</H2>
  40
  41 <DL class="page-index">
  42   <DT><A CLASS="header" HREF="../../../../boost/iostreams/chain.hpp"><CODE>&lt;boost/iostreams/chain.hpp&gt;</CODE></A></DT>
  43 </DL>
  44
  45 <A NAME="reference"></A>
  46 <H2>Reference</H2>
  47
  48 <A NAME="synopsis"></A>
  49 <H4>Synopsis</H4>
  50
  51 <PRE CLASS="broken_ie"><SPAN CLASS="keyword">namespace</SPAN> boost { <SPAN CLASS="keyword">namespace</SPAN> iostreams {
  52
  53 <SPAN CLASS="keyword">template</SPAN>&lt; <SPAN CLASS="keyword">typename</SPAN> <A CLASS="documented" HREF="#template_params">Mode</A>,
  54           <SPAN CLASS="keyword">typename</SPAN> <A CLASS="documented" HREF="#template_params">Ch</A>    = <SPAN CLASS="keyword">char</SPAN>,
  55           <SPAN CLASS="keyword">typename</SPAN> <A CLASS="documented" HREF="#template_params">Tr</A>    = std::char_traits&lt;Ch&gt;,
  56           <SPAN CLASS="keyword">typename</SPAN> <A CLASS="documented" HREF="#template_params">Alloc</A> = std::allocator&lt;<CODE>Ch</CODE>&gt; &gt;
  57 <SPAN CLASS="keyword">class</SPAN> <A CLASS="documented" HREF="#chain">chain</A>;
  58
  59 <SPAN CLASS="keyword">template</SPAN>&lt; <SPAN CLASS="keyword">typename</SPAN> <A CLASS="documented" HREF="#template_params">Mode</A>,
  60           <SPAN CLASS="keyword">typename</SPAN> <A CLASS="documented" HREF="#template_params">Ch</A>    = <SPAN CLASS="keyword">wchar_t</SPAN>,
  61           <SPAN CLASS="keyword">typename</SPAN> <A CLASS="documented" HREF="#template_params">Tr</A>    = std::char_traits&lt;Ch&gt;,
  62           <SPAN CLASS="keyword">typename</SPAN> <A CLASS="documented" HREF="#template_params">Alloc</A> = std::allocator&lt;<CODE>Ch</CODE>&gt; &gt;
  63 <SPAN CLASS="keyword">class</SPAN> <A CLASS="documented" HREF="#wchain">wchain</A>;
  64
  65 <SPAN CLASS="keyword">template</SPAN>&lt; <SPAN CLASS="keyword">typename</SPAN> <A CLASS="documented" HREF="#template_params">Mode</A>,
  66           <SPAN CLASS="keyword">typename</SPAN> <A CLASS="documented" HREF="#template_params">Ch</A>    = <SPAN CLASS="keyword">char</SPAN>,
  67           <SPAN CLASS="keyword">typename</SPAN> <A CLASS="documented" HREF="#template_params">Tr</A>    = std::char_traits&lt;Ch&gt;,
  68           <SPAN CLASS="keyword">typename</SPAN> <A CLASS="documented" HREF="#template_params">Alloc</A> = std::allocator&lt;<CODE>Ch</CODE>&gt; &gt;
  69 <SPAN CLASS="keyword">class</SPAN> <A CLASS="documented" HREF="chain.html">chain</A> : <SPAN CLASS="keyword">public</SPAN> <SPAN CLASS="omitted">implementation-defined stream type</SPAN> {
  70 <SPAN CLASS="keyword">public</SPAN>:
  71     <SPAN CLASS="keyword">typedef</SPAN> Ch                      char_type;
  72     <SPAN CLASS="keyword">typedef</SPAN> Tr                      traits_type;
  73     <SPAN CLASS="keyword">typedef</SPAN> Mode                    mode;
  74     <SPAN CLASS="keyword">typedef</SPAN> Alloc                   allocator_type;
  75     <SPAN CLASS="keyword">typedef</SPAN> <SPAN CLASS="omitted">implementation-defined</SPAN>  size_type;
  76
  77     <A CLASS="documented" HREF="#default_constructor">chain</A>();
  78     <A CLASS="documented" HREF="#copy_constructor">chain</A>(<SPAN CLASS='keyword'>const</SPAN> chain&amp;);
  79
  80     std::streamsize <A CLASS='documented' HREF='#read'>read</A>(char_type* s, std::streamsize n);
  81     std::streamsize <A CLASS='documented' HREF='#write'>write</A>(<SPAN CLASS='keyword'>const</SPAN> char_type* s, std::streamsize n);
  82     <A CLASS='documented' HREF='../functions/positioning.html#synopsis'>stream_offset</A> <A CLASS='documented' HREF='#seek'>seek</A>(<A CLASS='documented' HREF='../functions/positioning.html#synopsis'>stream_offset</A> off, std::ios_base::seekdir way);
  83
  84     <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>;
  85
  86     <SPAN CLASS='keyword'>template</SPAN>&lt;<SPAN CLASS='keyword'>typename</SPAN> T&gt;
  87     T* <A CLASS='documented' HREF='#component'>component</A>(<SPAN CLASS="keyword">int</SPAN> n) <SPAN CLASS='keyword'>const</SPAN>;
  88
  89     <SPAN CLASS="keyword">template</SPAN>&lt;<SPAN CLASS="keyword">typename</SPAN> T&gt;
  90     <SPAN CLASS="keyword">void</SPAN> <A CLASS="documented" HREF="#policy_push">push</A>( <SPAN CLASS="keyword">const</SPAN> T&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">template</SPAN>&lt;<SPAN CLASS="keyword">typename</SPAN> StreamOrStreambuf&gt;
  95     <SPAN CLASS="keyword">void</SPAN> <A CLASS="documented" HREF="#stream_push">push</A>( StreamOrStreambuf&amp; t,
  96                std::streamsize buffer_size = <SPAN CLASS="omitted">default value</SPAN>,
  97                std::streamsize pback_size = <SPAN CLASS="omitted">default value</SPAN> );
  98
  99     <SPAN CLASS="keyword">void</SPAN> <A CLASS="documented" HREF="#pop">pop</A>();
 100     <SPAN CLASS="keyword">bool</SPAN> <A CLASS="documented" HREF="#empty">empty</A>() <SPAN CLASS="keyword">const</SPAN>;
 101     size_type <A CLASS="documented" HREF="#size">size</A>() <SPAN CLASS="keyword">const</SPAN>;
 102     <SPAN CLASS="keyword">void</SPAN> <A CLASS="documented" HREF="#reset">reset</A>();
 103     <SPAN CLASS="keyword">bool</SPAN> <A CLASS="documented" HREF="#is_complete">is_complete</A>() <SPAN CLASS="keyword">const</SPAN>;
 104     <SPAN CLASS="keyword">bool</SPAN> <A CLASS="documented" HREF="#auto_close">auto_close</A>() <SPAN CLASS="keyword">const</SPAN>;
 105     <SPAN CLASS="keyword">void</SPAN> <A CLASS="documented" HREF="#set_auto_close">set_auto_close</A>(<SPAN CLASS='keyword'>bool</SPAN> close);
 106     <SPAN CLASS="keyword">bool</SPAN> <A CLASS="documented" HREF="#sync">sync</A>();
 107     <SPAN CLASS="keyword">bool</SPAN> <A CLASS="documented" HREF="#strict_sync">strict_sync</A>();
 108
 109         <SPAN CLASS='comment'>// Deprecated members</SPAN>
 110
 111     <SPAN CLASS='keyword'>template</SPAN>&lt;<SPAN CLASS='keyword'>int</SPAN> N&gt;
 112     <SPAN CLASS='keyword'>const</SPAN> std::type_info&amp; <A CLASS='documented' HREF='#component_type'>component_type</A>() <SPAN CLASS='keyword'>const</SPAN>;
 113
 114     <SPAN CLASS='keyword'>template</SPAN>&lt;<SPAN CLASS='keyword'>int</SPAN> N, <SPAN CLASS='keyword'>typename</SPAN> T&gt;
 115     T* <A CLASS='documented' HREF='#component'>component</A>() <SPAN CLASS='keyword'>const</SPAN>;
 116 };
 117
 118 } } // End namespace boost::io</PRE>
 119
 120 <A NAME="chain"></A>
 121 <H2>Class Template <CODE>chain</CODE></H2>
 122
 123 <A NAME="template_params"></A>
 124 <H4>Template parameters</H4>
 125
 126 <TABLE STYLE="margin-left:2em" BORDER=0 CELLPADDING=2>
 127 <TR>
 128     <TR>
 129         <TD VALIGN="top"><I>Mode</I></TD><TD WIDTH="2em" VALIGN="top">-</TD>
 130         <TD>A <A HREF="../guide/modes.html#mode_tags">mode tag</A>.</TD>
 131     </TR>
 132     <TR>
 133         <TD VALIGN="top"><I>Ch</I></TD><TD WIDTH="2em" VALIGN="top">-</TD>
 134         <TD>The character type</TD>
 135     </TR>
 136     <TR>
 137         <TD VALIGN="top"><I>Tr</I></TD><TD WIDTH="2em" VALIGN="top">-</TD>
 138         <TD>The traits type</TD>
 139     </TR>
 140     <TR>
 141         <TD VALIGN="top"><I>Alloc</I></TD><TD WIDTH="2em" VALIGN="top">-</TD>
 142         <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>
 143     </TR>
 144 </TABLE>
 145
 146 <A NAME="default_constructor"></A>
 147 <H4><CODE>chain::chain</CODE></H4>
 148
 149 <PRE CLASS="broken_ie">    chain();</PRE>
 150
 151 <P>
 152     Constructs a <CODE>chain</CODE> with an empty chain of Filters and Devices.
 153 </P>
 154
 155 <A NAME="copy_constructor"></A>
 156 <H4><CODE>chain::chain</CODE></H4>
 157
 158 <PRE CLASS="broken_ie">    chain(<SPAN CLASS='keyword'>const</SPAN> chain&amp; rhs);</PRE>
 159
 160 <P>
 161     Constructs a <CODE>chain</CODE> representing the same sequence of Filters and Devices as the given chain.
 162 </P>
 163
 164 <A NAME="read"></A>
 165 <H4><CODE>chain::read</CODE></H4>
 166
 167 <PRE CLASS="broken_ie">    std::streamsize read(char_type* s, std::streamsize n);</PRE>
 168
 169 <P>
 170       Invokes <A HREF='../functions/read.html'><CODE>read</CODE></A> on the first filter or device in this chain, which must be non-empty.
 171 </P>
 172
 173 <A NAME="write"></A>
 174 <H4><CODE>chain::write</CODE></H4>
 175
 176 <PRE CLASS="broken_ie">    std::streamsize write(<SPAN CLASS='keyword'>const</SPAN> char_type* s, std::streamsize n);</PRE>
 177
 178 <P>
 179       Invokes <A HREF='../functions/write.html'><CODE>write</CODE></A> on the first filter or device in this chain, which must be non-empty.
 180 </P>
 181
 182 <A NAME="seek"></A>
 183 <H4><CODE>chain::seek</CODE></H4>
 184
 185 <PRE CLASS="broken_ie">    <A CLASS='documented' HREF='../functions/positioning.html#synopsis'>stream_offset</A> seek(<A CLASS='documented' HREF='../functions/positioning.html#synopsis'>stream_offset</A> off, std::ios_base::seekdir way);
 186 </PRE>
 187
 188 <P>
 189       Invokes <A HREF='../functions/seek.html'><CODE>seek</CODE></A> on the first filter or device in this chain, which must be non-empty.
 190 </P>
 191
 192 <A NAME="component_type"></A>
 193 <H4><CODE>chain::component_type</CODE></H4>
 194
 195 <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>;
 196 </PRE>
 197
 198 <P>
 199       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 this chain, which must have size at least <CODE>n + 1</CODE>. Components are numbered beginning at zero.
 200 </P>
 201
 202 <PRE CLASS="broken_ie">    <SPAN CLASS='comment'>// Deprecated</SPAN>
 203     <SPAN CLASS='keyword'>template</SPAN>&lt;<SPAN CLASS='keyword'>int</SPAN> N&gt;
 204     <SPAN CLASS='keyword'>const</SPAN> std::type_info&amp; component_type() <SPAN CLASS='keyword'>const</SPAN>;
 205 </PRE>
 206
 207 <P>
 208       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 this 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.
 209 </P>
 210
 211 <P>
 212       <I>This member is deprecated; use the overload of <CODE>component_type</CODE> that takes an <CODE>int</CODE> argument instead.</I>
 213 </P>
 214
 215 <A NAME="component"></A>
 216 <H4><CODE>chain::component</CODE></H4>
 217
 218 <PRE CLASS="broken_ie">    <SPAN CLASS='keyword'>template</SPAN>&lt;<SPAN CLASS='keyword'>typename</SPAN> T&gt;
 219     T* component(<SPAN CLASS="keyword">int</SPAN> n) <SPAN CLASS='keyword'>const</SPAN>;
 220 </PRE>
 221
 222 <P>
 223       Returns a pointer to the <CODE>n</CODE><I>th</I> Filter or Device in this chain, if this 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.
 224 </P>
 225 <P>
 226       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.
 227 </P>
 228
 229 <PRE CLASS="broken_ie">    <SPAN CLASS='comment'>// Deprecated</SPAN>
 230     <SPAN CLASS='keyword'>template</SPAN>&lt;<SPAN CLASS='keyword'>int</SPAN> N, <SPAN CLASS='keyword'>typename</SPAN> T&gt;
 231     T* component() <SPAN CLASS='keyword'>const</SPAN>;
 232 </PRE>
 233
 234 <P>
 235       Returns a pointer to the <CODE>N</CODE><I>th</I> Filter or Device in this chain, if this 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.
 236 </P>
 237 <P>
 238       <I>This member is deprecated; use the overload of <CODE>component</CODE> that takes an <CODE>int</CODE> argument instead.</I>
 239 </P>
 240
 241 <A NAME="policy_push"></A>
 242 <H4><CODE>chain::push</CODE></H4>
 243 <PRE CLASS="broken_ie">    <SPAN CLASS="keyword">template</SPAN>&lt;<SPAN CLASS="keyword">typename</SPAN> T&gt;
 244     void push( <SPAN CLASS="keyword">const</SPAN> T&amp; t,
 245                std::streamsize buffer_size,
 246                std::streamsize pback_size );</PRE>
 247 <P>
 248     Appends a copy of <CODE>t</CODE> to this chain, which must not be <A HREF="#is_complete">complete</A>. The parameters have the following interpretations:
 249 </P>
 250
 251 <TABLE STYLE="margin-left:2em" BORDER=0 CELLPADDING=2 ID="Table3">
 252 <TR>
 253     <TR>
 254         <TD VALIGN="top"><I>T</I></TD><TD WIDTH="2em" VALIGN="top">-</TD>
 255         <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>
 256     </TR>
 257     <TR>
 258         <TD VALIGN="top"><I>t</I></TD><TD WIDTH="2em" VALIGN="top">-</TD>
 259         <TD>An instance of <I>T</I></TD>
 260     </TR>
 261     <TR>
 262         <TD VALIGN="top"><I>buffer_size</I></TD><TD WIDTH="2em" VALIGN="top">-</TD>
 263         <TD>The size of any buffers that need to be allocated</TD>
 264     </TR>
 265     <TR>
 266         <TD VALIGN="top"><I>pback_size</I></TD><TD WIDTH="2em" VALIGN="top">-</TD>
 267         <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></TD>
 268     </TR>
 269 </TABLE>
 270
 271 <P>
 272     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:
 273 </P>
 274 <UL>
 275     <LI>by using a <A HREF="../../../../doc/html/ref.html" TARGET="_top">reference wrapper</A>, or
 276     <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.
 277 </UL>
 278 <P>
 279     If T is a Device, this chain will become <I>complete</I> upon the return of this function, and can then be used to perform i/o.
 280 </P>
 281
 282 <A NAME="stream_push"></A>
 283 <PRE CLASS="broken_ie">    <SPAN CLASS="keyword">template</SPAN>&lt;<SPAN CLASS="keyword">typename</SPAN> StreamOrStreambuffer&gt;
 284     void push( StreamOrStreambuffer&amp; t,
 285                std::streamsize buffer_size,
 286                std::streamsize pback_size );</PRE>
 287
 288 <P>
 289     Appends the given stream or stream buffer to this chain, which must not be <A HREF="#is_complete">complete</A>. The parameters have the following interpretations:
 290 </P>
 291
 292 <TABLE STYLE="margin-left:2em" BORDER=0 CELLPADDING=2 ID="Table4">
 293 <TR>
 294     <TR>
 295         <TD VALIGN="top"><I>StreamOrStreambuffer</I></TD><TD WIDTH="2em" VALIGN="top">-</TD>
 296         <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>
 297     </TR>
 298     <TR>
 299         <TD VALIGN="top"><I>buffer_size</I></TD><TD WIDTH="2em" VALIGN="top">-</TD>
 300         <TD>The size of any buffers that need to be allocated</TD>
 301     </TR>
 302     <TR>
 303         <TD VALIGN="top"><I>pback_size</I></TD><TD WIDTH="2em" VALIGN="top">-</TD>
 304         <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></TD>
 305     </TR>
 306 </TABLE>
 307
 308 <P>
 309     This chain will become <I>complete</I> upon the return of this function, and can then be used to perform i/o.
 310 </P>
 311
 312 <A NAME="pop"></A>
 313 <H4><CODE>chain::pop</CODE></H4>
 314 <PRE CLASS="broken_ie">    <SPAN CLASS="keyword">void</SPAN> pop();</PRE>
 315
 316 <P>Removes the final Filter or Device from this chain, which must be non-empty. If this chain is  <A HREF="#is_complete">complete</A>, <CODE>pop</CODE> 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_clos</CODE></A>.</P>
 317
 318 <A NAME="empty"></A>
 319 <H4><CODE>chain::empty</CODE></H4>
 320 <PRE CLASS="broken_ie">    <SPAN CLASS="keyword">bool</SPAN> empty() <SPAN CLASS="keyword">const</SPAN>;</PRE>
 321
 322 <P>Returns <CODE>true</CODE> if this chain contains no Filters or Devices.</P>
 323
 324 <A NAME="size"></A>
 325 <H4><CODE>chain::size</CODE></H4>
 326 <PRE CLASS="broken_ie">    size_type size() <SPAN CLASS="keyword">const</SPAN>;</PRE>
 327
 328 <P>Returns the number of Filters and Devices in this chain.</P>
 329
 330 <A NAME="reset"></A>
 331 <H4><CODE>chain::reset</CODE></H4>
 332 <PRE CLASS="broken_ie">    <SPAN CLASS="keyword">void</SPAN> reset();</PRE>
 333
 334 <P>Clears this chain. If this chain is <A HREF="#is_complete">complete</A>, <CODE>reset</CODE> causes each Filter and Device in the chain to be closed using the function <A HREF="../functions/close.html"><CODE>close</CODE></A>, regardless of whether the auto-close feature has been disabled using <A HREF='#set_auto_close'><CODE>set_auto_close</CODE></A>.</P></P>
 335
 336 <A NAME="is_complete"></A>
 337 <H4><CODE>chain::is_complete</CODE></H4>
 338 <PRE CLASS="broken_ie">    <SPAN CLASS="keyword">bool</SPAN> is_complete() <SPAN CLASS="keyword">const</SPAN>;</PRE>
 339
 340 <P>Returns <CODE>true</CODE> if this chain contains a <A HREF="../concepts/device.html">Device</A>. A chain is complete if and only if it is capable of performing i/o.</P>
 341
 342 <A NAME="auto_close"></A>
 343 <H4><CODE>chain::auto_close</CODE></H4>
 344 <PRE CLASS="broken_ie">    <SPAN CLASS="keyword">bool</SPAN> auto_close() <SPAN CLASS="keyword">const</SPAN>;</PRE>
 345
 346 <P>Indicates whether the Filters and Devices in this 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>
 347
 348 <A NAME="set_auto_close"></A>
 349 <H4><CODE>chain::set_auto_close</CODE></H4>
 350 <PRE CLASS="broken_ie">    <SPAN CLASS="keyword">void</SPAN> set_auto_close(<SPAN CLASS='keyword'>bool</SPAN> close);</PRE>
 351
 352 <P>Specifies whether the Filters and Devices in this chain will be closed automatically if <A HREF='#pop'><CODE>pop</CODE></A> is invoked while the chain is complete. Does not prevent the Filters and Devices in this chain from being closed automatically if the chain is complete at destruction.</P>
 353
 354 <A NAME="sync"></A>
 355 <H4><CODE>chain::sync</CODE></H4>
 356 <PRE CLASS="broken_ie">    <SPAN CLASS="keyword">bool</SPAN> sync();</PRE>
 357
 358 <P>Invokes the function <A HREF='../functions/flush.html'><CODE>flush</CODE></A> on each Filter and Device in this 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>
 359
 360 <A NAME="strict_sync"></A>
 361 <H4><CODE>chain::strict_sync</CODE></H4>
 362 <PRE CLASS="broken_ie">    <SPAN CLASS="keyword">bool</SPAN> strict_sync();</PRE>
 363
 364 <P>Identical to <CODE>sync</CODE> except for the return value, which is <CODE>false</CODE> unless <I>each</I> Filter in this 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>
 365
 366 <A NAME="wchain"></A>
 367 <H2>Class Template <CODE>wchain</CODE></H2>
 368
 369
 370 <PRE CLASS="broken_ie"><SPAN CLASS="keyword">template</SPAN>&lt; <SPAN CLASS="keyword">typename</SPAN> Mode,
 371           <SPAN CLASS="keyword">typename</SPAN> Ch    = <SPAN CLASS="keyword">wchar_t</SPAN>,
 372           <SPAN CLASS="keyword">typename</SPAN> Tr    = std::char_traits&lt;Ch&gt;,
 373           <SPAN CLASS="keyword">typename</SPAN> Alloc = std::allocator&lt;<CODE>Ch</CODE>&gt; &gt;
 374 <SPAN CLASS="keyword">class</SPAN> wchain;</PRE>
 375
 376 <P>Identical to <CODE>chain</CODE>, except for the default character type.
 377
 378 <!-- Begin Footer -->
 379
 380 <HR>
 381
 382 <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>
 383 <P CLASS="copyright">
 384     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>)
 385 </P>
 386
 387 <!-- End Footer -->
 388
 389 </BODY>