RegExp.prototype[Symbol.matchAll]()

str

Ein String, der das Ziel für den Abgleich darstellt.

Ein iterierbares Iterator-Objekt (das nicht neu gestartet werden kann) mit Übereinstimmungen. Jede Übereinstimmung ist ein Array mit derselben Form wie der Rückgabewert von RegExp.prototype.exec().

Diese Methode wird intern in String.prototype.matchAll() aufgerufen. Zum Beispiel liefern die folgenden beiden 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 konstruieren, wodurch vermieden wird, das ursprüngliche Regex in irgendeiner Weise zu verändern. lastIndex beginnt als 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 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 dann undefined. Wenn das Regex global ist, wird jedes Mal, wenn die next()-Methode des zurückgegebenen Iterators aufgerufen wird, das Regex' exec() aufgerufen und das Ergebnis zurückgegeben.

Wenn das Regex sowohl sticky als auch global ist, werden weiterhin sticky Matches durchgeführt — das heißt, es werden keine Vorkommen jenseits des lastIndex gefunden.

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

Wenn die aktuelle Übereinstimmung ein leerer String ist, wird der lastIndex trotzdem erhöht. Wenn das Regex das u Flag hat, wird es um einen Unicode-Codepunkt weitergeschaltet; andernfalls wird es um einen UTF-16-Codepunkt weitergeschaltet.

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

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

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

Diese Methode kann fast auf die gleiche Weise wie String.prototype.matchAll() verwendet werden, abgesehen von dem unterschiedlichen Wert 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" ]

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" ]

• Polyfill von RegExp.prototype[Symbol.matchAll] in core-js
• es-shims Polyfill von RegExp.prototype[Symbol.matchAll]
• String.prototype.matchAll()
• RegExp.prototype[Symbol.match]()
• RegExp.prototype[Symbol.replace]()
• RegExp.prototype[Symbol.search]()
• RegExp.prototype[Symbol.split]()
• Symbol.matchAll