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

CKTIS / JavaScript

String.prototype.search — encontrar o índice de uma correspondência

O método search() encontra a primeira correspondência de uma expressão regular e devolve o respetivo índice ou -1. Um argumento do tipo cadeia é interpretado como um padrão, não como uma subcadeia literal.

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

String.prototype.search devolve o índice da primeira correspondência de um RegExp comum, ou -1 se não existir nenhuma. O índice começa em zero e é medido em unidades de código UTF-16, não em caracteres visíveis. O método não altera a cadeia nem devolve a subcadeia encontrada. Verifique o resultado com !== -1: o índice 0 indica uma correspondência bem-sucedida.

Se o argumento tiver um método [Symbol.search] invocável, próprio ou herdado, search() invoca-o em vez de criar uma nova expressão regular. As instâncias comuns de RegExp herdam este método de RegExp.prototype. Se o argumento for null ou undefined, ou se o acesso à sua propriedade [Symbol.search] devolver null ou undefined, search() cria uma expressão regular a partir do argumento. Qualquer outro valor não invocável dessa propriedade provoca um TypeError. Por isso, "abc".search(".") devolve 0: . corresponde a qualquer carácter, exceto um terminador de linha, e não a um ponto literal. Utilize indexOf() para procurar texto literal. Omitir o argumento ou passar undefined cria um padrão vazio e produz 0.

Com um RegExp comum, a flag g não recolhe todas as correspondências. A pesquisa começa com lastIndex definido como 0 e, após a conclusão normal, o valor anterior é reposto. A flag y continua a exigir uma correspondência no início da cadeia. O método não aceita um argumento que indique a posição inicial.

Um método [Symbol.search] personalizado pode definir completamente o comportamento, incluindo o tipo do resultado. No exemplo, os algarismos começam no índice 7, lastIndex mantém-se em 8 e a ausência de correspondência produz -1.

Exemplos

const text = "Order: 42";
const pattern = /\d+/g;
pattern.lastIndex = 8;

console.log(text.search(pattern));
console.log(pattern.lastIndex);
console.log(text.search(/missing/));
console.log("abc".search("."));

Resultado

7
8
-1
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