NAME¶

std::match_results::format - std::match_results::format

Synopsis¶

template< class OutputIt >

OutputIt format( OutputIt out,
const char_type* fmt_first, const char_type* fmt_last, (1) (since C++11)
std::regex_constants::match_flag_type flags =

std::regex_constants::format_default ) const;
template< class OutputIt, class ST, class SA >

OutputIt format( OutputIt out,
const basic_string<char_type,ST,SA>& fmt, (2) (since C++11)
std::regex_constants::match_flag_type flags =

std::regex_constants::format_default ) const;
template< class ST, class SA >

std::basic_string<char_type,ST,SA>
format( const std::basic_string<char_type,ST,SA>& fmt, (3) (since C++11)
std::regex_constants::match_flag_type flags =

std::regex_constants::format_default ) const;
string_type format( const char_type* fmt_s,

std::regex_constants::match_flag_type flags = (4) (since C++11)

std::regex_constants::format_default ) const;

format outputs a format string, replacing any format specifiers or escape sequences
in that string with match data from *this.

1) The format character sequence is defined by the range [fmt_first, fmt_last). The
resulting character sequence is copied to out.
2) The format character sequence is defined by the characters in fmt. The resulting
character sequence is copied to out.
3-4) The format character sequence is defined by the characters in fmt and fmt_s
respectively. The resulting character sequence is copied to a newly constructed
std::basic_string, which is returned.

The flags bitmask determines which format specifiers and escape sequences are
recognized.

The behavior of format is undefined if ready() != true.

Parameters¶

fmt_begin, fmt_end - pointers to a range of characters defining the format character
sequence
fmt - std::basic_string defining the format character sequence
fmt_s - pointer to a null-terminated character string defining the
format character sequence
out - iterator that the resulting character sequence is copied to
flags - std::regex_constants::match_flag_type bitmask specifying which
format specifiers and escape sequences are recognized

Type requirements¶

-
OutputIt must meet the requirements of LegacyOutputIterator.

Return value¶

1-2) out
3-4) The newly constructed string containing resulting character sequence.

Exceptions¶

May throw implementation-defined exceptions.

Example¶

// Run this code

#include <iostream>
#include <string>
#include <regex>

int main()
{
std::string s = "for a good time, call 867-5309";
std::regex phone_regex("\\d{3}-\\d{4}");
std::smatch phone_match;

if (std::regex_search(s, phone_match, phone_regex)) {
std::string fmt_s = phone_match.format(
"$`" // $` means characters before the match
"[$&]" // $& means the matched characters
"$'"); // $' means characters following the match
std::cout << fmt_s << '\n';
}
}

Output:¶

for a good time, call [867-5309]

See also¶

regex_replace replaces occurrences of a regular expression with formatted
(C++11) replacement text
(function template)
match_flag_type options specific to matching
(C++11) (typedef)