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 July 2015.

Die Methode [Symbol.matchAll]() von RegExp-Instanzen legt fest, 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("-[0-9]+", "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, das das Ziel des Abgleichs ist.

Ein iterierbares Iterator-Objekt (welches nicht neu gestartet werden kann) von Übereinstimmungen. Jede Übereinstimmung 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");

Wie [Symbol.split]() beginnt [Symbol.matchAll]() damit, einen neuen Regex mithilfe von [Symbol.species] zu konstruieren, wodurch vermieden wird, den ursprünglichen Regex in irgendeiner Weise zu verändern. Der 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, ob die Eingabe ein globaler Regex ist, erfolgt in String.prototype.matchAll(). [Symbol.matchAll]() validiert die Eingabe nicht. Wenn der Regex nicht global ist, liefert der zurückgegebene Iterator das exec()-Ergebnis einmal und gibt dann undefined zurück. Wenn der Regex global ist, wird jedes Mal, wenn die next()-Methode des zurückgegebenen Iterators aufgerufen wird, das exec() des Regex aufgerufen und das Ergebnis wird geliefert.

Wenn der Regex sticky und global ist, werden immer noch Sticky-Matches durchgeführt, d.h. es werden keine Vorkommen hinter dem lastIndex gematcht.

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

Wenn das aktuelle Match eine leere Zeichenkette ist, wird der lastIndex trotzdem weitergeschaltet. Wenn der Regex das u-Flag hat, wird um einen Unicode-Codepunkt vorgerückt; 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-Subklassen anzupassen.

Beispiele

Direkter Aufruf

Diese Methode kann fast auf die gleiche Weise wie String.prototype.matchAll() verwendet werden, abgesehen von den unterschiedlichen Werten von this und der unterschiedlichen Reihenfolge der Argumente.

const re = /[0-9]+/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 Methode [Symbol.matchAll]() ü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("([0-9]+)-([0-9]+)-([0-9]+)", "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%