最終更新日時(UTC): 2026年01月08日 11時16分38秒
yoh が更新

履歴 編集

class template
<regex>

# std::match_results(C++11)

    namespace std {
      template <class BidirectionalIterator,
                class Allocator = allocator<sub_match<BidirectionalIterator>>>
      class match_results;

      using cmatch  = match_results<const char*>;
      using wcmatch = match_results<const wchar_t*>;
      using smatch  = match_results<string::const_iterator>;
      using wsmatch = match_results<wstring::const_iterator>;

      namespace pmr {  // C++17から
        template <class BidirectionalIterator>
          using match_results =
            std::match_results<BidirectionalIterator,
                               polymorphic_allocator<sub_match<BidirectionalIterator>>>;

        using cmatch  = match_results<const char*>;
        using wcmatch = match_results<const wchar_t*>;
        using smatch  = match_results<string::const_iterator>;
        using wsmatch = match_results<wstring::const_iterator>;
      }
    }

## 概要

`match_results` は正規表現によるマッチ結果を格納するコンテナである。コンテナの要素はマッチ結果を表すサブマッチ（`sub_match`）である。
コンテナとは言っても `regex_match` や `regex_search` のマッチ結果を格納することを目的としているため、 一般的なコンテナのように通常の操作でコンテナに要素を格納したり変更したりすることはできない。

構築直後の `match_results` オブジェクトは結果を格納していない（`ready() == false`）ため、ほとんどのメンバ関数は使用することができない。
`regex_match` や `regex_search` に引数として渡されると、マッチが成功したか否かにかかわらずその結果を格納する（`ready() == true`）。
なお、`regex_iterator` を間接参照した際の `match_results` オブジェクトは常にマッチ結果を格納している（`ready() == true`）。

マッチ結果を格納した `match_results` オブジェクトは、マッチが成功した場合には 1 つ以上の要素を格納しているため、`empty() == false` となる。
マッチに成功し `empty() == false` となった `match_results` オブジェクトに格納されている各要素（サブマッチ：`sub_match`）には、標準シーケンスコンテナの `vector` 等と同様に `operator[]` で直接アクセスすることができるだけでなく、 `str`、`position`、`length` といったメンバ関数で各要素の内容にアクセスすることもできる。
最初の要素には、マッチした文字列全体を表すサブマッチが格納され、以降に各キャプチャグループ（正規表現内のカッコで囲まれた部分に対応する）が続く。
また、マッチした文字列だけでなく、マッチした文字列の前（`prefix`）、および、後（`suffix`）を指すサブマッチも保持している。 さらに、マッチした結果を用いた書式出力機能も有する（`format`）。

`match_results` はアロケータ対応コンテナの要件のすべて、および、シーケンスコンテナの要件のうち読み取り専用の操作をサポートしている。
`match_results` オブジェクトからメンバ関数で取得できるイテレータについて規格では特に言及されていないが、`operator[]` が使用できることから通常ランダムアクセスイテレータであるもの考えても差し支えないものと思われる。

## メンバ関数

### 構築・破棄

名前 | 説明 | 対応バージョン
--- | --- | ---
`(constructor)` | コンストラクタ | C++11
`(destructor)` | デストラクタ | C++11
`operator=` | 代入演算子 | C++11

### 状態

名前 | 説明 | 対応バージョン
--- | --- | ---
`ready` | 結果が利用可能か否かを返す | C++11

### サイズ

名前 | 説明 | 対応バージョン
--- | --- | ---
`size` | サブマッチの数を返す | C++11
`max_size` | 格納できるサブマッチの最大数を返す | C++11
`empty` | マッチしたか否かを返す | C++11

### 要素アクセス

名前 | 説明 | 対応バージョン
--- | --- | ---
`length` | 指定されたサブマッチの長さを返す | C++11
`position` | 指定されたサブマッチの位置を返す | C++11
`str` | 指定されたサブマッチを文字列の形で返す | C++11
`operator[]` | 指定されたサブマッチを返す | C++11
`prefix` | マッチした文字列の前の文字列を示すサブマッチを返す | C++11
`suffix` | マッチした文字列の後の文字列を示すサブマッチを返す | C++11
`begin` | 先頭のサブマッチを指すイテレータを取得する | C++11
`end` | 末尾のサブマッチの次を指すイテレータを取得する | C++11
`cbegin` | 先頭のサブマッチを指すイテレータを取得する | C++11
`cend` | 末尾のサブマッチの次を指すイテレータを取得する | C++11

### フォーマット

名前 | 説明 | 対応バージョン
--- | --- | ---
`format` | `match_results` オブジェクトを書式文字列に従って出力する | C++11

### アロケータ

名前 | 説明 | 対応バージョン
--- | --- | ---
`get_allocator` | アロケータオブジェクトを取得する | C++11

### 交換

名前 | 説明 | 対応バージョン
--- | --- | ---
`swap` | オブジェクトの内容を交換する | C++11

## メンバ型

名前 | 説明 | 対応バージョン
--- | --- | ---
`value_type` | 要素の型。`sub_match<BidirectionalIterator>` の別名 | C++11
`const_reference` | `const` 参照の型。`const value_type&` の別名 | C++11
`reference` | 参照の型。`value_type&` の別名（C++11 では `const value_type&` となっていたが、規格のバグとして C++14 で修正された） | C++11
`const_iterator` | 読み取り専用イテレータの型。実装依存の型の別名 | C++11
`iterator` | イテレータの型。`const_iterator` | C++11
`difference_type` | 2 つのイテレータの差の型。`typename iterator_traits<BidirectionalIterator>::difference_type` の別名 | C++11
`size_type` | `typename allocator_traits<Allocator>::size_type` の別名 | C++11
`allocator_type` | アロケータオブジェクトの型。`Allocator` の別名 | C++11
`char_type` | 文字の型。`typename iterator_traits<BidirectionalIterator>::value_type` の別名 | C++11
`string_type` | 文字列の型。`basic_string<char_type>` の別名 | C++11

## 非メンバ関数

名前 | 説明 | 対応バージョン
--- | --- | ---
`operator==` | 等値比較を行う | C++11
`operator!=` | 非等値比較を行う | C++11
`swap` | 2 つの `match_results` オブジェクトの内容を交換する | C++11

## 例

    #include <iostream>
    #include <regex>

    int main()
    {
      const char s[] = "The C++11 is very cool!!";
      const std::regex re("(\\w+) is (\\w+)");

      std::cmatch m;
      if (std::regex_search(s, m, re)) {
        std::cout << "ready = " << std::boolalpha << m.ready() << ", empty = " << m.empty() << std::endl << std::endl;
        std::cout << "prefix:'" << m.prefix() << '\'' << std::endl;
        for (std::size_t i = 0, n = m.size(); i < n; ++i) {
          std::cout << i << ":'" << m.str(i) << "\', position = " << m.position(i) << ", length = " << m.length(i) << std::endl;
        }
        std::cout << "suffix:'" << m.suffix() << '\'' << std::endl << std::endl;
        std::cout << m.format("$`14 is $2$'") << std::endl;
      } else {
        std::cout << "not match" << std::endl;
      }
    }

### 出力

    ready = true, empty = false

    prefix:'The C++'
    0:'11 is very', position = 7, length = 10
    1:'11', position = 7, length = 2
    2:'very', position = 13, length = 4
    suffix:' cool!!'

    The C++14 is very cool!!

## バージョン

### 言語

- C++11

### 処理系

- Clang: 3.0 ✅, 3.1 ✅, 3.2 ✅, 3.3 ✅, 3.4 ✅, 3.5 ✅, 3.6 ✅
- GCC: 4.9.0 ✅, 4.9.1 ✅, 4.9.2 ✅, 5.0.0 ✅
- ICC: ??
- Visual C++: ??