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:

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.

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 `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

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`	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`	Convertible to `input` but not to `multichar_tag`	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`	Convertible to `input` and to `multichar_tag`	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

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)