Filter

Description

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 having interfaces resembling the functions fgetc, fputc, fread, fwrite and fseek from <stdio.h>. Each function takes a reference to a Device instead of a pointer to a FILE structure.^[1] 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.^[2]

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 `io_mode` convertible to `input`
OutputFilter	Refinement of Filter with `io_mode` convertible to `output`
BidirectionalFilter	Refinement of Filter with `io_mode` convertible to `bidirectional`
SeekableFilter	Refinement of Filter with `io_mode` convertible to `seekable`
InputSeekableFilter	Refinement of Filter with `io_mode` convertible to `input_seekable`
OutputSeekableFilter	Refinement of Filter with `io_mode` convertible to `output_seekable`
BidirectionalSeekableFilter	Refinement of Filter with `io_mode` convertible to `bidirectional_seekable`
DualSeekableFilter	Refinement of Filter with `io_mode` convertible to `dual_seekable`

Refinement of

Associated Types

Character type	The type of the characters in the filtered sequences
Category	A type convertible to filter_tag and to a unique most-derived mode tag
Mode	The unique most-derived mode tag to which Category is convertible

Notation

`F`	- A type which is a model of Filter
`D`	- A type which is a model of Device, with the same character type as `F` and with i/o mode refining the i/o mode of `F`
`Ch`	- The character type of `F`
`Tr`	- `std::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 `std::streamoff`
`way`	- Object of type `std::ios_base::seekdir`
`which`	- Object of type `std::ios_base::openmode`

Valid Expressions — Typenames

Expression	Expression Type
`typename io_char<F>::type`	`typename` of the character type
`typename io_category<F>::type`	`typename` of the category

Valid Expressions / Semantics — Input

Expression	Expression Type	Category Precondition	Semantics
`f.get(d)`	`Tr::int_type`	Convertible to `input` but not to `multichar_tag`	Returns the next character in the input sequence controlled by `f`, or `Tr::eof()` if the end of the sequence has been reached. The input sequence controlled by `d` may be accessed using `boost::iostreams::read` and `boost::iostreams::putback`.
`f.read(d, s1, n)`	`std::streamsize`	Convertible to `input` and to `multichar_tag`	Reads up to characters from the input sequence controlled by `f` into the buffer `s1`, returning the number of characters read. Returning a value less than `n` indicates end-of-sequence. The input sequence controlled by `d` may be accessed using `boost::iostreams::read` and `boost::iostreams::putback`.

Valid Expressions / Semantics — Output

Expression	Expression Type	Category Precondition	Semantics
`f.put(d, c)`	`void`	Convertible to `output` but not to `multichar_tag`	Writes the character `c` to the output sequence controlled by `f`. The output sequence controlled by `d` may be accessed using `boost::iostreams::write`.
`f.write(d, s2, n)`	`void`	Convertible to `output` and to `multichar_tag`	Writes n characters from the buffer `s` to the output sequence controlled by `f`. The output sequence controlled by `d` may be accessed using `boost::iostreams::write`.

Valid Expressions / Semantics — Random-Access

Expression Expression Type Category Precondition Semantics

Expression	Expression Type	Category Precondition	Semantics
`f.seek(d, off, way)`	`std::streamoff`	Convertible to `seekable` but not to `direct_tag`	Advances the read/write head by `off` characters, returning the new position, where the offset is calculated from: the start of the sequence if `way` is `ios_base::beg` the current position if `way` is `ios_base::cur` the end of the sequence if `way` is `ios_base::end` The input sequence controlled by `d` may be accessed using `boost::iostreams::seek` and using `boost::iostreams::write` if the `io_mode` of `F` is convertible to `output`.
`f.seek(d, off, way, which)`	`std::streamoff`	Convertible to `dual_seekable` or `bidirectional_seekable` but not to `direct_tag`	Repositions the read head (if `which` is `std::ios_base::in`), the write head (if `which` is `std::ios_base::out`) or both heads (if `which` is `std::ios_base::in \| std::ios_base::out`) by `off` characters, returning the new position, where the offset is calculated from the start of the sequence if `way` is `ios_base::beg` the current position if `way` is `ios_base::cur` the end of the sequence if `way` is `ios_base::end` The input sequence controlled by `d` may be accessed using `boost::iostreams::seek`, and using `boost::iostreams::write` if the `io_mode` of `F` is convertible to `output`. The result is undefined if `way` is `ios_base::cur` and `which` is `(std::ios_base::in \| std::ios_base::out)`.

f.seek(d, off, way)

std::streamoff

Convertible to seekable but not to direct_tag

Advances the read/write head by off characters, returning the new position, where the offset is calculated from:

the start of the sequence if way is ios_base::beg
the current position if way is ios_base::cur
the end of the sequence if way is ios_base::end

The input sequence controlled by d may be accessed using boost::iostreams::seek and using boost::iostreams::write if the io_mode of F is convertible to output.

f.seek(d, off, way, which)

std::streamoff

Convertible to dual_seekable or bidirectional_seekable but not to direct_tag

Repositions the read head (if which is std::ios_base::in), the write head (if which is std::ios_base::out) or both heads (if which is std::ios_base::in | std::ios_base::out) by off characters, returning the new position, where the offset is calculated from

the start of the sequence if way is ios_base::beg
the current position if way is ios_base::cur
the end of the sequence if way is ios_base::end

The input sequence controlled by d may be accessed using boost::iostreams::seek, and using boost::iostreams::write if the io_mode of F is convertible to output.

The result is undefined if way is ios_base::cur and which is (std::ios_base::in | std::ios_base::out).

Exceptions

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 immediately to begin processing new sequences of data.

Models

See InputFilter, OutputFilter, BidirectionalFilter and SeekableFilter.

Acknowledgments

The concept Filter was inspired by the inserters and extractors of [Kanze].

^[1]There are other differences between the Filter member functions and the corresponding functions from <stdio.h>. Consult the tables, above, for details.

^[2][ISO], 24.3.1. See Tag Dispatching for a discussion.

Revised 20 May, 2004

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)