BidirectionalFilter

Definition

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:

by defining member function get and put.

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.

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.

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.