| Home | Libraries | People | FAQ | More

## Function regex_replace

boost::xpressive::regex_replace — Build an output sequence given an input sequence, a regex, and a format string or a formatter object, function, or expression.

## Synopsis

    // In header: <boost/xpressive/regex_algorithms.hpp>

    template<typename OutIter, typename BidiIter, typename Formatter>
      OutIter regex_replace(OutIter out, BidiIter begin, BidiIter end,
                            basic_regex< BidiIter > const & re,
                            Formatter const & format,
                            regex_constants::match_flag_type flags = regex_constants::match_default,
                            unspecified = 0);
    template<typename OutIter, typename BidiIter>
      OutIter regex_replace(OutIter out, BidiIter begin, BidiIter end,
                            basic_regex< BidiIter > const & re,
                            typename iterator_value< BidiIter >::type const * format,
                            regex_constants::match_flag_type flags = regex_constants::match_default);
    template<typename BidiContainer, typename BidiIter, typename Formatter>
      BidiContainer
      regex_replace(BidiContainer & str, basic_regex< BidiIter > const & re,
                    Formatter const & format,
                    regex_constants::match_flag_type flags = regex_constants::match_default,
                    unspecified = 0);
    template<typename BidiContainer, typename BidiIter, typename Formatter>
      BidiContainer
      regex_replace(BidiContainer const & str, basic_regex< BidiIter > const & re,
                    Formatter const & format,
                    regex_constants::match_flag_type flags = regex_constants::match_default,
                    unspecified = 0);
    template<typename Char, typename Formatter>
      std::basic_string< typename remove_const< Char >::type >
      regex_replace(Char * str, basic_regex< Char * > const & re,
                    Formatter const & format,
                    regex_constants::match_flag_type flags = regex_constants::match_default,
                    unspecified = 0);
    template<typename BidiContainer, typename BidiIter>
      BidiContainer
      regex_replace(BidiContainer & str, basic_regex< BidiIter > const & re,
                    typename iterator_value< BidiIter >::type const * format,
                    regex_constants::match_flag_type flags = regex_constants::match_default,
                    unspecified = 0);
    template<typename BidiContainer, typename BidiIter>
      BidiContainer
      regex_replace(BidiContainer const & str, basic_regex< BidiIter > const & re,
                    typename iterator_value< BidiIter >::type const * format,
                    regex_constants::match_flag_type flags = regex_constants::match_default,
                    unspecified = 0);
    template<typename Char>
      std::basic_string< typename remove_const< Char >::type >
      regex_replace(Char * str, basic_regex< Char * > const & re,
                    typename add_const< Char >::type * format,
                    regex_constants::match_flag_type flags = regex_constants::match_default);

## Description

Constructs a ``regex_iterator`` object: ``regex_iterator`< BidiIter > i(begin, end, re, flags)`, and uses `i` to enumerate through all of the matches m of type ``match_results`< BidiIter >` that occur within the sequence `[begin, end)`. If no such matches are found and `!(flags & format_no_copy)` then calls `std::copy(begin, end, out)`. Otherwise, for each match found, if `!(flags & format_no_copy)` calls `std::copy(m.prefix().first, m.prefix().second, out)`, and then calls `m.format(out, format, flags)`. Finally if `!(flags & format_no_copy)` calls `std::copy(last_m.suffix().first, last_m.suffix().second, out)` where `last_m` is a copy of the last match found.

If `flags & format_first_only` is non-zero then only the first match found is replaced.

Parameters:

`begin` | The beginning of the input sequence.
`end` | The end of the input sequence.
`flags` | Optional match flags, used to control how the expression is matched against the sequence. (See `match_flag_type`.)
`format` | The format string used to format the replacement sequence, or a formatter function, function object, or expression.
`out` | An output iterator into which the output sequence is written.
`re` | The regular expression object to use.

Requires:

Type `BidiIter` meets the requirements of a Bidirectional Iterator (24.1.4).

Type `OutIter` meets the requirements of an Output Iterator (24.1.2).

Type `Formatter` models `ForwardRange`, `Callable<match_results<BidiIter> >`, `Callable<match_results<BidiIter>, OutIter>`, or `Callable<match_results<BidiIter>, OutIter, regex_constants::match_flag_type>`; or else it is a null-terminated format string, or an expression template representing a formatter lambda expression.

`[begin,end)` denotes a valid iterator range.

Returns: | The value of the output iterator after the output sequence has been written to it.
Throws: | regex_error on stack exhaustion or invalid format string.