Baza znanjaIzpitno središče
SLSlovenščina
Izberi jezik13

CKTIS / JavaScript

String.prototype.matchAll — iterator zadetkov z zajemalnimi skupinami

String.prototype.matchAll vrne iterator zadetkov regularnega izraza, vključno z zajemalnimi skupinami in položaji. Pri običajnem RegExp zahteva zastavico g, lastIndex izvirnega vzorca pa ostane nespremenjen.

Različica: ECMAScript and Web APIs; exact feature edition and browser support reviewed per entry; Node 24 in repository does not prove browser API support

Sintaksa

string.matchAll(regexp)

String.prototype.matchAll omogoča pregledovanje zadetkov vzorca v besedilu. Pri standardnem delovanju RegExp vrne len iterator: vsak korak ustvari polje, v katerem [0] vsebuje celoten zadetek, [1], [2] itd. pa zajemalne skupine. Neujemajoča se neobvezna skupina ima vrednost undefined. Lastnost index označuje položaj v kodnih enotah UTF-16, input vsebuje vhodno besedilo, groups pa omogoča dostop do poimenovanih skupin, če obstajajo.

Če je argument prepoznan kot regularni izraz, matchAll preveri zastavico g, preden poišče Symbol.matchAll. Če zastavice ni, klic sproži TypeError. Pri iskanju upošteva tudi podedovane lastnosti: če je najdena vrednost klicljiva, jo matchAll pokliče in vrne njen rezultat. Če lastnost manjka ali je njena vrednost undefined ali null, matchAll iz argumenta ustvari RegExp z zastavico g. V tem primeru niz obravnava kot vzorec regularnega izraza, ne kot dobesedno besedilo. Vsaka druga neklicljiva vrednost lastnosti Symbol.matchAll sproži TypeError.

Standardna izvedba RegExp ustvari kopijo vzorca in njen začetni lastIndex nastavi na rezultat operacije ToLength, uporabljene na vrednosti lastIndex izvirnika. Tako se na primer -1 pretvori v 0, 2.9 pa v 2. Vrednost lastIndex izvirnika ostane nespremenjena. Zato ne predpostavljaj, da se iskanje vedno začne pri nič. Iterator je mogoče uporabiti samo enkrat: ko je izčrpan, se ne začne znova. Če ni zadetkov, je iteracija prazna, ne null; za obdelavo rezultatov uporabi for...of ali jih shrani v polje z [...iterator].

Za razliko od match z zastavico g matchAll ohrani zajemalne skupine pri vsakem zadetku. Metoda je del ECMAScript 2020, ne Web APIs. Sama specifikacija ne potrjuje podpore v določenem brskalniku; tega ne dokazuje niti prisotnost Node 24 v repozitoriju. Razpoložljivost v ciljnem okolju lahko preveriš z typeof String.prototype.matchAll === "function".

Primeri

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}`);

Rezultat

x=12 | x | 12 | 0
y=7 | y | 7 | 5
lastIndex=0
remaining=0

Prikazana koda in navedeni rezultat sta bila preverjena v izoliranem okolju z metodo, zapisano v dokazilu o preverjanju te natančne različice.

Viri