String.prototype.matchAll()

regexp

Ein Objekt eines regulären Ausdrucks oder ein beliebiges Objekt, das eine Symbol.matchAll-Methode hat.

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 er das globale (g)-Flag gesetzt haben, sonst wird ein TypeError ausgelöst.

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

TypeError

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

Die Implementierung von String.prototype.matchAll macht 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 reguläre Ausdrücke 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() zur Verfügung können Sie die while-Schleife und exec mit g vermeiden. Stattdessen erhalten Sie einen Iterator, um ihn mit den bequemeren for...of, Array-Spread-Syntax oder Array.from() Konstrukten zu verwenden:

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 wird eine Ausnahme auslösen, wenn das g-Flag fehlt.

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

matchAll erstellt intern eine Kopie des regexp — anders als bei regexp.exec() ä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 im Gegensatz zur Verwendung von regexp.exec() in einer Schleife, lastIndex nicht verändert werden kann, um den regulären Ausdruck vor- oder zurückzuspulen.

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

Fanggruppen 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 auf Fanggruppen einfach 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 eine Symbol.matchAll Methode hat, kann es als benutzerdefinierter Matcher verwendet werden. Der Rückgabewert von Symbol.matchAll wird der 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
• es-shims Polyfill von String.prototype.matchAll
• Leitfaden zu regulären Ausdrücken
• Leitfaden zu Gruppen und Rückverweisen
• String.prototype.match()
• RegExp
• RegExp.prototype.exec()
• RegExp.prototype.test()
• RegExp.prototype[Symbol.matchAll]()