# std::match_results<BidirIt,Alloc>::format

< cpp‎ | regex‎ | match results

template< class OutputIt > OutputIt format( OutputIt out, const char_type* fmt_first, const char_type* fmt_last, std::regex_constants::match_flag_type flags = std::regex_constants::format_default ) const; | (1) | (C++11 起)
template< class OutputIt, class ST, class SA > OutputIt format( OutputIt out, const basic_string<char_type,ST,SA>& fmt, std::regex_constants::match_flag_type flags = std::regex_constants::format_default ) const; | (2) | (C++11 起)
template< class ST, class SA > std::basic_string<char_type,ST,SA> format( const std::basic_string<char_type,ST,SA>& fmt, std::regex_constants::match_flag_type flags = std::regex_constants::format_default ) const; | (3) | (C++11 起)
string_type format( const char_type* fmt_s, std::regex_constants::match_flag_type flags = std::regex_constants::format_default ) const; | (4) | (C++11 起)

`format` 输出格式字符串，它将字符串中的任何格式指定符或转义序列替换为来自 *this 的数据。

1) 格式字符序列以范围 `[fmt_first, fmt_last)` 定义。复制结果字符序列到 `out` 的副本。
2) 格式字符序列以 `fmt` 中的字符定义。复制结果字符序列到 `out` 的副本。
3-4) 格式字符序列分别以 `fmt` 和 `fmt_s` 中的字符定义。复制结果字符序列到新构造的 std::basic_string ，并返回它。

`flags` 位掩码确定辨识哪些格式指定符和转义序列。

若 ready() != true 则 `format` 的行为未定义。

### 参数

fmt_begin, fmt_end | - | 指向定义格式字符序列的字符范围的指针
fmt | - | 定义格式字符序列的 std::basic_string
fmt_s | - | 指向定义格式字符序列的空终止字符串的指针
out | - | 要复制结果字符串到的迭代器
flags | - | 指定辨识哪些格式指定符和转义序列的 std::regex_constants::match_flag_type 位掩码
类型要求
- `OutputIt` 必须满足老式输出迭代器 (LegacyOutputIterator) 的要求。

### 返回值

1-2) `out`
3-4) 含结果字符序列的新构造字符串。

### 异常

可能抛出实现定义的异常。

### 示例

    #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(
                "$`"    // $` 意味着匹配之前的字符
                "[$&]"  // $& 意味着匹配的字符
                "$'");  // $' 意味着后随匹配的字符
            std::cout << fmt_s << '\n';
        }
    }

输出：

    for a good time, call [867-5309]

### 参阅

regex_replace (C++11) | 以格式化的替换文本来替换正则表达式匹配的出现位置 (函数模板)
match_flag_type (C++11) | 特定于匹配的选项 (typedef)