# Class Template `basic_counter`

Description
Headers
Reference
Examples

## Description

The class template `basic_counter` is a DualUseFilter which forwards data unmodified to the next filter in a chain, keeping track of the number of characters and lines it has processed.

`basic_counter` is OptimallyBuffered with an optimal buffer size of `0` to keep the character and line counts accurate. When a `basic_counter` is used for output, the line and character counts should exactly reflect the data which has been passed to downstream fillters. When a `basic_counter` is used for input, the character counts may deviate slightly from the number of characters that have been read from downstream the filters because of the putback buffer. The line count should exactly reflect the number of lines that have been read from downstream, except when the first character of a line is being read, in which case the line count may be off by one.

## Headers

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

## Reference

#### Synopsis

    namespace boost { namespace iostreams {

    template<typename Ch>
    class basic_counter {
    public:
        typedef Ch                                char_type;
        typedef typename [implmentation defined]  category;
        explicit basic_counter(int first_line = 0, int first_char = 0);
        int lines() const;
        int characters() const;
        std::streamsize optimal_buffer_size() const;
    };

    typedef basic_counter<char>     counter;
    typedef basic_counter<wchar_t>  wcounter;

    } } // End namespace boost::io

#### Template parameters

Ch | - | The character type

#### `counter::counter`

        explicit basic_counter(int first_line = 0, int first_char = 0);

Constructs a `basic_counter` with the given initial counts.

#### `counter::lines`

        int lines() const;

Returns the current line count.

#### `counter::characters`

        int characters() const;

Returns the current character count.

#### `counter::optimal_buffer_size`

        std::streamsize optimal_buffer_size() const;

Returns `0`.

## Examples

The following example illustrates one way of obtaining the line and character counts after a `basic_counter` has been added to a filter chain: the `filtering_stream` member function `component` to obtain a pointer to `basic_counter`.

    #include <boost/iostreams/device/file.hpp>
    #include <boost/iostreams/filter/counter.hpp>
    #include <boost/iostreams/filtering_stream.hpp>

    namespace io = boost::iostreams;

    int main()
    {
        io::filtering_istream in;
        in.push(io::counter());
        in.push(io::file_source("poem.txt"));
        // read from in
        int lines = in.component<0, counter>()->lines();
        int characters = in.component<0, counter>()->characters();
    }

The following example illustrates a second way of obtaining the line and character counts: add the `basic_counter` to the filter chain by referece, using `boost::ref`, and access the `basic_counter` directly.

    #include <boost/iostreams/device/file.hpp>
    #include <boost/iostreams/filter/counter.hpp>
    #include <boost/iostreams/filtering_stream.hpp>
    #include <boost/ref.hpp>

    namespace io = boost::iostreams;

    int main()
    {
        io::counter cnt;
        io::filtering_ostreams out;
        out.push(boost::ref(cnt));
        out.push(io::file_sink("log.txt"));
        // write to out
        int lines = cnt.lines();
        int characters = cnt.characters();
    }

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)