BidirectionalFilter

Definition

An BidirectionalFilter is a Filter whose mode refines bidirectional.

Description

An BidirectionalFilter operates on the character sequences controlled by a BidirectionalDevice, providing access to two filtered sequences having the same character type. It may expose the filtered sequences in two ways:

  1. by defining member function get and put.
  2. by defining member functions read and write.
The second alternative is provided for enhanced performance. BidirectionalFilters implementing this alternative are referred to as Multi-Character Filters.

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 bidirectional
Mode The unique most-derived mode tag to which Category is convertible

Notation

F- A type which is a model of BidirectionalFilter
D- A type which is a model of Device, with the same character type as F and with mode refining 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
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 Convertible to input but not to multichar_tag Returns the next character in the input sequence controlled by f, Tr::eof() if the end of the sequence has been reached or Tr::would_block() if input is temporarily unavilable because a call to d has produced fewer characters than requested. The input sequence controlled by d may be accessed using io::get, io::read and io::putback.
f.put(d, c)
bool Attempts to writes the character c to the output sequence controlled by f, returning false if c cannot be consumed because a call to d has consumed fewer characters than requested. The output sequence controlled by d may be accessed using io::put and io::write.
f.read(d, s1, n)
std::streamsize
Convertible to input and to multichar_tag Reads up to n characters from the input sequence controlled by f into the buffer s1, returning the number of characters read or -1 to indicate end-of-sequence. A value less than n may be returned only at end-of-sequence or if input is temporarily unavilable because a call to d has produced fewer characters than requested. The input sequence controlled by d may be accessed using io::get, io::read and io::putback.
f.write(d, s2, n)
std::streamsize
Writes up to n characters from the buffer s2 to the output sequence controlled by d, returning the number of characters written. A value less than n may be returned only if a call to d has consumed fewer characters than requested. The output sequence controlled by d may be accessed using io::put and io::write.

Exceptions

Errors which occur during the execution of get, put, read or write 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, an BidirectionalFilter 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