RegExp.prototype[Symbol.split]()

試してみましょう

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

console.log("2016-01-02".split(new RegExp1("-")));
// 予想される結果: Array ["(2016)", "(01)", "(02)"]

console.log("2016-01-02".split(/-/));
// 予想される結果: Array ["2016", "01", "02"]

構文

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

引数

str

分割操作の対象。

limit 省略可

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

返値

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

解説

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

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

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

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

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

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

例

直接呼出し

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

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

サブクラスで [Symbol.split]() を使用する

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

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 は re[Symbol.split]() を呼び出す
console.log(result); // ["(2016)", "(01)", "(02)"]

仕様書

ブラウザーの互換性

関連情報

• RegExp.prototype[Symbol.split] のポリフィル (core-js)
• String.prototype.split()
• RegExp.prototype[Symbol.match]()
• RegExp.prototype[Symbol.matchAll]()
• RegExp.prototype[Symbol.replace]()
• RegExp.prototype[Symbol.search]()
• RegExp.prototype.exec()
• RegExp.prototype.test()
• Symbol.split