CKTIS / JavaScript
String.prototype.matchAll — un iteratore di corrispondenze con gruppi di cattura
String.prototype.matchAll restituisce un iteratore sulle corrispondenze di un’espressione regolare, inclusi gruppi di cattura e posizioni. Con un RegExp ordinario è necessario il flag g e il lastIndex del modello originale resta invariato.
Versione: ECMAScript and Web APIs; exact feature edition and browser support reviewed per entry; Node 24 in repository does not prove browser API support
Sintassi
string.matchAll(regexp)String.prototype.matchAll permette di scorrere le corrispondenze di un modello in un testo. Con il comportamento standard di RegExp, restituisce un iteratore lazy: ogni passaggio produce un array in cui [0] contiene la corrispondenza completa e [1], [2] e gli elementi successivi contengono i gruppi di cattura. Un gruppo facoltativo senza corrispondenza vale undefined. La proprietà index indica la posizione in unità di codice UTF-16, input contiene il testo di input e groups espone i gruppi con nome, se presenti.
Se l’argomento è riconosciuto come espressione regolare, matchAll verifica la presenza del flag g prima di cercare Symbol.matchAll. Se il flag manca, la chiamata genera un TypeError. La ricerca comprende anche le proprietà ereditate: se il valore trovato è invocabile, matchAll lo invoca e ne restituisce il risultato. Se la proprietà è assente o vale undefined o null, matchAll crea dall’argomento un RegExp con il flag g. In questo caso, una stringa viene interpretata come modello di espressione regolare, non come testo letterale. Qualsiasi altro valore non invocabile di Symbol.matchAll genera un TypeError.
L’implementazione standard di RegExp crea una copia del modello e imposta il lastIndex iniziale della copia al valore ottenuto applicando ToLength al lastIndex dell’originale. Ad esempio, -1 diventa 0 e 2.9 diventa 2. Il lastIndex dell’originale resta invariato. Non dare quindi per scontato che la ricerca inizi sempre da zero. L’iteratore è utilizzabile una sola volta: una volta esaurito, non riparte. Nessuna corrispondenza significa un’iterazione vuota, non null; usa for...of per elaborare i risultati oppure [...iterator] per salvarli in un array.
A differenza di match con il flag g, matchAll conserva i gruppi di cattura per ogni corrispondenza. Il metodo fa parte di ECMAScript 2020, non delle Web APIs. La specifica da sola non stabilisce il supporto in uno specifico browser; nemmeno la presenza di Node 24 in un repository lo dimostra. Nell’ambiente di destinazione, la disponibilità si può verificare con typeof String.prototype.matchAll === "function".
Esempi
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}`);Risultato
x=12 | x | 12 | 0 y=7 | y | 7 | 5 lastIndex=0 remaining=0
Il codice mostrato e il risultato dichiarato sono stati verificati in un ambiente isolato con il metodo registrato nella prova di verifica di questa versione esatta.