String.prototype.matchAll()

regexp

Ein reguläres Ausdrucksobjekt oder jedes Objekt, das eine Symbol.matchAll Methode besitzt.

Wenn regexp kein RegExp Objekt ist und keine Symbol.matchAll Methode hat, wird es implizit in ein RegExp umgewandelt, indem new RegExp(regexp, 'g') verwendet wird.

Wenn regexp ein regulärer Ausdruck ist, muss das globale (g) Flag gesetzt sein, andernfalls wird ein TypeError ausgelöst.

Ein iterierbares Iterator-Objekt (das nicht neustartbar ist) von Übereinstimmungen oder ein leerer Iterator, wenn keine Übereinstimmungen gefunden werden. Jeder Wert, der vom Iterator geliefert wird, ist ein Array mit der gleichen Struktur wie der Rückgabewert von RegExp.prototype.exec().

TypeError

Wird ausgelöst, wenn das regexp ein regulärer Ausdruck ist, der das globale (g) Flag nicht gesetzt hat (seine flags Eigenschaft enthält kein "g").

Die Implementierung von String.prototype.matchAll tut nicht viel anderes, als die Symbol.matchAll Methode des Arguments mit dem String als erstem Parameter aufzurufen (abgesehen von der zusätzlichen Eingabevalidierung, dass der reguläre Ausdruck global ist). Die eigentliche Implementierung stammt von RegExp.prototype[Symbol.matchAll]().

Ohne matchAll() ist es möglich, Aufrufe von regexp.exec() (und RegExps mit dem g Flag) in einer Schleife zu verwenden, um alle Übereinstimmungen zu erhalten:

const regexp = /foo[a-z]*/g;
const str = "table football, foosball";
let match;

while ((match = regexp.exec(str)) !== null) {
  console.log(
    `Found ${match[0]} start=${match.index} end=${regexp.lastIndex}.`,
  );
}
// Found football start=6 end=14.
// Found foosball start=16 end=24.

Mit matchAll() verfügbar können Sie die while Schleife und exec mit g vermeiden. Stattdessen erhalten Sie einen Iterator zur Verwendung mit der bequemeren for...of, Array-Spreading oder Array.from() Konstrukten:

const regexp = /foo[a-z]*/g;
const str = "table football, foosball";
const matches = str.matchAll(regexp);

for (const match of matches) {
  console.log(
    `Found ${match[0]} start=${match.index} end=${
      match.index + match[0].length
    }.`,
  );
}
// Found football start=6 end=14.
// Found foosball start=16 end=24.

// matches iterator is exhausted after the for...of iteration
// Call matchAll again to create a new iterator
Array.from(str.matchAll(regexp), (m) => m[0]);
// [ "football", "foosball" ]

matchAll löst eine Ausnahme aus, wenn das g Flag fehlt.

const regexp = /[a-c]/;
const str = "abc";
str.matchAll(regexp);
// TypeError

matchAll erzeugt intern einen Klon des regexp — daher ändert sich lastIndex nicht, während der String durchsucht wird.

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

Dies bedeutet jedoch, dass Sie im Gegensatz zur Verwendung von regexp.exec() in einer Schleife lastIndex nicht ändern können, um den regulären Ausdruck vor- oder zurückzusetzen.

Ein weiterer überzeugender Grund für matchAll ist der verbesserte Zugriff auf Erfassungsgruppen.

Erfassungsgruppen werden ignoriert, wenn match() mit dem globalen g Flag verwendet wird:

const regexp = /t(e)(st(\d?))/g;
const str = "test1test2";

str.match(regexp); // ['test1', 'test2']

Mit matchAll können Sie einfach auf Erfassungsgruppen zugreifen:

const array = [...str.matchAll(regexp)];

array[0];
// ['test1', 'e', 'st1', '1', index: 0, input: 'test1test2', length: 4]
array[1];
// ['test2', 'e', 'st2', '2', index: 5, input: 'test1test2', length: 4]

Wenn ein Objekt über eine Symbol.matchAll Methode verfügt, kann es als benutzerdefinierter Matcher verwendet werden. Der Rückgabewert von Symbol.matchAll wird zum Rückgabewert von matchAll().

const str = "Hmm, this is interesting.";

str.matchAll({
  [Symbol.matchAll](str) {
    return [["Yes, it's interesting."]];
  },
}); // returns [["Yes, it's interesting."]]

• Polyfill von String.prototype.matchAll in core-js
• String.prototype.match()
• Reguläre Ausdrücke Leitfaden
• Gruppen und Rückverweise Leitfaden
• RegExp
• RegExp.prototype.exec()
• RegExp.prototype.test()
• RegExp.prototype[Symbol.matchAll]()