function template
<regex>

std::regex_replace

c-string/c-string (1)
template <class traits, class charT>  basic_string<charT> regex_replace (const charT* s,          const basic_regex<charT,traits>& rgx,          const charT* fmt,          regex_constants::match_flag_type flags = regex_constants::match_default);
c-string/string (2)
template <class traits, class charT, class ST, class SA>  basic_string<charT> regex_replace (const charT*s,          const basic_regex<charT,traits>& rgx,          const basic_string<charT,ST,SA>& fmt,          regex_constants::match_flag_type flags = regex_constants::match_default);
string/c-string (3)
template <class traits, class charT, class ST, class SA>  basic_string<charT,ST,SA> regex_replace (const basic_string<charT,ST,SA>& s,          const basic_regex<charT,traits>& rgx,          const charT* fmt,          regex_constants::match_flag_type flags = regex_constants::match_default);
string/string (4)
template <class traits, class charT, class ST, class SA, class FST, class FSA>  basic_string<charT,ST,SA> regex_replace (const basic_string<charT,ST,SA>& s,          const basic_regex<charT,traits>& rgx,          const basic_string<charT,FST,FSA>& fmt,          regex_constants::match_flag_type flags = regex_constants::match_default);
range/c-string (5)
template <class OutputIterator, class BidirectionalIterator,          class traits, class charT>  OutputIterator regex_replace (OutputIterator out,          BidirectionalIterator first, BidirectionalIterator last,          const basic_regex<charT,traits>& rgx,          const charT* fmt,          regex_constants::match_flag_type flags = regex_constants::match_default);
range/string (6)
template <class OutputIterator, class BidirectionalIterator,          class traits, class charT, class ST, class SA>  OutputIterator regex_replace (OutputIterator out,          BidirectionalIterator first, BidirectionalIterator last,          const basic_regex<charT,traits>& rgx,          const basic_string<charT,ST,SA>& fmt,          regex_constants::match_flag_type flags = regex_constants::match_default);
Replace matched sequence
Makes a copy of the target sequence (the subject) with all matches of the regular expression rgx (the pattern) replaced by fmt (the replacement). The target sequence is either s or the character sequence between first and last, depending on the version used.

The resulting sequence is returned as a string object on versions 1, 2, 3 and 4. Versions 5 and 6 take an output iterator as first argument, which is used to store the resulting sequence.

An optional parameter, flags, allows to specify options on how to match and format the expression.

Parameters

s
A string with the target sequence (the subject).
rgx
A basic_regex object (the pattern) to match.
fmt
A string with the replacement for each match.
This may include format specifiers and escape sequences that are replaced by the characters they represent. For format_default, the possible specifiers are:
charactersreplacement
$nn-th backreference (i.e., a copy of the n-th matched group specified with parentheses in the regex pattern).
n must be an integer value designating a valid backreference, greater than 0, and of two digits at most.
$&A copy of the entire match
$`The prefix (i.e., the part of the target sequence that precedes the match).
$ยดThe suffix (i.e., the part of the target sequence that follows the match).
$$A single $ character.
flags
Flags used to control how rgx is matched and how fmt is formatted.
One or more of these constants can be combined (using the bitwise OR operator, |) to form a valid bitmask value of type regex_constants::match_flag_type:
flag*effectsnotes
match_defaultDefaultDefault matching behavior.
This constant has a value of zero**.
match_not_bolNot Beginning-Of-LineThe first character is not considered a beginning of line ("^" does not match).
match_not_eolNot End-Of-LineThe last character is not considered an end of line ("$" does not match).
match_not_bowNot Beginning-Of-WordThe escape sequence "\b" does not match as a beginning-of-word.
match_not_eowNot End-Of-WordThe escape sequence "\b" does not match as an end-of-word.
match_anyAny matchAny match is acceptable if more than one match is possible.
match_not_nullNot nullEmpty sequences do not match.
match_continuousContinuousThe expression must match a sub-sequence that begins at the first character.
Sub-sequences must begin at the first character to match.
match_prev_availPrevious AvailableOne or more characters exist before the first one. (match_not_bol and match_not_bow are ignored)
format_defaultDefault formattingUses the standard formatting rules to replace matches (those used by ECMAScript's replace method).
This constant has a value of zero**.
format_sedsed formattingUses the same rules as the sed utility in POSIX to replace matches.
format_no_copyNo copyThe sections in the target sequence that do not match the regular expression are not copied when replacing matches.
format_first_onlyFirst onlyOnly the first occurrence of a regular expression is replaced.
* These bitmask flag names are available under the std::regex_constants namespace (see regex_constants for more details).
** Constants with a value of zero are ignored if some other flag is set.
match_flag_type is a type available under the std::regex_constants namespace.
out
Output iterator pointing to the first character of a sequence where the resulting sequence is stored.
The function template type can be any type of output iterator to characters.
first, last
Bidirectional iterators to the initial and final positions in the range of characters used as target sequence for the match. The range used is [first,last), which includes all the characters between first and last, including the character pointed by first but not the character pointed by last.
The function template type can be any type of bidirectional iterator to characters.

Return value

Versions 1, 2, 3 and 4 return a string object with the resulting sequence.
Versions 5 and 6 return out.
Versions 5 and 6 return an iterator that points to the element past the last character written to the sequence pointed by out.

Example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
// regex_replace example
#include <iostream>
#include <string>
#include <regex>
#include <iterator>

int main ()
{
  std::string s ("there is a subsequence in the string\n");
  std::regex e ("\\b(sub)([^ ]*)");   // matches words beginning by "sub"

  // using string/c-string (3) version:
  std::cout << std::regex_replace (s,e,"sub-$2");

  // using range/c-string (6) version:
  std::string result;
  std::regex_replace (std::back_inserter(result), s.begin(), s.end(), e, "$2");
  std::cout << result;

  // with flags:
  std::cout << std::regex_replace (s,e,"$1 and $2",std::regex_constants::format_no_copy);
  std::cout << std::endl;

  return 0;
}

Output:
there is a sub-sequence in the string
there is a sequence in the string
sub and sequence


See also