# Class Template `symmetric_filter`

Description
Headers
Reference
Examples

## Description

The class template `symmetric_filter` is tool for generating models of DualUseFilter from models of SymmetricFilter. It is useful for defining filters based on C language APIs.

The Iostreams library uses `symmetric_filter` to implement the Zlib and Bzip2 Filters.

## Headers

`<boost/iostreams/filter/symmetric.hpp>`

## Reference

#### Synopsis

    namespace boost { namespace iostreams {

    template< typename SymmetricFilter,
              typename Alloc = std::allocator<...> >
    class symmetric_filter {
    public:
        typedef typename char_type_of<SymmetricFilter>::type  char_type;
        typedef implementation-defined                        category;

        explicit symmetric_filter(int buffer_size);

        template<typename T0>
        symmetric_filter(int buffer_size, const T0& t0);

        template<typename T0, typename T1>
        symmetric_filter(int buffer_size, const T0& t0, const T1& t1);

        template<typename T0, ..., typename TN>
        symmetric_filter( int buffer_size, const T0& t0,
                          const T1& t1, ..., const TN& tN );

        ...
    protected:
        SymmetricFilter& filter();
        std::basic_string<char_type, Alloc> unconsumed_input() const;
    };

    } } // End namespace boost::io

#### Template parameters

SymmetricFilter | - | A model of SymmetricFilter
Alloc | - | A standard library allocator type ([ISO], 20.1.5), used to allocate a character buffer

#### `symmetric_filter::symmetric_filter`

        explicit symmetric_filter(int buffer_size);

Constructs an instance of `symmetric_filter` based on a default-constructed instance of the template parameter `SymmetricFilter` and having an internal buffer of size `buffer_size`.

#### `symmetric_filter::symmetric_filter`

        template<typename T0>
        symmetric_filter(int buffer_size, const T0& t0);

        template<typename T0, typename T1>
        symmetric_filter(int buffer_size, const T0& t0, const T1& t1);

        template<typename T0, ..., typename TN>
        symmetric_filter( int buffer_size, const T0& t0,
                                  const T1& t1, ..., const TN& tN );

Each member constructs an instance of `symmetric_filter` based on an instance of the template parameter `SymmetricFilter` constructed with the given sequence of arguments and having an internal buffer of size `buffer_size`.

#### `symmetric_filter::filter`

        SymmetricFilter& filter();

Returns a reference to the underlying instance of `SymmetricFilter`.

#### `symmetric_filter::unconsumed_input`

        std::basic_string<char_type, Alloc> unconsumed_input() const;

Returns any uncomsumed data remaining in the internal buffer as a standard string. Valid from the time the end of a stream is reached — that is, from the time `SymmetricFilter::filter` returns `false` — until `filter` is invoked to begin processing a new sequence of data.

## Examples

For example uses of `symmetric_filter`, see the headers `<boost/iostreams/filter/zlib.hpp>` and `<boost/iostreams/filter/bzip2.hpp>` and the corresponding implementation files `<libs/iostreams/src/zlib.cpp>` and `<libs/iostreams/src/bzip2.cpp>`.

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