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> |