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

CKTIS / JavaScript

String.prototype.match — correspondências de expressões regulares

O método match() procura correspondências de uma expressão regular numa cadeia de caracteres. A flag g altera a forma do resultado: sem ela, obténs no máximo uma correspondência com os grupos de captura; com ela, obténs um array de correspondências completas. Se não houver correspondência, o resultado é null.

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.match(regexp)

String.prototype.match procura correspondências de um padrão numa cadeia de caracteres sem a alterar. Com um objeto RegExp padrão, o resultado é um array ou null quando nada corresponde. Verifica se o resultado não é null antes de aceder aos seus elementos.

Sem g nem y, o método devolve a primeira correspondência, se existir. Com y mas sem g, tenta encontrar uma correspondência que comece exatamente na posição obtida ao aplicar ToLength ao valor atual de lastIndex. Pode, por isso, devolver uma correspondência posterior ou devolver null mesmo que o padrão corresponda noutra posição da cadeia. Por exemplo, se lastIndex estiver definido como -1 em /a/y, o padrão encontra uma correspondência no índice 0 de 'a'. Se encontrar uma correspondência sem g, o elemento 0 contém a correspondência completa e os elementos seguintes contêm os grupos de captura. A propriedade index indica a posição da correspondência em unidades de código UTF-16, e input contém a cadeia pesquisada. Com g, o array contém correspondências completas que não se sobrepõem, mas não inclui os grupos de captura nem esses metadados. Sem y, a pesquisa pode saltar as partes da cadeia que separam as correspondências. Com g e y em conjunto, a pesquisa termina assim que o padrão deixa de corresponder na posição atual. Por exemplo, 'a a'.match(/a/gy) devolve apenas ['a'], apesar de haver outro a no índice 2. Para manter os grupos de várias correspondências, utiliza matchAll().

Um argumento do tipo cadeia de caracteres é interpretado como um padrão de expressão regular, não como texto literal: "abc".match(".")[0] produz "a". Omitir o argumento ou passar undefined cria um padrão vazio, pelo que o resultado é uma correspondência com a cadeia vazia, não null.

Tecnicamente, o método delega em Symbol.match se o argumento fornecer esse método. Uma implementação personalizada pode, por isso, devolver um tipo de resultado diferente; o comportamento de array descrito acima corresponde ao comportamento padrão de RegExp.

Exemplos

const text = "item-12 item-34";
const first = text.match(/item-(\d+)/);
console.log(JSON.stringify([first[0], first[1], first.index]));
console.log(JSON.stringify(text.match(/item-(\d+)/g)));
console.log(text.match(/missing/g));

Resultado

["item-12","12",0]
["item-12","item-34"]
null

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