RegExp.prototype[Symbol.matchAll]()

Baseline Widely available

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

Die Methode [Symbol.matchAll]() von RegExp-Instanzen gibt an, wie String.prototype.matchAll funktionieren soll.

Probieren Sie es aus

class MyRegExp extends RegExp {
  [Symbol.matchAll](str) {
    const result = RegExp.prototype[Symbol.matchAll].call(this, str);
    if (!result) {
      return null;
    }
    return Array.from(result);
  }
}

const re = new MyRegExp("-\\d+", "g");
console.log("2016-01-02|2019-03-07".matchAll(re));
// Expected output: Array [Array ["-01"], Array ["-02"], Array ["-03"], Array ["-07"]]

Syntax

regexp[Symbol.matchAll](str)

Parameter

str: Ein String, der das Ziel des Suchvorgangs ist.

Rückgabewert

Ein iterierbares Iterator-Objekt (welches nicht neu gestartet werden kann) von Treffern. Jeder Treffer ist ein Array mit der gleichen Struktur wie der Rückgabewert von RegExp.prototype.exec().

Beschreibung

Diese Methode wird intern in String.prototype.matchAll() aufgerufen. Zum Beispiel liefern die folgenden beiden Beispiele das gleiche Ergebnis.

"abc".matchAll(/a/g);

/a/g[Symbol.matchAll]("abc");

Ähnlich wie [Symbol.split]() beginnt [Symbol.matchAll]() mit der Verwendung von [Symbol.species], um ein neues Regex zu erstellen, was eine Veränderung des ursprünglichen Regex in jeglicher Weise vermeidet. lastIndex beginnt mit dem Wert des ursprünglichen Regex.

const regexp = /[a-c]/g;
regexp.lastIndex = 1;
const str = "abc";
Array.from(str.matchAll(regexp), (m) => `${regexp.lastIndex} ${m[0]}`);
// [ "1 b", "1 c" ]

Die Validierung, dass der Input ein globales Regex ist, erfolgt in String.prototype.matchAll(). [Symbol.matchAll]() validiert den Input nicht. Wenn das Regex nicht global ist, liefert der zurückgegebene Iterator das Ergebnis von exec() einmal und gibt dann undefined zurück. Wenn das Regex global ist, wird jedes Mal, wenn die next()-Methode des zurückgegebenen Iterators aufgerufen wird, das exec()-Ergebnis des Regex aufgerufen und das Ergebnis geliefert.

Wenn das Regex sticky und global ist, führt es weiterhin sticky Matches durch – das heißt, es werden keine Vorkommen über das lastIndex hinaus berücksichtigt.

console.log(Array.from("ab-c".matchAll(/[abc]/gy)));
// [ [ "a" ], [ "b" ] ]

Wenn der aktuelle Treffer ein leerer String ist, wird der lastIndex trotzdem weitergesetzt. Wenn das Regex das u-Flag hat, wird es um einen Unicode-Codepunkt weitergesetzt; andernfalls um einen UTF-16-Codepunkt.

console.log(Array.from("😄".matchAll(/(?:)/g)));
// [ [ "" ], [ "" ], [ "" ] ]

console.log(Array.from("😄".matchAll(/(?:)/gu)));
// [ [ "" ], [ "" ] ]

Diese Methode existiert, um das Verhalten von matchAll() in RegExp-Unterklassen anzupassen.

Beispiele

Direkter Aufruf

Diese Methode kann fast auf die gleiche Weise verwendet werden wie String.prototype.matchAll(), mit Ausnahme des unterschiedlichen Werts von this und der unterschiedlichen Reihenfolge der Argumente.

const re = /\d+/g;
const str = "2016-01-02";
const result = re[Symbol.matchAll](str);

console.log(Array.from(result, (x) => x[0]));
// [ "2016", "01", "02" ]

Verwendung von `[Symbol.matchAll]()` in Unterklassen

Unterklassen von RegExp können die [Symbol.matchAll]()-Methode überschreiben, um das Standardverhalten zu ändern.

Zum Beispiel, um ein Array anstelle eines Iterators zurückzugeben:

class MyRegExp extends RegExp {
  [Symbol.matchAll](str) {
    const result = RegExp.prototype[Symbol.matchAll].call(this, str);
    return result ? Array.from(result) : null;
  }
}

const re = new MyRegExp("(\\d+)-(\\d+)-(\\d+)", "g");
const str = "2016-01-02|2019-03-07";
const result = str.matchAll(re);

console.log(result[0]);
// [ "2016-01-02", "2016", "01", "02" ]

console.log(result[1]);
// [ "2019-03-07", "2019", "03", "07" ]

Spezifikationen

Specification
ECMAScript® 2026 Language Specification # sec-regexp-prototype-%symbol.matchall%