Znalostní bázeCentrum zkoušek
CSČeština
Vybrat jazyk13

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.

Zdroje