FUNCTION REGEX_RE(3)

NAME
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