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

CKTIS / JavaScript

RegExp.prototype.test — verificar se existe uma correspondência

O método test() verifica se uma expressão regular corresponde a um texto e devolve true ou false. As flags g e y fazem com que a pesquisa use lastIndex, pelo que chamadas repetidas podem produzir resultados diferentes.

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

regexp.test(string)

Chama RegExp.prototype.test como regexp.test(string). Devolve true quando encontra uma correspondência e false caso contrário. Não devolve os grupos capturados; para os obter, usa exec(). O argumento é convertido em texto. Se for omitido, passa a ser o texto "undefined".

Por predefinição, basta que uma parte do texto corresponda. Para limitar a correspondência aos limites da entrada, usa as âncoras ^ e $, tendo em conta que a flag m as transforma em limites de linha.

Com a implementação padrão de exec(), as flags g e y usam lastIndex para determinar a posição inicial. Com g, a pesquisa pode experimentar posições posteriores, mas y não permite que avance. No modo Unicode (com u ou v), se lastIndex apontar para o substituto baixo de um par de substitutos UTF-16, uma correspondência pode começar no substituto alto que o antecede, mesmo com y. Se tiver êxito, lastIndex é definido para o fim da correspondência; se falhar, é reposto a zero. Se nenhuma das duas flags estiver presente, a implementação padrão de exec() lê mesmo assim lastIndex e aplica ToLength ao seu valor. Se a conversão for bem-sucedida, a pesquisa começa na posição 0 sem alterar a propriedade lastIndex. No entanto, se atribuíres um valor do tipo Symbol a lastIndex, test() lança uma exceção TypeError mesmo sem g nem y. Para verificações independentes, omite g e y ou define lastIndex = 0 antes de cada chamada.

Uma correspondência vazia não faz avançar automaticamente lastIndex: um ciclo baseado em test() pode não terminar. O método usa exec(), pelo que substituir esse método pode alterar o comportamento. Esta é uma API da linguagem ECMAScript, não uma API do browser.

Exemplos

const pattern = /cat/g;
console.log(pattern.test("cat"));
console.log(pattern.lastIndex);
console.log(pattern.test("cat"));
console.log(pattern.lastIndex);
pattern.lastIndex = 0;
console.log(pattern.test("cat"));

Resultado

true
3
false
0
true

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