std::match_results::format(3)

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)