String.prototype.match()

match() メソッドは、正規表現に対する文字列のマッチングの結果を受け取ります。

構文

str.match(regexp)

引数

regexp

正規表現オブジェクトです。

regexp が RegExp ではないオブジェクトであった場合、 RegExp への暗黙的な変換が new RegExp(regexp) を使用して行われます。

一切引数を与えずに match() メソッドを使った場合、空の文字列 1 つを持つ Array、 [""] が得られます。

返値

グローバル (g) フラグの有無によって内容が変わる Array を返します。一致するもの見つからなかった場合は null を返します。

• g フラグがあった場合は、正規表現全体に一致したすべての結果を返しますが、キャプチャグループは返しません。
• g フラグがなかった場合、最初に完全に一致したものと、それに関するキャプチャグループを返します。この場合、返される要素には下記の追加のプロパティが存在します。

追加のプロパティ

上記の説明にある通り、結果は追加のプロパティを含むことがあります。

groups

名前付きキャプチャグループのオブジェクトで、キーは名前、値はキャプチャグループ、または名前付きキャプチャグループが定義されていない場合は undefined です。詳細はグループと範囲を見てください。

index

結果が見つかった検索のインデックスです。

input

検索された文字列のコピーです。

解説

正規表現が g フラグを含んでいない場合、 str.match() は RegExp.exec() と同じ結果を返します。

その他のメソッド

• ある文字列が正規表現 RegExp に一致するかどうかを知る必要がある場合は、 RegExp.test() を使用してください。
• 一番最初に一致したものだけが欲しい場合、代わりに RegExp.exec() を使ったほうが良いかもしれません。
• キャプチャグループを取得する場合でグローバルフラグが設定されていた場合は、 RegExp.exec() を使用してください。

例

match() の使用

以下の例において、 match() は 'Chapter' とそれに続く 1 桁以上の数字、それに続く 0 回以上の小数点と数字を見つけるために使われています。

正規表現が i フラグを含んでいるので、大文字と小文字の違いは無視されます。

let str = 'For more information, see Chapter 3.4.5.1';
let re = /see (chapter \d+(\.\d)*)/i;
let found = str.match(re);

console.log(found);

// logs [ 'see Chapter 3.4.5.1',
//        'Chapter 3.4.5.1',
//        '.1',
//        index: 22,
//        input: 'For more information, see Chapter 3.4.5.1' ]

// 'see Chapter 3.4.5.1' is the whole match.
// 'Chapter 3.4.5.1' was captured by '(chapter \d+(\.\d)*)'.
// '.1' was the last value captured by '(\.\d)'.
// The 'index' property (22) is the zero-based index of the whole match.
// The 'input' property is the original string that was parsed.

match() での g と i フラグの使用

以下の例は、 g と i フラグを match() で使用した実例です。 A から E までと、 a から e までのすべての文字が返され、それぞれが配列の個々の要素に入ります。

let str = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz';
let regexp = /[A-E]/gi;
let matches_array = str.match(regexp);

console.log(matches_array);
// ['A', 'B', 'C', 'D', 'E', 'a', 'b', 'c', 'd', 'e']

名前付きキャプチャグループの使用

名前付きキャプチャグループに対応しているブラウザーでは、次のコードは "fox" または "cat" を "animal" という名前のグループに入れます。

let paragraph = 'The quick brown fox jumps over the lazy dog. It barked.';

let capturingRegex = /(?<animal>fox|cat) jumps over/;
found = paragraph.match(capturingRegex);
console.log(found.groups); // {animal: "fox"}

引数なしの match() の使用

let str = "Nothing will come of nothing.";

str.match();   // returns [""]

RegExp ではないオブジェクトを引数にする

引数 regexp が文字列または数値である場合、暗黙に new RegExp(regexp) を使用して RegExp に変換されます。

正の符号がついた正の数であった場合、 RegExp() は正の符号を無視します。

let str1 = "NaN means not a number. Infinity contains -Infinity and +Infinity in JavaScript.",
    str2 = "My grandfather is 65 years old and My grandmother is 63 years old.",
    str3 = "The contract was declared null and void.";
str1.match("number");   // "number" is a string. returns ["number"]
str1.match(NaN);        // the type of NaN is the number. returns ["NaN"]
str1.match(Infinity);   // the type of Infinity is the number. returns ["Infinity"]
str1.match(+Infinity);  // returns ["Infinity"]
str1.match(-Infinity);  // returns ["-Infinity"]
str2.match(65);         // returns ["65"]
str2.match(+65);        // A number with a positive sign. returns ["65"]
str3.match(null);       // returns ["null"]

仕様書

ブラウザーの互換性

match() の基本対応

名前付きキャプチャグループの対応

Firefox 特有のメモ

• 標準外の第二引数 flags が Firefox のみで str.match(regexp, flags) のように使用できました。 Firefox 49 以降では削除されています。
• Firefox 27 において、このメソッドは ECMAScript 仕様書に合うように調整されました。 match() がグローバルの正規表現で呼び出された場合、 RegExp.lastIndex プロパティは (もしあれば) 0 にリセットされるようになりました (bug 501739)。

関連情報

• String.prototype.matchAll()
• RegExp
• RegExp.prototype.exec()
• RegExp.prototype.test()