【JSリファレンス】String.prototype.matchAll()

更新日：2024/06/14

初出：ECMAScript2020


String.prototype.matchAll()は、Stringオブジェクト(Stringコンストラクターのインスタンス)のプロトタイプチェーンに組み込まれるメソッドです。

引数としてRegExpオブジェクトを受け取り、対象の文字列に正規表現を適用した結果を順番に返すイテレーターを返します。

 

■構文


String.prototype.matchAll ( regexp )
  1. regexp: 文字列に適用する値

    次の３つのうちのどれかを指定

    ●RegExpオブジェクト。gフラグ必須
    ●正規表現文字列（開始と終了の / は含まない）
    ●[Symbol.match]をプロパティ名にもつオブジェクト

正規表現文字列は、gフラグを持つRegExpオブジェクトに変換されます。

正規表現のマッチング処理の本体は、RegExpオブジェクトの[Symbol.matchAll]()メソッドが行います。
このメソッドは、String.prototype.matchAll( )によって呼び出されます。

実際にはRegExpオブジェクトである必要はなく、[Symbol.matchAll]をプロパティ名を持っていれば他のオブジェクトでも呼び出されます。

String.prototype.matchAll( )は、[Symbol.matchAll]()の戻り値をそのまま返します。
そのため、戻り値は[Symbol.matchAll]()に依存します。

引数がRegExpオブジェクトの場合、マッチした文字列とキャプチャグループの配列およびいくつかのプロパティ(使用例参照)を順番に返すイテレーター

引数がRegExpオブジェクトでない場合、[Symbol.matchAll]()の戻り値

 

■使用例

▶引数がRegExpオブジェクトの場合

const rg = /([a-z])(\d)/g;
for( const value of "a1b2".matchAll( rg ) ){
    console.log( value );
}
// 結果：
// [ 'a1', 'a', '1', index: 0, input: 'a1b2', groups: undefined ]
// [ 'b2', 'b', '2', index: 2, input: 'a1b2', groups: undefined ]

▶引数がRegExpオブジェクトでない場合

const obj = {
    [Symbol.matchAll]: function*(value) {
        yield* [...value];
    }
};

for( const value of "ab".matchAll( obj ) ){
    console.log( value );
}
// 結果：
// a
// b

 

関連ページ

●【JavaScript】 正規表現match()とexec()の違い
●【JavaScript】 matchとmatchAllの違い

更新日：2024/06/14

書いた人（管理人）：けーちゃん

スポンサーリンク

記事の内容について

null

こんにちはけーちゃんです。
説明するのって難しいですね。

「なんか言ってることおかしくない？」
たぶん、こんなご意見あると思います。

裏付けを取りながら記事を作成していますが、僕の勘違いだったり、そもそも情報源の内容が間違えていたりで、正確でないことが多いと思います。
そんなときは、ご意見もらえたら嬉しいです。

掲載コードについては事前に動作確認をしていますが、貼り付け後に体裁を整えるなどをした結果動作しないものになっていることがあります。
生暖かい視線でスルーするか、ご指摘ください。

ご意見、ご指摘はこちら。
https://jsref.affi-sapo-sv.com/info.php

 

このサイトは、リンクフリーです。大歓迎です。