public member function
<regex>

std::match_results::format

(1)
 string_type format (const char_type* fmt, 
    regex_constants::match_flag_type flags = regex_constants::format_default ) const;
(2)
template <class sT, class sA>
  basic_string<char_type, sT, sA> format (const basic_string<char_type, sT, sA>& fmt,
    regex_constants::match_flag_type flags = regex_constants::format_default ) const;
(3)
template <class OutputIterator, class sT, class sA>
  OutputIterator format ( OutputIterator out,
    const basic_string<char_type, sT, sA>& fmt,
    regex_constants::match_flag_type flags = regex_constants::format_default ) const;
(4)
template <class OutputIterator>
  OuputIterator format ( OutputIterator out,
    const char_type* fmt_first, const char_type* fmt_last,
    regex_constants::match_flag_type flags = regex_constants::format_default ) const;
Format replacement string
Versions (1) and (2) return a string object with a copy of fmt that has its format specifiers and escape sequences replaced by the characters they represent.

Versions (3) and (4) do the same but store the resulting character sequence in the range that starts at out.

The function uses the matches in the match_results object to replace the escape sequences referring to them.

The match_results object shall be ready, which happens after it has been passed as the proper argument in a call to either regex_match or regex_search.

Parameters

fmt
Format string.
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 1, 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 interpret the format string.
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*effects on formatnotes
match_defaultDefaultSame as format_default.
This constant has a value of zero**.
match_not_bolNoneIgnored by this function.
See match_constants for more info.
match_not_eol
match_not_bow
match_not_eow
match_any
match_not_null
match_continuous
match_prev_avail
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 a sequence of characters where the resulting string is stored.
fmt_first, fmt_last
Range on a sequence of characters containing the format string.

Return value

For (1) and (2) the resulting string as a string object.
For (3) and (4), the function returns out.

string_type is a member type, alias of the basic_string type that corresponds to the character type used in the sequence (e.g., string for cmatch and smatch).

Example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
 
// match_results::format
// - using cmatch, a standard alias of match_results<const char*>
#include <iostream>
#include <regex>

int main ()
{
  std::cmatch m;

  std::regex_match ( "subject", m, std::regex("(sub)(.*)") );

  std::cout << m.format ("the expression matched [$0].\n");
  std::cout << m.format ("with sub-expressions [$1] and [$2].\n");

  return 0;
}


Output:
the expression matched [subject].
with sub-expressions [sub] and [ject].


See also

sub_match::str
Return string (public member function)
match_replace

C++