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

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

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

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)