User's Guide

3.4 Filtering Streams and Stream Buffers


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 zero or more Filters followed by an optional Device, accessed with an interface similar to that of std::stack. These chains are represented by of the class template chain. 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 input, data flows from the chain's end to its beginning — starting at a Source and passing through zero or more InputFilters. If it has mode output, data flows in the opposite direction — from the beginning of the chain, through zero or more OutputFilters, towards Sink at the end of the chain. If a filtering_streambuf or filtering_stream performs both input and output, data flows in both directions.