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:

by defining a member function put
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 typedefs 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 typedefs 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.

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)