SeekableFilter

Definition

A SeekableFilter is a Filter whose mode refines seekable.

Description

A SeekableFilter operates on the character sequence controlled by a SeekableDevice, providing access to a filtered sequence having the same character type. It may expose the filtered sequence in two ways:

by defining member function get, put and seek.
by defining member functions read, write and seek.

The second alternative is provided for enhanced performance. SeekableFilters implementing this alternative are referred to as Multi-Character. (See Multi-Character Filter.)

Refinement of

InputFilter, OutputFilter.

Associated Types

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

Notation

`F`	- A type which is a model of SeekableFilter
`D`	- A type which is a model of Device, with the same character type as `F` and with mode convertible to the mode of `F`
`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`

Valid Expressions / Semantics

Expression	Expression Type	Category Precondition	Semantics
`typename char_type_of<F>::type`	`typename` of the character type	-	-
`typename category_of<F>::type`	`typename` of the category	-	-
`f.get(d)`	`Tr::int_type`	Not convertible to `multi_char_tag`	Returns the next character in the sequence controlled by `f`, or `Tr::eof()` if the end of the sequence has been reached. The sequence controlled by `d` may be accessed using `io::read` and `io::putback`.
`f.put(d, c)`	`bool`	Not convertible to `multi_char_tag`	Writes the character `c` to the sequence controlled by `f`. The sequence controlled by `d` may be accessed using `io::write`.
`f.read(d, s1, n)`	`std::streamsize`	Convertible to `multi_char_tag`	Reads up to characters from the 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 sequence controlled by `d` may be accessed using `io::read` and `io::putback`.
`f.write(d, s2, n)`	`std::streamsize`	Convertible to `multi_char_tag`	Writes n characters from the buffer `s2` to the sequence controlled by `f`. The sequence controlled by `d` may be accessed using `io::write`.
`f.seek(d, off, way)`	`std::streampos`	-	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 sequence controlled by `d` may be accessed using `io::seek` and using `io::write` if the mode of `F` is convertible to `output`.

Exceptions

Errors which occur during the execution of get, put, read, write or seek are indicated by throwing exceptions. Reaching the end of the sequence is not an error, but attempting to write past the end of the sequence is.

After an exception is thrown, a SeekableFilter 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.

Models

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)