String.prototype.match()

Resumo

O método match() retorna uma correspondência entre uma string com uma expressão regular.

Sintaxe

str.match(regexp);

Parâmetros

regexp
Um objeto de expressão regular. Se regexp não for uma RegExp, o mesmo será convertido para uma nova RegExp usando new RegExp(regexp).

Se você não fornecer nenhum parâmetro ao usar o método match(), você obterá um Array com uma string vazia: [""].

Valor retornado

  • Se o sinalizador g for usado, todos os resultados correspondentes à expressão regular serão retornados, mas a captura de grupos não.
  • se o sinalizador g não for usado, apenas a primeira correspondência completa e seus grupos de captura relacionados serão retornados. Nesse caso, o item devolvido terá propriedades adicionais conforme descrito a seguir.
array
Um Array cujo conteúdo depende da presença ou ausência do sinalizador global (g), ou null se nenhuma correspondência for encontrada.

Propriedades adicionais

Conforme explicado acima, alguns resultados contêm propriedades adicionais conforme descrito abaixo.

groups
Um objeto de grupos de captura nomeados cujas chaves são os nomes, e valores são os grupos de captura ou undefined se nenhum grupo de captura nomeado foi definido. Consulte Grupos e Intervalos para obter mais informações.
index
O índice da pesquisa em que o resultado foi encontrado.
input
Uma cópia da string pesquisada.

Descrição

Se a expressão regular não incluir o sinalizador g, str.match() retornará o mesmo resultado que RegExp.exec().

Veja também: métodos RegExp

  • Se você precisar saber se uma string corresponde a uma expressão regular, use RegExp.test().
  • Se você quiser encontrar apenas uma correspondência, 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 "Capítulo", seguido de um ou mais caracteres numéricos, seguido por um ponto decimal e caracteres numéricos 0 ou mais vezes. A expressão inclui a flag i para que diferenças de maiúscula/minúscula sejam ignoradas.

var str = "Para maiores informações, veja o Capítulo 3.4.5.1";
var re = /(capítulo \d+(\.\d)*)/i;
var found = str.match(re);

console.log(found);

// retorna ["Capítulo 3.4.5.1",
            "Capítulo 3.4.5.1",
            ".1",
            index: 33,
            input: "Para maiores informações, veja o Capítulo 3.4.5.1"]

// "Capítulo 3.4.5.1" é a primeira correspondência e o primeiro valor
//  capturado a partir de (capítulo \d+(\.\d)*).
// ".1" é o útlimo valor de (\.\d).
// A propriedade "index" (33) é o índice de base zero da correspôndencia 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 são retornadas, com cada letra sendo um elemento no array.

var str = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz";
var regexp = /[A-E]/gi;
var 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 código 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 parâmetros

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

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

Um objeto não-RegExp como parâmetro

Quando o parâmetro regexp é uma string ou um número, ele é convertido implicitamente em um RegExp usando o new RegExp(regexp).

Se for um número positivo com um sinal positivo, RegExp() irá ignorar o sinal positivo.

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

Especificações

Especificações Estado Comentário
ECMAScript 3rd Edition. Standard Definição inicial.
Implementado no JavaScript 1.2
ECMAScript 5.1 (ECMA-262)
The definition of 'String.prototype.match' in that specification.
Padrão
ECMAScript 2015 (6th Edition, ECMA-262)
The definition of 'String.prototype.match' in that specification.
Padrão

Estamos convertendo nossos dados de compatibilidade para o formato JSON. Esta tabela de compatibilidade ainda usa o formato antigo, pois ainda não convertemos os dados que ela contém. Descubra como você pode ajudar! (en-US)

característica Chrome Firefox (Gecko) Internet Explorer Opera Safari
Suporte Básico (Yes) (Yes) (Yes) (Yes) (Yes)
Característica Android Chrome for Android Firefox Mobile (Gecko) IE Mobile Opera Mobile Safari Mobile
Suporte Básico (Yes) (Yes) (Yes) (Yes) (Yes) (Yes)

Veja também