# Class Template `aggregate_filter`

Description
Headers
Reference
Examples

## Description

The class template `aggregate_filter` is a DualUseFilter for use as a base class by Filters which filter an entire character sequence at once. Because a `aggregate_filter` must read an entire character sequence into memory before it begins to filter, it is not suitable in low-memory situations or for processing character sequences which have no natural end, such as stock tickers. Because of these limitations, `aggregate_filter` is best used as an aid to those learning to use the Iostreams library.

When used as an InputFilter, an instance of `aggregate_filter` reads to the end of the stream as soon as input is commenced. The entire contents of the stream are filtered using the `private virtual` function `do_filter`. The filtered data is stored and used to satisfy all future requests for input until the end of the filtered data is reached.

When used as an OutputFilter, an instance of `aggregate_filter` stores all data written to it without passing it downstream. When the stream is closed, the entire contents of the stream are filtered using `do_filter`. The filtered data is then written, all at once, to the next downstream Filter or Device.

## Headers

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

## Reference

#### Synopsis

    namespace boost { namespace iostreams {

    #include <vector>

    template< typename Ch,
              typename Tr = std::char_traits<Ch>,
              typename Alloc = std::allocator<Ch> >
    class aggregate_filter  {
    public:
        typedef Ch                            char_type;
        typedef implementation-defined        category;
        typedef std::vector<Char, Alloc>      vector_type;
        virtual ~aggregate_filter();
        ...
    private:
        virtual void do_filter(const vector_type& src, vector_type& dest) = 0;
    };

    } } // End namespace boost::io

#### Template parameters

Ch | - | The character type
Tr | - | The traits type
Alloc | - | A standard library allocator type ([ISO], 20.1.5), used to instantiate `std::vector`

#### `aggregate_filter::do_filter`

        virtual void do_filter(const vector_type& src, vector_type& dest) = 0;

Reads unflitered characters from `src` and appends filtered characters to `dest`, returning after all the characters in `src` have been consumed.

## Examples

For example uses of `aggregate_filter`, see the headers `<boost/iostreams/filter/regex.hpp>` and `<boost/iostreams/filter/stdio.hpp>`.

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)