Class Template `basic_regex_filter`

Description
Headers
Installation
Reference

Description

The class template basic_regex_filter performs text substitutions using regular expressions from the Boost Regular Expression Library ([Maddock]).

Each basic_regex_filter stores a regular expression and a formatting function. As unfiltered data is scanned for matches, portions of data which fall between regular expression matches are forwarded unchanged. Each time a match is found, the corresponding match_results object is passed to the formatting function and the return value is forwarded in place of the matched text.

Users may construct instances of basic_regex_filter either from formatting functions or from format strings.

Since a regular expression may need to look arbitrarily far ahead in a character sequence, basic_regex_filter derives from aggregate_filter and processes an entire sequence of data at once.

Headers

<boost/iostreams/filter/regex.hpp>

Installation

The template basic_regex_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>

template< typename Ch,
          typename Tr = regex_traits<Ch>,
          typename Alloc = std::allocator<Ch> >
class basic_regex_filter
    : public aggregate_filter<Ch, std::char_traits<Ch>, Alloc> // Exposition only
{   
public:
    typedef boost::function1<
                std::basic_string<Ch>, 
                const match_results<const Ch*>&
            > 
            formatter;
    basic_regex_filter( const basic_regex<Ch, Tr, Alloc>& pattern,
                        const formatter& replace,
                        regex_constants::match_flag_type flags = 
                            regex_constants::match_default );
    basic_regex_filter( const basic_regex<Ch, Tr, Alloc>& pattern,
                        const std::basic_string<Ch>& fmt,
                        regex_constants::match_flag_type flags = 
                            regex_constants::match_default,
                        regex_constants::match_flag_type fmt_flags = 
                            regex_constants::format_default );
    basic_regex_filter( const basic_regex<Ch, Tr, Alloc>& pattern,
                        const Ch* fmt,
                        regex_constants::match_flag_type flags = 
                            regex_constants::match_default,
                        regex_constants::match_flag_type fmt_flags = 
                            regex_constants::format_default );
};

typedef basic_regex_filter<char>     regex_filter;
typedef basic_regex_filter<wchar_t>  wregex_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_regex_filter::formatter`

    typedef boost::function1<
                std::basic_string<Ch>, 
                const match_results<const Ch*>&
            > 
            formatter;

The type of object which a basic_regex_filter uses to determine the replacement text for a given regular expression match. Each time a match is found, a corresponding match_results object is passed to a formatter, which returns the appropriate replacement text. Since Boost.Function objects are implictly constructible from function objects with the correct signature, users of regular expression Filters may define their own function objects with the correct signature and pass them to the basic_regex_filter constructor which takes a formatter. E.g.,

    struct my_formatter {
        std::string operator()(const match_results<const char*>& match)
        {
            // Examine match and return the appropriate replacement text
        }
    };
    int main()
    {
        regex         pattern( ... );
        regex_filter  filter(pattern, my_formatter());
        ...
    }

`basic_regex_filter::basic_regex_filter`

    basic_regex_filter( const basic_regex<Ch, Tr, Alloc>& pattern,
                        const formatter& replace,
                        regex_constants::match_flag_type flags = 
                            regex_constants::match_default );

Constructs a basic_regex_filter from the given regular expression, formatting function and match flags. The parameters have the following interpretations:

pattern	-	The regular expression to be matched against the stream of unfiltered data
replace	-	A function which will be passed each `match_results` object in succession and whose return values will be be used as replacement text
flags	-	Used to construct a regex_iterator

    basic_regex_filter( const basic_regex<Ch, Tr, Alloc>& pattern,
                        const std::basic_string<Ch>& fmt,
                        regex_constants::match_flag_type flags = 
                            regex_constants::match_default,
                        regex_constants::match_flag_type fmt_flags = 
                            regex_constants::format_default );

Constructs a basic_regex_filter from the given regular expression, format string and pair of match flags. The parameters have the following interpretations:

pattern	-	The regular expression to be matched against the stream of unfiltered data
fmt	-	A format string which specifies the replacement text for each regular expression match, using match_results::format
flags	-	Used to construct a regex_iterator
fmt_flags	-	The flags argument to match_results::format

    basic_regex_filter( const basic_regex<Ch, Tr, Alloc>& pattern,
                        const Ch* fmt,
                        regex_constants::match_flag_type flags = 
                            regex_constants::match_default,
                        regex_constants::match_flag_type fmt_flags = 
                            regex_constants::format_default );