String.prototype.matchAll()

regexp

Ein Regular-Expression-Objekt oder ein beliebiges Objekt, das eine Symbol.matchAll-Methode hat.

Wenn regexp kein RegExp-Objekt ist und keine Symbol.matchAll-Methode besitzt, wird es implizit durch new RegExp(regexp, 'g') in eine RegExp umgewandelt.

Wenn regexp ein Regex ist, muss es das globale (g)-Flag gesetzt haben, sonst 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 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 Regex ist, das nicht das globale (g)-Flag gesetzt hat (seine flags-Eigenschaft enthält kein "g").

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

Ohne matchAll() ist es möglich, Aufrufe zu regexp.exec() (und Regex 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 verfügbarem matchAll() können Sie die while-Schleife und exec mit g vermeiden. Stattdessen erhalten Sie einen Iterator, den Sie mit den bequemeren for...of, Array-Spreading oder Array.from()-Konstrukten verwenden können:

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 werfen, wenn das g-Flag fehlt.

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

matchAll erstellt intern einen Klon des regexp — also, 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, Sie lastIndex nicht ändern können, um das Regex vor- oder zurückzuspulen.

Ein weiterer überzeugender Grund für matchAll ist der verbesserte Zugang zu Capturing-Gruppen.

Capturing-Gruppen werden ignoriert, wenn Sie match() mit dem globalen g-Flag verwenden:

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

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

Mit matchAll können Sie einfach auf Capturing-Gruppen 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 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
• es-shims Polyfill von String.prototype.matchAll
• Leitfaden über reguläre Ausdrücke
• Leitfaden über Gruppen und Rückverweise
• String.prototype.match()
• RegExp
• RegExp.prototype.exec()
• RegExp.prototype.test()
• RegExp.prototype[Symbol.matchAll]()