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 [Symbol.matchAll]()
-Methode von RegExp
-Instanzen legt fest, wie String.prototype.matchAll
funktionieren sollte.
Probieren Sie es aus
Syntax
regexp[Symbol.matchAll](str)
Parameter
Rückgabewert
Ein iterierbares Iterator-Objekt (das nicht neu gestartet werden kann) von Treffern. Jeder Treffer ist ein Array mit derselben Struktur wie der Rückgabewert von RegExp.prototype.exec()
.
Beschreibung
Diese Methode wird intern in String.prototype.matchAll()
aufgerufen. Beispielsweise liefern die folgenden zwei Beispiele dasselbe Ergebnis.
"abc".matchAll(/a/g);
/a/g[Symbol.matchAll]("abc");
Ähnlich wie [Symbol.split]()
verwendet [Symbol.matchAll]()
[Symbol.species]
, um ein neues Regex zu erstellen und so zu verhindern, dass das ursprüngliche Regex in irgendeiner Weise verändert wird. lastIndex
beginnt als der 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 Überprüfung, ob die Eingabe ein globales Regex ist, erfolgt in String.prototype.matchAll()
. [Symbol.matchAll]()
validiert die Eingabe nicht. Wenn das Regex nicht global ist, gibt der zurückgegebene Iterator das Ergebnis von exec()
einmal zurück und gibt dann undefined
zurück. Ist das Regex global, wird bei jedem Aufruf der next()
-Methode des zurückgegebenen Iterators das exec()
des Regex aufgerufen und das Ergebnis zurückgegeben.
Wenn das Regex sticky und global ist, werden weiterhin Sticky-Übereinstimmungen ausgeführt – d. h., es werden keine Vorkommen über den lastIndex
hinaus übereinstimmen.
console.log(Array.from("ab-c".matchAll(/[abc]/gy)));
// [ [ "a" ], [ "b" ] ]
Wenn die aktuelle Übereinstimmung ein leerer String ist, wird der lastIndex
dennoch vorgerückt. Wenn das Regex das u
-Flag hat, wird um einen Unicode-Codepunkt vorgerückt; andernfalls wird um einen UTF-16-Codepunkt vorgerückt.
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 auf fast dieselbe Weise wie String.prototype.matchAll()
verwendet werden, außer mit einem anderen Wert für this
und der anderen 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 [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("([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 Language Specification # sec-regexp-prototype-%symbol.matchall% |
Browser-Kompatibilität
BCD tables only load in the browser