# SeekableFilter

## Definition

A SeekableFilter is a Filter whose `mode_of` 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 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` | 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` 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

Revised 20 May, 2004

© Copyright Jonathan Turkanis, 2004

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)