RegExp.prototype[Symbol.matchAll]()
Baseline
Weitgehend verfügbar
Diese Funktion ist gut etabliert und funktioniert auf vielen Geräten und in vielen Browserversionen. Sie ist seit Januar 2020 browserübergreifend verfügbar.
Die Methode [Symbol.matchAll]() von RegExp-Instanzen legt fest, wie sich String.prototype.matchAll verhalten 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
Rückgabewert
Ein iterierbares Iterator-Objekt mit Übereinstimmungen, das nicht neu gestartet werden kann. Jede Übereinstimmung ist ein Array mit derselben Struktur wie der Rückgabewert von RegExp.prototype.exec().
Beschreibung
Diese Methode dient dazu, das Verhalten von matchAll() in Unterklassen von RegExp anzupassen. Sie wird intern von String.prototype.matchAll() aufgerufen. Beispielsweise liefern die folgenden beiden Aufrufe dasselbe Ergebnis.
"abc".matchAll(/a/g);
/a/g[Symbol.matchAll]("abc");
Wie [Symbol.split]() erstellt [Symbol.matchAll]() zunächst mithilfe von [Symbol.species] einen neuen regulären Ausdruck. Dadurch wird der ursprüngliche reguläre Ausdruck in keiner Weise verändert. Der Konstruktor erhält this und die ursprünglichen Flags. Der Anfangswert von lastIndex entspricht dem Wert des ursprünglichen regulären Ausdrucks.
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" ]
Ist der reguläre Ausdruck global (mit dem Flag g), wird bei jedem Aufruf der Methode next() des zurückgegebenen Iterators exec() aufgerufen und das Ergebnis ausgegeben. Wenn die aktuelle Übereinstimmung eine leere Zeichenfolge ist, wird lastIndex dennoch erhöht. Hat der reguläre Ausdruck das Flag u, rückt die Position um einen Unicode-Codepunkt vor; andernfalls rückt sie um eine UTF-16-Codeeinheit vor.
console.log(Array.from("😄".matchAll(/(?:)/g)));
// [ [ "" ], [ "" ], [ "" ] ]
console.log(Array.from("😄".matchAll(/(?:)/gu)));
// [ [ "" ], [ "" ] ]
Ist der reguläre Ausdruck nicht global, gibt der zurückgegebene Iterator das Ergebnis von exec() einmal aus und endet dann. (Die Prüfung, ob die Eingabe ein globaler regulärer Ausdruck ist, erfolgt in String.prototype.matchAll(). [Symbol.matchAll]() prüft die Flags von this nicht.)
Ist der reguläre Ausdruck sowohl sticky als auch global, sucht er weiterhin nur an der durch lastIndex festgelegten Position nach einer Übereinstimmung – Vorkommen hinter lastIndex werden also nicht gefunden.
console.log(Array.from("ab-c".matchAll(/[abc]/gy)));
// [ [ "a" ], [ "b" ] ]
Beispiele
Direkter Aufruf
Diese Methode kann nahezu genauso verwendet werden wie String.prototype.matchAll(). Unterschiede bestehen im Wert von this und in der 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" ]
[Symbol.matchAll]() in Unterklassen verwenden
Unterklassen von RegExp können die Methode [Symbol.matchAll]() überschreiben, um das Standardverhalten zu ändern.
Um beispielsweise ein Array statt 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
| Spezifikation |
|---|
| ECMAScript® 2027 Language Specification # sec-regexp-prototype-%symbol.matchall% |