RegExp.prototype[@@split]()

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.

[@@search]() は RegExp インスタンスのメソッドで、 String.prototype.split にセパレーターとして正規表現が渡されたときにどのように動作するのかを指定します。

試してみましょう

構文

js
regexp[Symbol.split](str)
regexp[Symbol.split](str, limit)

引数

str

分割操作の対象。

limit 省略可

検出される分割数の制限を指定する整数。 [@@split]() メソッドは、 this RegExp パターン (または上記の構文では regexp) に一致するたびに、分割項目の数が limit と一致するか、文字列が this パターンを満たなくなるまで、分割を行います。

返値

要素として部分文字列を含む配列 (Array)。

解説

このメソッドは String.prototype.split() において、RegExp がセパレーターとして渡された場合に内部的に呼び出されます。たとえば、次の 2 つの例は同じ結果を返します。

js
"a-b-c".split(/-/);

/-/[Symbol.split]("a-b-c");

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

RegExp.prototype[@@split]() ベースメソッドは、次のように動作します。

  • @@species を使用して新しい正規表現を構築し、元の正規表現が変更され内容にするところから始まります。
  • 正規表現の g （「グローバル」）フラグは無視され、 y （「粘着的」）フラグは元々表示されていない場合でも常に適用されます。
  • 対象とする文字列が空で、正規表現が空文字列に一致する場合（例えば /a?/）は、空の配列を返します。そうでない場合、正規表現が空文字列に一致しなければ [""] を返します。
  • 照合は this.exec() を連続して呼び出すことで行われます。正規表現は常に粘着的なので、文字列に沿って移動し、その度に一致する文字列、インデックス、キャプチャグループが得られます。
  • 一致するごとに、最後に一致した文字列の終わりと、現在一致した文字列の始めの間の部分文字列が、最初の配列に追加されます。その後、キャプチャグループの値が 1 つずつ追加されます。
  • 現在一致している文字列が空文字列であったり、正規表現が現在の位置で一致しなかったりした場合（粘着的なので）、lastIndex が進められます。正規表現が Unicode 対応であれば、Unicode コードポイント分進みます。そうでなければ、 UTF-16 コード単位 1 つ分進みます。
  • 正規表現が対象の文字列と一致しない場合は、対象の文字列を配列で囲んでそのまま返します。
  • 返される配列の長さは、指定された場合は limit 引数を超えることはありません。そのため、配列が既に埋まっている場合、最後の一致するグループとそのキャプチャグループがすべて返す配列に存在するとは限りません。

例

直接呼出し

this の扱いと引数の並び順を除いて、このメソッドは String.prototype.split() とほとんど同じように使用できます。

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

サブクラスで @@split を使用する

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

js
class MyRegExp extends RegExp {
  [Symbol.split](str, limit) {
    const result = RegExp.prototype[Symbol.split].call(this, str, limit);
    return result.map((x) => `(${x})`);
  }
}

const re = new MyRegExp("-");
const str = "2016-01-02";
const result = str.split(re); // String.prototype.split calls re[@@split].
console.log(result); // ["(2016)", "(01)", "(02)"]

仕様書

Specification
ECMAScript Language Specification
# sec-regexp.prototype-%symbol.split%

ブラウザーの互換性

BCD tables only load in the browser

関連情報