Métodos RegExp do JavaScript
Expressões regulares em JavaScript permitem pesquisar, corresponder e manipular strings. Este guia aborda os principais métodos de RegExp e String.
As expressões regulares em JavaScript são uma forma poderosa de pesquisar, corresponder e manipular strings. Este guia aborda os principais métodos que você chama em uma expressão regular (test, exec) e em uma string (search, split, match, matchAll, replace, replaceAll), com um exemplo executável e o formato real de retorno de cada um. Compreender esses métodos permite que você gerencie a correspondência de padrões no seu código com eficiência.
Uma revisão rápida de regex
Antes dos métodos, uma orientação de um minuto para leitores novos em expressões regulares.
Um literal de regex é escrito entre barras, opcionalmente seguido de flags:
/pattern/flags // e.g. /hello/giVocê também pode criar um dinamicamente com o construtor RegExp, o que é útil quando o padrão vem de uma variável (observe que as barras invertidas devem ser duplicadas dentro de uma string):
const word = "hello";
const regex = new RegExp(word, "gi"); // same as /hello/gi
const digits = new RegExp("\\d+"); // same as /\d+/As flags alteram o comportamento da correspondência:
| Flag | Nome | Efeito |
|---|---|---|
g | global | Encontra todas as correspondências em vez de parar na primeira. |
i | ignorar maiúsculas | Torna a correspondência insensível a maiúsculas e minúsculas. |
m | multilinha | ^ e $ correspondem nas quebras de linha, não apenas no início e fim da string. |
s | dotAll | Permite que . também corresponda a caracteres de nova linha. |
u | unicode | Trata o padrão como uma sequência de pontos de código Unicode. |
y | sticky | Corresponde somente a partir exatamente de lastIndex. |
Para a sintaxe completa de padrões e detalhes de flags, consulte Padrões e Flags do JavaScript e Grupos de Captura. Muitos dos métodos abaixo também são documentados pelo lado da string em Strings do JavaScript.
RegExp.test()
O método test() testa uma string para verificar se há uma correspondência com uma expressão regular. Retorna true se uma correspondência for encontrada, ou false caso contrário.
Exemplo
Neste exemplo, o método test() verifica se a string "Hello world!" contém o padrão "hello". Como o método diferencia maiúsculas de minúsculas, retorna false. Adicione a flag i (/hello/i) e ele retornaria true.
RegExp.exec()
O método exec() pesquisa uma string por uma correspondência com uma expressão regular. Retorna um array contendo o texto correspondente e os grupos de captura, ou null se nenhuma correspondência for encontrada. O valor retornado não é um array simples: ele também carrega index (onde a correspondência começou), input (a string original) e groups (grupos de captura nomeados, ou undefined se não houver nenhum).
Exemplo
Aqui exec() encontra um ou mais dígitos em "The year is 2024.". O elemento 0 é a correspondência completa, o elemento 1 é o primeiro grupo de captura (\d+), e as propriedades extras informam onde a correspondência foi encontrada.
A armadilha do lastIndex com /g
Quando a regex tem a flag global (g) ou sticky (y), exec() torna-se stateful: cada chamada retoma a partir da propriedade lastIndex da regex e a avança, retornando null quando não há mais correspondências. Chame-a em um loop para percorrer cada correspondência — mas esteja ciente de que reutilizar a mesma regex /g em chamadas não relacionadas pode gerar resultados surpreendentes porque lastIndex é lembrado.
Sem a flag g, exec() não é stateful e sempre retorna a primeira correspondência, então um loop while como este seria executado indefinidamente. Para uso não global, prefira match() ou matchAll().
String.search()
O método search() testa uma string para verificar se há uma correspondência com uma expressão regular. Retorna o índice baseado em zero da primeira correspondência, ou -1 se nenhuma correspondência for encontrada.
Exemplo
Neste exemplo, o método search() retorna o índice da primeira ocorrência de "awesome" na string, que é 14.
String.split()
O método split() divide uma string em uma lista ordenada de substrings e as retorna em um array. É um método de string de uso geral: o separador pode ser uma string simples (str.split(",")) ou uma expressão regular. A forma com regex é apenas um caso de uso, prático quando o delimitador varia — por exemplo, dividir em um ou mais caracteres de espaço em branco.
Exemplo
A primeira chamada divide por uma vírgula literal; a segunda usa a regex /\s+/ para dividir em qualquer sequência de espaço em branco, de modo que múltiplos espaços e tabulações se transformam em separadores limpos.
String.match()
O método match() recupera o resultado da correspondência de uma string com uma expressão regular. Seu valor de retorno depende das flags:
- Com
/g: um array de todas as substrings correspondidas (semindexougroups), ounullse não houver correspondências. - Sem
/g: o mesmo array rico queexec()retorna — a primeira correspondência mais os grupos de captura, comindex,inputegroups— ounullse não houver correspondência.
Como match() retorna null em vez de um array vazio quando nada corresponde, sempre verifique o resultado antes de usá-lo.
Exemplo
Com a flag global, match() retorna todas as ocorrências de "ain"; um padrão que não corresponde retorna null, não um array vazio.
String.matchAll()
O método matchAll() retorna um iterador de todas as correspondências, incluindo os grupos de captura. Cada item que ele produz é um array completo de correspondência (um RegExpMatchArray), com o mesmo formato que exec() produz — portanto, cada correspondência carrega index, input e groups, não apenas as strings correspondidas. A expressão regular deve ter a flag g, ou matchAll() lança um TypeError. Ao contrário de exec() em um loop, matchAll() não deixa um lastIndex residual na sua regex, o que o torna a escolha mais limpa para iterar sobre cada correspondência. (Requer ES2020+.)
Exemplo
Como os itens são arrays de correspondência reais, você pode ler match.index e os grupos capturados (match[1], match[2], …) para cada resultado. Converta o iterador para um array com Array.from(str.matchAll(regex)) ou o operador spread quando precisar indexar os resultados.
String.replace()
O método replace() retorna uma nova string com as correspondências do padrão substituídas (a string original nunca é mutada). Com uma string simples ou uma regex sem /g, ele substitui apenas a primeira correspondência; adicione a flag g para substituir todas elas.
A string de substituição suporta tokens especiais: $& é a correspondência completa, $` e $' são o texto antes/depois dela, $n insere o n-ésimo grupo de captura, e $<name> insere um grupo nomeado.
Exemplo
Você também pode passar uma função como substituição; ela recebe a correspondência e os grupos capturados como argumentos e retorna o texto de substituição, o que é prático para valores calculados:
String.replaceAll()
O método replaceAll() substitui todas as ocorrências e retorna uma nova string. Quando você passa uma expressão regular, ela deve ter a flag g ou lança um TypeError — isso protege contra o erro comum de esperar que replace() seja global. Ele suporta os mesmos tokens de substituição $1 / $<name> e substituições por função que replace(). (Requer ES2021+.)
Exemplo
Use replaceAll() com uma string simples quando quiser simplesmente trocar todas as cópias de uma substring literal; use a forma com regex quando o alvo for um padrão.
Conclusão
Este guia abordou os principais métodos usados com expressões regulares em JavaScript — test e exec no lado da regex, e search, split, match, matchAll, replace e replaceAll no lado da string — junto com seus formatos reais de retorno e o comportamento stateful de lastIndex com a flag /g. Para se aprofundar nos próprios padrões, continue com Padrões e Flags, Grupos de Captura e a flag sticky y.