String.prototype.matchAll() — Methode · JavaScript-Referenz

Signatur

matchAll(regexp)

Beschreibung

Die Methode matchAll() von String-Werten gibt einen Iterator aller Treffer zurück, die dieser String gegen einen regulären Ausdruck ergibt, einschließlich capturing groups.

Die Implementierung von String.prototype.matchAll tut kaum mehr, als die Symbol.matchAll-Methode des Arguments mit dem String als erstem Parameter aufzurufen (abgesehen von der zusätzlichen Eingabeprüfung, dass die Regex global ist). Die eigentliche Implementierung stammt aus RegExp.prototype[Symbol.matchAll]().

Parameter

Name	Typ	Default	Beschreibung
$regexp Pflicht	RegExp \| Object	—	Ein Objekt eines regulären Ausdrucks oder ein beliebiges Objekt, das eine `Symbol.matchAll`-Methode besitzt. Ist `regexp` kein `RegExp`-Objekt und besitzt keine `Symbol.matchAll`-Methode, wird es implizit mittels `new RegExp(regexp, 'g')` in ein `RegExp` umgewandelt. Ist `regexp` eine Regex, so muss sie das globale Flag (`g`) gesetzt haben, andernfalls wird ein `TypeError` geworfen.

Rückgabewert

Typ

Iterator

Beschreibung

Ein iterierbares Iterator-Objekt (das nicht neu gestartet werden kann) der Treffer oder ein leerer Iterator, wenn keine Treffer gefunden werden. Jeder vom Iterator gelieferte Wert ist ein Array mit derselben Form wie der Rückgabewert von RegExp.prototype.exec().

Beispiele

Regexp.prototype.exec() und matchAll()

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.

matchAll() mit for...of und Array.from()

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

Ausnahme bei fehlendem g-Flag

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

lastIndex bleibt unverändert

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

Besserer Zugriff auf capturing groups als bei String.prototype.match()

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

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

Zugriff auf capturing groups mit matchAll()

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]

matchAll() mit einem Nicht-RegExp, das [Symbol.matchAll]() implementiert

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

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

// Wichtig · Fallstricke

Wirft einen TypeError, wenn regexp eine Regex ist, die das globale Flag (g) nicht gesetzt hat (ihre flags-Eigenschaft enthält kein "g"). matchAll erstellt intern einen Klon der regexp — anders als bei regexp.exec() ändert sich lastIndex also nicht, während der String durchsucht wird. Das bedeutet jedoch auch, dass man lastIndex nicht mutieren kann, um die Regex vor- oder zurückzuspulen.

Siehe auch

String.prototype.match() RegExp RegExp.prototype.exec() RegExp.prototype.test() RegExp.prototype[Symbol.matchAll]()