Base de conhecimentoCentro de Exames
PT · PTPortuguês (Portugal)
Escolher idioma13

CKTIS / JavaScript

String.prototype.matchAll — um iterador de correspondências com grupos de captura

String.prototype.matchAll devolve um iterador sobre as correspondências de uma expressão regular, incluindo grupos de captura e posições. Com um RegExp normal, a flag g é obrigatória e o lastIndex do padrão original não é alterado.

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

Sintaxe

string.matchAll(regexp)

String.prototype.matchAll permite percorrer as correspondências de um padrão num texto. Com o comportamento padrão de RegExp, devolve um iterador preguiçoso: cada passo produz um array cujo [0] contém a correspondência completa e cujos [1], [2] e elementos seguintes contêm os grupos de captura. Um grupo opcional sem correspondência tem o valor undefined. A propriedade index indica a posição em unidades de código UTF-16, input contém o texto de entrada e groups expõe os grupos com nome, se existirem.

Se o argumento for reconhecido como uma expressão regular, matchAll verifica se tem a flag g antes de procurar Symbol.matchAll. Se a flag estiver ausente, a chamada lança um TypeError. A procura inclui propriedades herdadas: se o valor encontrado puder ser invocado, matchAll invoca-o e devolve o respetivo resultado. Se a propriedade não existir ou tiver o valor undefined ou null, matchAll cria um RegExp a partir do argumento com a flag g. Neste caso, uma cadeia de caracteres é interpretada como um padrão de expressão regular, não como texto literal. Qualquer outro valor de Symbol.matchAll que não possa ser invocado provoca um TypeError.

A implementação padrão de RegExp cria uma cópia do padrão e define o lastIndex inicial da cópia com o resultado da aplicação de ToLength ao lastIndex do original. Por exemplo, -1 passa a 0 e 2.9 passa a 2. O lastIndex do original permanece inalterado. Por isso, não partas do princípio de que a pesquisa começa sempre em zero. O iterador só pode ser usado uma vez: depois de esgotado, não recomeça. Não haver correspondências significa uma iteração vazia, não null; usa for...of para processar os resultados ou [...iterator] para os guardar num array.

Ao contrário de match com a flag g, matchAll preserva os grupos de captura em cada correspondência. O método pertence ao ECMAScript 2020, não às Web APIs. A especificação, por si só, não comprova o suporte num navegador específico; a presença de Node 24 num repositório também não o comprova. No ambiente de destino, a disponibilidade pode ser verificada com typeof String.prototype.matchAll === "function".

Exemplos

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

Resultado

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

O código apresentado e o resultado declarado foram verificados num ambiente isolado pelo método registado na prova de verificação desta versão exata.

Fontes