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:

  1. by defining member function get, put and seek.
  2. 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 typeThe 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

ExpressionExpression TypeCategory PreconditionSemantics
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 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
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