Filtering Streams and Stream Buffers

Headers
Synopsis
Overview
Reference
Class template filtering_streambuf
Class template filtering_stream

Headers

<boost/iostreams/filtering_streambuf.hpp>
<boost/iostreams/filtering_stream.hpp>

Synopsis

namespace boost { namespace iostreams {

template< typename Mode,
          typename Ch = char, 
          typename Tr = std::char_traits<Ch>,
          typename Alloc = std::allocator<Ch> >
class filtering_streambuf;

template< typename Mode,
          typename Ch = char, 
          typename Tr = std::char_traits<Ch>,
          typename Alloc = std::allocator<Ch> >
class filtering_streambuf;

} } // End namespace boost::io

Overview

The class templates filtering_streambuf and filtering_stream are the fundamental components provided by the Iostreams library for filtering data. Each filtering_streambuf or filtering_stream contains a chain of instances of stream_buffer, accessed with an interface similar to that of std::stack. Each stream_buffer in the chain is based on Filter — except possibly the last, which may be based on Device. If the chain ends with a Device it is called complete and may be used to perform i/o.

The mode of each stream_buffer in the chain must refine the mode of the filtering_streambuf or filtering_stream. For example, one cannot use a Filter or Device having mode output with a filtering_streambuf having mode input.

If a filtering_streambuf or filtering_stream has mode_of input, data flows from the chain's end to its beginning — starting at a stream_buffer based on a Source and passing through zero or more stream_buffers based on InputFilters (see Figure 3). If it has mode output, data flows in the opposite direction — from the beginning of the chain, through zero or more stream_buffers based on OutputFilters, towards a stream_buffer based on a Sink at the end of the chain (see Figure 4). If a filtering_streambuf or filtering_stream performs both input and output, data flows in both directions (see Figure 5 and Figure 6).

Figure 3. Internals of a filtering_streambuf<input> (simplified)

Figure 4. Internals of a filtering_streambuf<output> (simplified)

Figure 5. Internals of a filtering_streambuf<bidirectional> (simplified)

Figure 6. Internals of a filtering_streambuf<seekable> (simplified)