KennisbankExamencentrum
NL · NLNederlands (Nederland)
Taal kiezen13

CKTIS / JavaScript

String.prototype.matchAll — een iterator voor overeenkomsten met capturegroepen

String.prototype.matchAll geeft een iterator terug voor overeenkomsten met een reguliere expressie, inclusief capturegroepen en posities. Bij een gewone RegExp is de vlag g vereist en blijft de lastIndex van het oorspronkelijke patroon ongewijzigd.

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

Syntax

string.matchAll(regexp)

Met String.prototype.matchAll kun je de overeenkomsten van een patroon in tekst doorlopen. Bij standaardgedrag van RegExp geeft de methode een luie iterator terug: elke stap levert een array op waarvan [0] de volledige overeenkomst bevat en [1], [2] enzovoort de capturegroepen bevatten. Een optionele groep zonder overeenkomst heeft de waarde undefined. De eigenschap index geeft de positie in UTF-16-code-eenheden aan, input bevat de invoertekst en groups biedt toegang tot eventuele benoemde groepen.

Als het argument als reguliere expressie wordt herkend, controleert matchAll de vlag g voordat het Symbol.matchAll opzoekt. Ontbreekt die vlag, dan veroorzaakt de aanroep een TypeError. Bij het opzoeken tellen ook overgeërfde eigenschappen mee: als de gevonden waarde aanroepbaar is, roept matchAll die aan en geeft het resultaat terug. Als de eigenschap ontbreekt of de waarde undefined of null is, maakt matchAll van het argument een RegExp met de vlag g. In dat geval wordt een tekenreeks als patroon voor een reguliere expressie geïnterpreteerd, niet als letterlijke tekst. Elke andere niet-aanroepbare waarde van Symbol.matchAll veroorzaakt een TypeError.

De standaardimplementatie van RegExp maakt een kopie van het patroon en past ToLength toe op de lastIndex van het origineel om de beginwaarde van lastIndex voor de kopie te bepalen. Zo wordt -1 bijvoorbeeld 0 en wordt 2.9 omgezet in 2. De lastIndex van het origineel blijft ongewijzigd. Ga er dus niet van uit dat de zoekactie altijd bij nul begint. De iterator kan maar één keer worden gebruikt: eenmaal uitgeput begint hij niet opnieuw. Geen overeenkomsten betekent een lege iteratie, niet null; gebruik for...of om resultaten te verwerken of [...iterator] om ze in een array op te slaan.

In tegenstelling tot match met de vlag g bewaart matchAll de capturegroepen voor elke overeenkomst. De methode maakt deel uit van ECMAScript 2020, niet van de Web APIs. De specificatie alleen bewijst niet dat een bepaalde browser de methode ondersteunt; Node 24 in een repository bewijst dat evenmin. Je kunt de beschikbaarheid in de doelomgeving controleren met typeof String.prototype.matchAll === "function".

Voorbeelden

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

Resultaat

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

De getoonde code en het opgegeven resultaat zijn in een geïsoleerde omgeving geverifieerd met de methode die in het verificatiebewijs voor exact deze versie is vastgelegd.

Bronnen