String.prototype.match()

Baseline Widely available

This feature is well established and works across many devices and browser versions. It’s been available across browsers since July 2015.

match() は String 値のメソッドで、この文字列の正規表現に対する照合結果を受け取ります。

試してみましょう

構文

js
match(regexp)

引数

regexp

正規表現オブジェクト、または Symbol.match を持つ任意のオブジェクトです。

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

一切引数を与えずに match() メソッドを使った場合、空文字列 1 つを持つ Array、[""] が得られます。これは match(/(?:)/) と同じになるからです。

返値

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

  • g フラグがあった場合は、正規表現全体に一致したすべての結果を返しますが、キャプチャグループは返しません。
  • g フラグがなかった場合、最初に完全に一致したものと、それに関するキャプチャグループを返します。この場合、match() は RegExp.prototype.exec() と同じ結果になります（追加のプロパティ付きの配列）。

解説

String.prototype.match 自体の実装はとてもシンプルです。引数の文字列を最初の引数として Symbol.match メソッドを呼び出すだけです。実際の実装は RegExp.prototype[Symbol.match]() から来ています。

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

正規表現が渡されたときの match() の意味についての詳しい情報は、RegExp.prototype[Symbol.match]() を参照してください。

例

match() の使用

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

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

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

console.log(found);
// [
//   'see Chapter 3.4.5.1',
//   'Chapter 3.4.5.1',
//   '.1',
//   index: 22,
//   input: 'For more information, see Chapter 3.4.5.1',
//   groups: undefined
// ]

上の照合結果では、'see Chapter 3.4.5.1' が一致する文字列全体です。 'Chapter 3.4.5.1' は (chapter \d+(\.\d)*) によって捕捉されました。 '.1' は (\.\d) によって捕捉された最後の値です。 index プロパティ (22) は一致する文字列全体の 0 基点のインデックスです。 input プロパティは解釈できた元の文字列です。

match() での global と ignoreCase フラグの使用

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

js
const str = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz";
const regexp = /[A-E]/gi;
const matches = str.match(regexp);

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

メモ: String.prototype.matchAll() とフラグを用いた高度な検索も参照してください。

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

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

js
const paragraph = "The quick brown fox jumps over the lazy dog. It barked.";

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

引数なしの match() の使用

js
const str = "Nothing will come of nothing.";

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

match() を [Symbol.match]() を実装している RegExp でないオブジェクトで使用

オブジェクトに Symbol.match メソッドがある場合、カスタムマッチャーとして使用することができます。 Symbol.match の返値が match() の返値になります。

js
const str = "Hmm, this is interesting.";

str.match({
  [Symbol.match](str) {
    return ["Yes, it's interesting."];
  },
}); // returns ["Yes, it's interesting."]

RegExp 以外を引数として取る

正規表現 regexp 引数が文字列または数値の場合、RegExp に new RegExp(regexp) を使用して暗黙的に変換されます。

js
const str1 =
  "NaN means not a number. Infinity contains -Infinity and +Infinity in JavaScript.";
const str2 =
  "My grandfather is 65 years old and My grandmother is 63 years old.";
const str3 = "The contract was declared null and void.";
str1.match("number"); // "number" は文字列です。 ["number"] を返します。
str1.match(NaN); // NaN の型は数値です。 ["NaN"] を返します。
str1.match(Infinity); // Infinity の方は数値です。 ["Infinity"] を返します。
str1.match(+Infinity); // ["Infinity"] を返します
str1.match(-Infinity); // ["-Infinity"] を返します
str2.match(65); // ["65"] を返します
str2.match(+65); // 正の符号が付いた数値です。 ["65"] を返します
str3.match(null); // ["null"] を返します。

特殊文字が適切にエスケープされていないと、予期しない結果になることがあります。

js
console.log("123".match("1.3")); // [ "123" ]

正規表現中の . はどのような文字にも一致するので、これは一致します。 ドット文字にのみ一致するようにするには、入力文字列をエスケープする必要があります。

js
console.log("123".match("1\\.3")); // null

仕様書

Specification
ECMAScript Language Specification
# sec-string.prototype.match

ブラウザーの互換性

BCD tables only load in the browser

関連情報