mirror of
https://github.com/boostorg/iostreams.git
synced 2026-02-23 15:52:13 +00:00
128 lines
7.2 KiB
HTML
Executable File
128 lines
7.2 KiB
HTML
Executable File
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<HTML>
|
|
<HEAD>
|
|
<TITLE>Filtering Streams and Stream Buffers</TITLE>
|
|
<LINK REL='stylesheet' HREF='../../../boost.css'>
|
|
<LINK REL='stylesheet' HREF='theme/iostreams.css'>
|
|
<STYLE>
|
|
.caption_code { font: bold 8pt monospace }
|
|
</STYLE>
|
|
</HEAD>
|
|
<BODY>
|
|
|
|
<!-- Begin Banner -->
|
|
|
|
<H1 CLASS='title'>Filtering Streams and Stream Buffers</H1>
|
|
<HR CLASS='banner'>
|
|
|
|
<!-- End Banner -->
|
|
|
|
<DL class='page-index'>
|
|
<DT><A href='#headers'>Headers</A></DT>
|
|
<DT><A href='#synopsis'>Synopsis</A></DT>
|
|
<DT><A href='#overview'>Overview</A></DT>
|
|
<DT>Reference
|
|
<DL>
|
|
<DT><A href='classes/filtering_streambuf.html'>Class template <CODE>filtering_streambuf</CODE></A></DT>
|
|
<DT><A href='classes/filtering_stream.html'>Class template <CODE>filtering_stream</CODE></A></DT>
|
|
</DL>
|
|
</DT>
|
|
</DL>
|
|
|
|
<HR>
|
|
|
|
<A NAME='headers'>
|
|
<H2>Headers</H2>
|
|
|
|
<DL class='page-index'>
|
|
<DT><A CLASS='header' HREF='../../../boost/iostreams/filtering_streambuf.hpp'><CODE><boost/iostreams/filtering_streambuf.hpp></CODE></A></DT>
|
|
<DT><A CLASS='header' HREF='../../../boost/iostreams/filtering_stream.hpp'><CODE><boost/iostreams/filtering_stream.hpp></CODE></A></DT>
|
|
</DL>
|
|
|
|
<A NAME='synopsis'>
|
|
<H2>Synopsis</H2>
|
|
|
|
<PRE CLASS='broken_ie'><SPAN CLASS="keyword">namespace</SPAN> boost { <SPAN CLASS="keyword">namespace</SPAN> iostreams {
|
|
|
|
<SPAN CLASS="keyword">template</SPAN>< <SPAN CLASS="keyword">typename</SPAN> Mode,
|
|
<SPAN CLASS="keyword">typename</SPAN> Ch = <SPAN CLASS="keyword">char</SPAN>,
|
|
<SPAN CLASS="keyword">typename</SPAN> Tr = std::char_traits<Ch>,
|
|
<SPAN CLASS="keyword">typename</SPAN> Alloc = std::allocator<Ch> >
|
|
<SPAN CLASS="keyword">class</SPAN> <A CLASS='documented' HREF="classes/filtering_streambuf.html">filtering_streambuf</A>;
|
|
|
|
<SPAN CLASS="keyword">template</SPAN>< <SPAN CLASS="keyword">typename</SPAN> Mode,
|
|
<SPAN CLASS="keyword">typename</SPAN> Ch = <SPAN CLASS="keyword">char</SPAN>,
|
|
<SPAN CLASS="keyword">typename</SPAN> Tr = std::char_traits<Ch>,
|
|
<SPAN CLASS="keyword">typename</SPAN> Alloc = std::allocator<Ch> >
|
|
<SPAN CLASS="keyword">class</SPAN> <A CLASS='documented' HREF="classes/filtering_stream.html">filtering_streambuf</A>;
|
|
<!--
|
|
<SPAN CLASS="keyword">template</SPAN>< <SPAN CLASS="keyword">typename</SPAN> Mode,
|
|
<SPAN CLASS="keyword">typename</SPAN> Ch = <SPAN CLASS="keyword">wchar_t</SPAN>,
|
|
<SPAN CLASS="keyword">typename</SPAN> Tr = std::char_traits<Ch>,
|
|
<SPAN CLASS="keyword">typename</SPAN> Alloc = std::allocator<Ch> >
|
|
<SPAN CLASS="keyword">class</SPAN> <B>wfiltering_streambuf</B>;
|
|
|
|
<SPAN CLASS="keyword">template</SPAN>< <SPAN CLASS="keyword">typename</SPAN> Mode,
|
|
<SPAN CLASS="keyword">typename</SPAN> Ch = <SPAN CLASS="keyword">wchar_t</SPAN>,
|
|
<SPAN CLASS="keyword">typename</SPAN> Tr = std::char_traits<Ch>,
|
|
<SPAN CLASS="keyword">typename</SPAN> Alloc = std::allocator<Ch> >
|
|
<SPAN CLASS="keyword">class</SPAN> <B>wfiltering_streambuf</B>;
|
|
-->
|
|
} } <SPAN CLASS="comment">// End namespace boost::io</SPAN></PRE>
|
|
|
|
<A NAME='overview'>
|
|
<H2>Overview</H2>
|
|
|
|
<P>
|
|
The class templates <A HREF="classes/filtering_streambuf.html"><CODE>filtering_streambuf</CODE></A> and <A HREF="classes/filtering_stream.html"><CODE>filtering_stream</CODE></A> are the fundamental components provided by the Iostreams Library for filtering data. Each <CODE>filtering_streambuf</CODE> or <CODE>filtering_stream</CODE> contains a chain of instances of <A HREF='policy_based_streams.html'><CODE>streambuf_facade</CODE></A>, accessed with an interface similar to that of <CODE>std::stack</CODE>. Each <CODE>streambuf_facade</CODE> in the chain is based on <A HREF="concepts.html#filter_concepts">Filter</A> — except possibly the last, which may be based on <A HREF="concepts.html#device_concepts">Device</A>. If the chain ends with a Device it is called <SPAN CLASS='term'>complete</SPAN> and may be used to perform i/o.
|
|
</P>
|
|
<P>
|
|
The <A HREF="modes.html">i/o mode</A> of each <CODE>streambuf_facade</CODE> in the chain must refine the mode of the <CODE>filtering_streambuf</CODE> or <CODE>filtering_stream</CODE>. For example, one cannot use a Filter or Device having mode <A HREF="modes.html#output">output</A> with a <CODE>filtering_streambuf</CODE> having mode <A HREF="modes.html#input">input</A>.
|
|
</P>
|
|
<P>
|
|
If a <CODE>filtering_streambuf</CODE> or <CODE>filtering_stream</CODE> has <CODE>io_mode</CODE> <A HREF="modes.html#input">input</A>, data flows from the chain's end to its beginning — starting at a <CODE>streambuf_facade</CODE> based on a <A HREF="concepts/source.html">Source</A> and passing through zero or more <CODE>streambuf_facades</CODE> based on <A HREF="concepts/input_filter.html">InputFilters</A> (<I>see </I> <A CLASS='caption_ref' HREF='#figure_3'>Figure 3</A>). If it has mode <A HREF="modes.html#output">output</A>, data flows in the opposite direction — from the beginning of the chain, through zero or more <CODE>streambuf_facades</CODE> based on <A HREF="concepts/output_filter.html">OutputFilters</A>, towards a <CODE>streambuf_facade</CODE> based on a <A HREF="concepts/source.html">Sink</A> at the end of the chain (<I>see </I> <A CLASS='caption_ref' HREF='#figure_4'>Figure 4</A>). If a <CODE>filtering_streambuf</CODE> or <CODE>filtering_stream</CODE> performs both input and output, data flows in both directions (<I>see </I> <A CLASS='caption_ref' HREF='#figure_5'>Figure 5</A> and <A CLASS='caption_ref' HREF='#figure_5'>Figure 6</A>).
|
|
|
|
<TABLE STYLE='margin:2em,2em' CELLSPACING=10>
|
|
<TR>
|
|
<TD VALIGN='top'>
|
|
<A NAME='figure_3'></A><P CLASS='caption'><B>Figure 3.</B> Internals of a <SPAN CLASS='caption_code'>filtering_streambuf<input></SPAN> (simplified)</P>
|
|
<IMG SRC='graphics/input_chain.gif'>
|
|
</TD>
|
|
</TR>
|
|
<TR>
|
|
<TD VALIGN='top'>
|
|
<A NAME='figure_4'></A><P CLASS='caption'><B>Figure 4.</B> Internals of a <SPAN CLASS='caption_code'>filtering_streambuf<output></SPAN> (simplified)</P>
|
|
<IMG SRC='graphics/output_chain.gif'>
|
|
</TD>
|
|
</TR>
|
|
<TR>
|
|
<TD VALIGN='top'>
|
|
<A NAME='figure_5'></A><P CLASS='caption'><B>Figure 5.</B> Internals of a <SPAN CLASS='caption_code'>filtering_streambuf<bidirectional></SPAN> (simplified)</P>
|
|
<IMG SRC='graphics/bidirectional_chain.gif'>
|
|
</TD>
|
|
</TR>
|
|
<TR>
|
|
<TD VALIGN='top'>
|
|
<A NAME='figure_6'></A><P CLASS='caption'><B>Figure 6.</B> Internals of a <SPAN CLASS='caption_code'>filtering_streambuf<seekable></SPAN> (simplified)</P>
|
|
<IMG SRC='graphics/seekable_chain.gif'>
|
|
</TD>
|
|
</TR>
|
|
</TABLE>
|
|
|
|
<!-- Begin Footer -->
|
|
|
|
<HR>
|
|
<P CLASS='copyright'>Revised
|
|
<!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->
|
|
20 May, 2004
|
|
<!--webbot bot="Timestamp" endspan i-checksum="38504" -->
|
|
</P>
|
|
|
|
<P CLASS='copyright'>© Copyright Jonathan Turkanis, 2004</P>
|
|
<P CLASS='copyright'>
|
|
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>)
|
|
</P>
|
|
|
|
<!-- End Footer -->
|
|
|
|
</BODY> |