A Filter operates on the character sequence or sequences controlled by a Device, providing access to a filtered input sequence, output sequence or both. Informally, when a Filter f is used in conjunction with a Device d, data read from the input sequence of d is processed by f before being returned to the user, data written to the output sequence of d is first processed by f, and repositioning operations are processed by f before being conveyed to d. 
    Filters are class types which define one or more member functions get, put, read, write and seek; each function takes a reference to a Device as its first argument. Whenever a Filter is used to perform an i/o operation, a reference to the Device being filtered is passed to the Filter as a function argument.
    Each Filter type has an associated character type and category. The character type is the type of the characters in the input and output sequences. The category is a tag structure which the Iostreams library relies on to determine which operations the Filter type supports. Its function is similar to the iterator_category member of std::iterator_traits.[1]
There is one refinement of Filter for each of the eight modes, and each such refinement corresponds to a refinement of Device. In order to express this corresponce cleanly, it is helpful to include the requirements of the various refinements of Filter in the definition of Filter itself, qualified by category. The various refinements of Filter can then be characterized exactly by the following definitions. For convenience, the requirements of the four most common Filter refinements are also documented individually.
| Concept | Definition | 
|---|---|
| InputFilter | Refinement of Filter with mode convertible to input | 
| OutputFilter | Refinement of Filter with mode convertible to output | 
| BidirectionalFilter | Refinement of Filter with mode convertible to bidirectional | 
| SeekableFilter | Refinement of Filter with mode convertible to seekable | 
| InputSeekableFilter | Refinement of Filter with mode convertible to input_seekable | 
| OutputSeekableFilter | Refinement of Filter with mode convertible to output_seekable | 
| BidirectionalSeekableFilter | Refinement of Filter with mode convertible to bidirectional_seekable | 
| DualSeekableFilter | Refinement of Filter with mode convertible to dual_seekable | 
| Character type | The type of the characters in the filtered sequences | 
| Category | A type convertible to filter_tagand to a unique most-derived mode tag | 
| Mode | The unique most-derived mode tag to which Category is convertible | 
| F | - A type which is a model of Filter | 
| D | - A type which is a model of Device, with the same character type as Fand with mode refining the mode ofF | 
| Ch | - The character type of F | 
| Tr | - boost::iostreams::char_traits<Ch> | 
| f | - Object of type F | 
| d | - Object of type D | 
| c | - Object of type Ch | 
| s1 | - Object of type Ch* | 
| s2 | - Object of type const Ch* | 
| n | - Object of type std::streamsize | 
| off | - Object of type stream_offset | 
| way | - Object of type std::ios_base::seekdir | 
| which | - Object of type std::ios_base::openmode | 
| io | - Alias for namespace boost::iostreams | 
| Expression | Expression Type | 
|---|---|
| typename char_type_of<F>::type | typenameof the character type | 
| typename category_of<F>::type | typenameof the category | 
| Expression | Expression Type | Category Precondition | Semantics | 
|---|---|---|---|
|  | Tr::int_type | Convertible to inputbut not tomultichar_tag | Returns the next character in the input sequence controlled by f,Tr::eof()if the end of the sequence has been reached orTr::would_block()if input is temporarily unavilable because a call todhas produced fewer characters than requested. The input sequence controlled bydmay be accessed usingio::get,io::readandio::putback. | 
|  |  | Convertible to inputand tomultichar_tag | Reads up to ncharacters from the input sequence controlled byfinto the buffers1, returning the number of characters read or-1to indicate end-of-sequence. A value less thannmay be returned only at end-of-sequence or if input is temporarily unavilable because a call todhas produced fewer characters than requested. The input sequence controlled bydmay be accessed usingio::get,io::readandio::putback. | 
| Expression | Expression Type | Category Precondition | Semantics | 
|---|---|---|---|
|  | bool | Convertible to outputbut not tomultichar_tag | Attempts to writes the character cto the output sequence controlled byf, returningfalseifccannot be consumed because a call todhas consumed fewer characters than requested. The output sequence controlled bydmay be accessed usingio::putandio::write. | 
|  |  | Convertible to outputand tomultichar_tag | Writes up to ncharacters from the buffers2to the output sequence controlled byd, returning the number of characters written. A value less thannmay be returned only if a call todhas consumed fewer characters than requested. The output sequence controlled bydmay be accessed usingio::putandio::write. | 
| Expression | Expression Type | Category Precondition | Semantics | 
|---|---|---|---|
|  | std::streampos | Convertible to seekablebut not todirect_tag | 
                Advances the read/write head by  
 
                The input sequence controlled by  | 
|  | std::streampos | Convertible to dual_seekableorbidirectional_seekablebut not todirect_tag | 
                Advances the read head (if  
 
                The input sequence controlled by  
                The result is undefined if  | 
    Errors which occur during the execution of get, put, read, write or seek are indicated by throwing exceptions. Reaching the end of the input sequence is not an error, but attempting to write past the end of the output sequence is.
After an exception is thrown, a Filter must be in a consistent state; further i/o operations may throw exceptions but must have well-defined behaviour. Furthermore, unless it is Closable, it must be ready to begin processing a new character sequence.
See InputFilter, OutputFilter, BidirectionalFilter and SeekableFilter.
The concept Filter was inspired by the inserters and extractors of [Kanze].
[1][ISO], 24.3.1. See Tag Dispatching for a discussion.
© Copyright 2008 CodeRage, LLC
© Copyright 2004-2007 Jonathan Turkanis
Distributed under the Boost Software License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)