CKTIS / JavaScript
String.prototype.matchAll — iterátor shod se zachytávacími skupinami
String.prototype.matchAll vrací iterátor shod regulárního výrazu včetně zachytávacích skupin a pozic. U běžného RegExp vyžaduje příznak g a lastIndex původního vzoru zůstane nezměněn.
Verze: ECMAScript and Web APIs; exact feature edition and browser support reviewed per entry; Node 24 in repository does not prove browser API support
Syntaxe
string.matchAll(regexp)String.prototype.matchAll umožňuje procházet shody vzoru v textu. Při standardním chování RegExp vrací líný iterátor: každý krok poskytne pole, jehož [0] obsahuje celou shodu a [1], [2] atd. zachytávací skupiny. Neodpovídající nepovinná skupina má hodnotu undefined. Vlastnost index udává pozici v jednotkách kódu UTF-16, input obsahuje vstupní text a groups zpřístupňuje pojmenované skupiny, pokud existují.
Pokud je argument rozpoznán jako regulární výraz, matchAll zkontroluje příznak g před vyhledáním Symbol.matchAll. Chybí-li příznak, volání vyvolá TypeError. Vyhledávání zahrnuje i zděděné vlastnosti: pokud lze nalezenou hodnotu zavolat, matchAll ji zavolá a vrátí její výsledek. Pokud vlastnost chybí nebo má hodnotu undefined či null, matchAll z argumentu vytvoří RegExp s příznakem g. V tomto případě se řetězec použije jako vzor regulárního výrazu, nikoli jako doslovný text. Jakákoli jiná hodnota Symbol.matchAll, kterou nelze zavolat, vyvolá TypeError.
Standardní implementace RegExp vytvoří kopii vzoru a jako její počáteční hodnotu lastIndex nastaví výsledek operace ToLength použité na lastIndex původního vzoru. Například z -1 vznikne 0 a z 2.9 vznikne 2. Hodnota lastIndex původního vzoru se nemění. Nepředpokládejte tedy, že hledání vždy začíná od nuly. Iterátor lze použít pouze jednou: po vyčerpání nezačne znovu. Žádné shody znamenají prázdnou iteraci, nikoli null; výsledky zpracujte pomocí for...of nebo je uložte do pole pomocí [...iterator].
Na rozdíl od match s příznakem g zachovává matchAll zachytávací skupiny pro každou shodu. Metoda patří do ECMAScript 2020, nikoli do Web APIs. Samotná specifikace nepotvrzuje podporu v konkrétním prohlížeči; nedokazuje ji ani přítomnost Node 24 v repozitáři. Dostupnost v cílovém prostředí lze ověřit pomocí typeof String.prototype.matchAll === "function".
Příklady
const text = "x=12 y=7";
const pattern = /([a-z])=(\d+)/g;
const matches = text.matchAll(pattern);
for (const match of matches) {
console.log(`${match[0]} | ${match[1]} | ${match[2]} | ${match.index}`);
}
console.log(`lastIndex=${pattern.lastIndex}`);
console.log(`remaining=${[...matches].length}`);Výsledek
x=12 | x | 12 | 0 y=7 | y | 7 | 5 lastIndex=0 remaining=0
Zobrazený kód a uvedený výsledek byly ověřeny v izolovaném prostředí metodou zaznamenanou v dokladu o ověření této přesné verze.