# OutputFilter

Definition
Description
Examples
Detailed Specification

## Definition

An OutputFilter is a Filter whose mode refines output.

## Description

An OutputFilter operates on the character sequence controlled by a Sink, providing access to a filtered sequence having the same character type. It may expose the filtered sequence in two ways:

1. by defining a member function `put`
2. by defining a member function `write`

The second alternative is provided for enhanced performance. OutputFilters implementing this alternative are referred to as as Multi-Character. (See Multi-Character Filter.)

## Examples

#### I. Ordinary OutputFilter

The following example shows an OutputFilter which converts each character in a sequence to uppercase.

        #include <ctype.h>                        // toupper
        #include <boost/iostreams/categories.hpp> // output_filter_tag
        #include <boost/iostreams/operations.hpp> // put

        using namespace std;
        namespace io = boost::iostreams;

        struct toupper_output_filter {
            typedef char                   char_type;
            typedef io::output_filter_tag  category;

            template<typename Sink>
            bool put(Sink& snk, char c)
            {
                return io::put(snk, toupper((unsigned char) c));
            }
        };

Here `char_type` is the character type of the Filter, `output_filter_tag` is a category tag identifying the Filter as a model of OutputFilter, and the function `io::put` writes a character to an arbitrary Sink.[1]

The Iostreams library defines two convenience classes, `output_filter` and `output_wfilter`, which provide member `typedef`s `char_type` and `category` as well as default implementations of several member functions. When defining a new model of OutputFilter, it is often sufficient to derive from `output_filter` or `output_wfilter` and to define a member function `put`.

#### II. Multi-Character OutputFilter

The following example shows a Multi-Character OutputFilter which performs the same filtering operation as the Filter in Example I.

        #include <ctype.h>                        // toupper
        #include <boost/iostreams/categories.hpp> // output_filter_tag
        #include <boost/iostreams/operations.hpp> // put

        using namespace std;
        namespace io = boost::iostreams;

        struct toupper_filter {
            typedef char                             char_type;
            typedef io::multichar_output_filter_tag  category;

            template<typename Sink>
            std::streamsize write(Sink& snk, const char* s, streamsize n)
            {
                std::streamsize rest = n;
                while (rest != 0 && io::put(snk, toupper((unsigned char) *s++))
                    --rest;
                return n - rest;
            }
        };

Here `multichar_output_filter_tag` is a category tag identifying the Filter as a multichar OutputFilter.

The Iostreams library defines two convenience classes, `multichar_output_filter` and `multichar_output_wfilter`, which provide the member `typedef`s `char_type` and `category` as well as default implementations of several member functions. When defining a new multichar OutputFilter, it is often sufficient to derive from `multichar_output_filter` or `multichar_output_wfilter` and to define a member function `write`.

## Refinement of

Filter.

## Associated Types

Character type | The type of the characters in the filtered sequences
Category | A type convertible to `filter_tag` and to `output`
Mode | The unique most-derived mode tag to which Category is convertible

## Notation

`F` | - A type which is a model of OutputFilter
`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`
`s` | - 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.put(d, c)
| `bool` | Convertible to `output` 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.write(d, s, n)
    std::streamsize
| Convertible to `output` and to `multichar_tag` | Writes up to `n` characters from the buffer `s` 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 `put` or `write` are indicated by throwing exceptions. Attempting to write past the end of the sequence is always an error.

After an exception is thrown, an OutputFilter 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

## Acknowledgments

The concept OutputFilter was inspired by the inserters of [Kanze].

[1]Technically, `boost::iostreams::put` requires that a Sink be indirect.

© 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)