String.prototype.match()

Sintaxe

str.match(regexp);

Parmetros

regexp

Um objeto de expresso regular. Se regexp no for uma RegExp, o mesmo ser convertido para uma nova RegExp usando new RegExp(regexp).

Se voc no fornecer nenhum parmetro ao usar o mtodo match(), voc obter um Array com uma string vazia: [""].

Valor retornado

• Se o sinalizador g for usado, todos os resultados correspondentes expresso regular sero retornados, mas a captura de grupos no.
• se o sinalizador g no for usado, apenas a primeira correspondncia completa e seus grupos de captura relacionados sero retornados. Nesse caso, o item devolvido ter propriedades adicionais conforme descrito a seguir.

array

Um Array cujo contedo depende da presena ou ausncia do sinalizador global (g), ou null se nenhuma correspondncia for encontrada.

Propriedades adicionais

Conforme explicado acima, alguns resultados contm propriedades adicionais conforme descrito abaixo.

groups

Um objeto de grupos de captura nomeados cujas chaves so os nomes, e valores so os grupos de captura ou undefined se nenhum grupo de captura nomeado foi definido. Consulte Grupos e Intervalos para obter mais informaes.

index

O ndice da pesquisa em que o resultado foi encontrado.

input

Uma cpia da string pesquisada.

Descrio

Se a expresso regular no incluir o sinalizador g, str.match() retornar o mesmo resultado que RegExp.exec().

Veja tambm: mtodos RegExp

• Se voc precisar saber se uma string corresponde a uma expresso regular, use RegExp.test().
• Se voc quiser encontrar apenas uma correspondncia, voc pode querer usar RegExp.exec().
• Se voc deseja obter grupos de captura e o sinalizador global (g) est definido, voc precisa usar RegExp.exec() ou String.prototype.matchAll() em vez disso.

Exemplos

Usando match()

No exemplo a seguir, match() usado para encontrar "Captulo", seguido de um ou mais caracteres numricos, seguido por um ponto decimal e caracteres numricos 0 ou mais vezes. A expresso inclui a flag i para que diferenas de maiscula/minscula sejam ignoradas.

const str = "Para maiores informaes, veja o Captulo 3.4.5.1";
const re = /(captulo \d+(\.\d)*)/i;
const found = str.match(re);

console.log(found);

// retorna ["Captulo 3.4.5.1",
            "Captulo 3.4.5.1",
            ".1",
            index: 33,
            input: "Para maiores informaes, veja o Captulo 3.4.5.1"]

// "Captulo 3.4.5.1"  a primeira correspondncia e o primeiro valor
//  capturado a partir de (captulo \d+(\.\d)*).
// ".1"  o tlimo valor de (\.\d).
// A propriedade "index" (33)  o ndice de base zero da correspndencia inteira.
// A propriedade "input"  a string original que foi analisada.

Usando as bandeiras (flags) global e ignore com
match()

O exemplo a seguir demonstra o uso das bandeiras (flags) global e ignore com match(). Todas as letras de A a E e a a e so retornadas, com cada letra sendo um elemento no array.

const str = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz";
const regexp = /[A-E]/gi;
const matches_array = str.match(regexp);

console.log(matches_array);
// ['A', 'B', 'C', 'D', 'E', 'a', 'b', 'c', 'd', 'e']

Usando grupos de captura nomeados

Em navegadores que suportam grupos de captura nomeados, o cdigo a seguir captura "fox" ou "cat" em um grupo denominado "animal":

const paragraph = "The quick brown fox jumps over the lazy dog. It barked.";

const capturingRegex = /(?<animal>fox|cat) jumps over/;
const found = paragraph.match(capturingRegex);
console.log(found.groups); // {animal: "fox"}

Usando match() sem parmetros

const str = "nada se perde, tudo se transforma";

str.match(); // retorna [""]

Um objeto no-RegExp como parmetro

Quando o parmetro regexp uma string ou um nmero, ele convertido implicitamente em um RegExp usando o new RegExp(regexp).

Se for um nmero positivo com um sinal positivo, RegExp() ir ignorar o sinal positivo.

const str1 =
  "NaN significa 'no  um nmero'. Infinity contem -Infinity e +Infinity em JavaScript.";
const str2 = "Meu av tem 65 anos e minha av tem 63.";
const str3 = "O contrato foi declarado null (nulo) e void (sem efeito)";
str1.match("nmero"); // "nmero"  um string. retorna ["nmero"]
str1.match(NaN); // o tipo de NaN  um nmero. retorna ["NaN"]
str1.match(Infinity); // o tipo de Infinity  um nmero. retorna ["Infinity"]
str1.match(+Infinity); // retorna ["Infinity"]
str1.match(-Infinity); // retorna ["-Infinity"]
str2.match(65); // retorna ["65"]
str2.match(+65); // Um nmero com sinal positivo. retorna ["65"]
str3.match(null); // retorna ["null"]

Especificaes

Navegadores compatveis

Veja tambm

• RegExp.prototype.exec()
• RegExp.prototype.test()