RegExp.prototype[Symbol.search]()

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.

[Symbol.search]()RegExp インスタンスのメソッドで、 String.prototype.search がどのように動作するのかを指定します。

試してみましょう

class RegExp1 extends RegExp {
  constructor(str) {
    super(str);
    this.pattern = str;
  }
  [Symbol.search](str) {
    return str.indexOf(this.pattern);
  }
}

console.log("table football".search(new RegExp1("foo")));
// Expected output: 6

構文

js
regexp[Symbol.search](str)

引数

str

検索対象の文字列 (String) です。

返値

正規表現で指定された文字列が最初に一致したインデックスの値、または一致する文字列が見つからなかった場合は -1 を返します。

解説

このメソッドは、 String.prototype.search() の内部で呼び出されます。たとえば、次の 2 つの例は同じ結果を返します。

js
"abc".search(/a/);

/a/[Symbol.search]("abc");

このメソッドは Symbol.split[Symbol.matchAll]() とは異なり、正規表現をコピーしません。しかし、[Symbol.match]()[Symbol.replace]() とは異なり、実行を始めるときには lastIndex を 0 に設定し、終了するときには前回の値に戻すので、一般的に副作用を避けることができます。つまり、このメソッドでは g フラグは効果がなく、 lastIndex が 0 でない場合でも常に文字列の最初に一致した部分を返します。これは、粘着的正規表現が常に文字列の先頭を厳密に検索することも意味しています。

js
const re = /[abc]/g;
re.lastIndex = 2;
console.log("abc".search(re)); // 0

const re2 = /[bc]/y;
re2.lastIndex = 1;
console.log("abc".search(re2)); // -1
console.log("abc".match(re2)); // [ 'b' ]

[Symbol.search]() は常に正規表現の exec() を 1 回だけ呼び出し、結果の index プロパティを返すか、結果が null の場合は -1 を返します。

このメソッドは、RegExp サブクラスで検索動作をカスタマイズするために存在しています。

直接呼出し

このメソッドは、this と引数順が異なることを除いて String.prototype.search() とほぼ同じ方法で使用できます。

js
const re = /-/g;
const str = "2016-01-02";
const result = re[Symbol.search](str);
console.log(result); // 4

サブクラスでの [Symbol.search]() の使用

RegExp のサブクラスは、動作を修正するために [Symbol.search]() メソッドをオーバーライドできます。

js
class MyRegExp extends RegExp {
  constructor(str) {
    super(str);
    this.pattern = str;
  }
  [Symbol.search](str) {
    return str.indexOf(this.pattern);
  }
}

const re = new MyRegExp("a+b");
const str = "ab a+b";
const result = str.search(re); // String.prototype.search は再定義した [Symbol.search] を呼び出す。
console.log(result); // 3

仕様書

Specification
ECMAScript® 2025 Language Specification
# sec-regexp.prototype-%symbol.search%

ブラウザーの互換性

Report problems with this compatibility data on GitHub
desktopmobileserver
Chrome
Edge
Firefox
Opera
Safari
Chrome Android
Firefox for Android
Opera Android
Safari on iOS
Samsung Internet
WebView Android
WebView on iOS
Deno
Node.js
[Symbol.search]

Legend

Tip: you can click/tap on a cell for more information.

Full support
Full support

関連情報