public member function
<regex>
| (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:
| characters | replacement |
|---|
| $n | n-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 format | notes |
|---|
| match_default | Default | Same as format_default.
This constant has a value of zero**. |
| match_not_bol | None | Ignored by this function.
See regex_constants for more info. |
| match_not_eol |
| match_not_bow |
| match_not_eow |
| match_any |
| match_not_null |
| match_continuous |
| match_prev_avail |
| format_default | Default formatting | Uses the standard formatting rules to replace matches (those used by ECMAScript's replace method).
This constant has a value of zero**. |
| format_sed | sed formatting | Uses the same rules as the sed utility in POSIX to replace matches. |
| format_no_copy | No copy | The sections in the target sequence that do not match the regular expression are not copied when replacing matches. |
| format_first_only | First only | Only 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].
|