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* (1) (since C++11)
   fmt_last,
                    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 <regex>
 #include <string>
 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)