# Class Template `basic_grep_filter`

Description
Headers
Installation
Reference

## Description

The class template `basic_grep_filter` filters a character sequence line by line using a regular expression provided at construction, in a manner similar to the command-line utility grep ([IEEE]). The filter uses regular expressions from the Boost Regular Expression Library ([Maddock]).

By default, the filtered character sequence consists of those lines of the unfilitered sequence that contain a subsequence matching the regular expression. By specifying appropriate options at construction, `basic_grep_filter` can be made to pass through only those lines which exactly match the regular expression (as if the option -x had been passed to the command-line utility) or only those lines that do not contain a match (as if the option -v had been passed to the command-line utility).

A running count of the lines in the filtered character sequence is available via the member function `count`.

## Headers

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

## Installation

The template `basic_grep_filter` uses the Boost Regular Expression Library, which must be built separately. See here for details.

## Reference

#### Synopsis

    namespace boost { namespace iostreams {

    #include <boost/function.hpp>
    #include <boost/regex.hpp>

    namespace grep {

    const int invert;
    const int whole_line;

    }

    template< typename Ch,
              typename Tr = regex_traits<Ch>,
              typename Alloc = std::allocator<Ch> >
    class basic_grep_filter {
    public:
        basic_grep_filter( const basic_regex<Ch, Tr, Alloc>& pattern,
                           regex_constants::match_flag_type flags =
                               regex_constants::match_default,
                           int options = 0 );
        int count() const;
    };

    typedef basic_grep_filter<char>     grep_filter;
    typedef basic_grep_filter<wchar_t>  wgrep_filter;

    } } // End namespace boost::io

#### Template parameters

Ch | - | The character type
Tr | - | The regular expression traits type
Alloc | - | A standard library allocator type ([ISO], 20.1.5), used to allocate character buffers

#### `basic_grep_filter::basic_grep_filter`

        basic_grep_filter( const basic_regex<Ch, Tr, Alloc>& pattern,
                           regex_constants::match_flag_type flags =
                               regex_constants::match_default,
                           int options = 0 );

Constructs a `basic_grep_filter` from the given regular expression, match flags, and grep options. The parameters have the following interpretations:

pattern | - | The regular expression to be matched against the stream of unfiltered data
flags | - | The flags passed to regex_search or regex_match to specify regular expression matching behavior
options | - | A bitwise OR of zero or more constants from the namespace `boost::iostreams::grep`. Currently two constants are recongnized: `grep::whole_line` causes the filter to pass through only those lines which exactly match the regular expression, and `grep::invert` causes the filter to pass through only those lines that do not contain a match.

#### `basic_grep_filter::count`

        int count() const;

Returns a running count of the lines passed through from the unfiltered character sequence to the filtered character sequence. The count is reset to zero automatically when the filter begins processing a new character sequence.

Revised 28 May 2008

© Copyright 2008 CodeRage, LLC

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)