# SymmetricFilter

## Description

A SymmetricFilter processes a character sequence fed to it incrementally in a user-supplied buffer and outputs a filtered sequence incrementally to a second user-supplied buffer. It is useful for defining filters based on C language APIs.

SymmetricFilter does not refine Filter. Instead, the template `symmetric_filter` can used to generate a Filter from a SymmetricFilter. The Filters generated in this manner are DualUseFilters and are CopyConstructible regardless of whether the SymmetricFilters on which they are based are CopyConstructible.

The concept SymmetricFilter is notable in that its definition does not involve the concept of a Source or Sink.

## Associated Types

Character type | The type of the characters in the filtered sequences

## Notation

`F` | - A type which is a model of SymmetricFilter
`Ch` | - The character type of `F`
`f` | - Object of type `F`
`i1, i2` | - Objects of type `const Ch*`
`o1, o2` | - Objects of type `Ch*`
`flush` | - Object of type `bool`

## Valid Expressions / Semantics — Typenames

Expression | Expression Type
--- | ---
    typename char_type_of<F>::type
| `typename` of the character type

## Valid Expressions / Semantics — Member Functions

Expression | Expression Type | Semantics | Postcondition
--- | --- | --- | ---
    f.filter(i1, i2, o1, o2, flush)
| `bool` | Attempts to filter the sequence `[i1, i2)`, storing the result in the sequence `[o1, o2)`. If `flush` is true, writes as much output to `[o1, o2)` as possible. If `flush` is `false`, returns `false` to indicate that a “natural” end of stream has been detected. Otherwise, returns `true` to indicate that additional characters, not yet stored in `[o1, o2)`, are available for output. | `i1` points to the first unconsumed character in the orginal sequence `[i1, i2)`. `o1` points to the first unconsumed character in the orginal sequence `[o1, o2)`. Either `i1 == i2` or `o1 == o2`.
    f.close()
| `void` | - | ```f` is ready to begin filtering a new sequence

## Exceptions

Errors which occur during the execution of `filter` or `close` are indicated by throwing exceptions.

## Models

Revised 02 Feb 2008

© Copyright 2008 CodeRage, LLC
© Copyright 2004-2007 Jonathan Turkanis

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)