String.prototype.match()

Prubalo

const paragraph = "The quick brown fox jumps over the lazy dog. It barked.";
const regex = /[A-Z]/g;
const found = paragraph.match(regex);

console.log(found);
// Expected output: Array ["T", "I"]

Sintaxis

match(regexp)

Parmetros

regexp

Un objeto de expresin regular o cualquier objeto que tenga un mtodo Symbol.match.

Si regexp no es un objeto RegExp y no tiene un mtodo Symbol.match, se convierte implcitamente en RegExp usando new RegExp(regexp).

Si no se proporciona ningn parmetro y se utiliza el mtodo match() directamente, se obtendr un Array con una cadena vaca: [''], ya que esto es equivalente a match(/(?:)/).

Valor devuelto

Un Array cuyo contenido depende de la presencia de la bandera global (g), o null si no se encuentran coincidencias.

• Si se usa la bandera g, se devolvern todos los resultados que coincidan con la expresin regular completa, pero no se incluirn los grupos de captura.

• Si no se usa la bandera g, se devolvern slo la primera coincidencia completa y sus grupos de captura relacionados. En este caso, match() devolver el mismo resultado que RegExp.prototype.exec() (un Array con algunas propiedades adicionales).

Descripcin

La implementacin de String.prototype.match en s es muy simple. Se llama al mtodo Symbol.match del argumento con la cadena como primer parmetro. La implementacin real proviene de RegExp.prototype[@@match]().

• Si se necesita saber si una cadena coincide con una expresin regular RegExp, use RegExp.prototype.test().

• Si solo se desea que se encuentre la primera coincidencia, es posible que desee utilizar RegExp.prototype.exec() en su lugar.

• Si se desea obtener grupos de captura y la bandera global g est siendo utilizada, debe usar RegExp.prototype.exec() o String.prototype.matchAll() en su lugar.

Para obtener ms informacin sobre la semntica de match() cuando se pasa una expresin regular, consulte RegExp.prototype[@@match]().

Ejemplos

Uso de match()

En el siguiente ejemplo, se usa match para hallar 'Captulo' seguido de uno o ms caracteres numricos seguidos de un punto decimal y caracteres numricos cero o ms veces.

La expresin regular incluye la bandera i por lo que las diferencias entre maysculas y minsculas sern ignoradas.

const str = "Para ms informacin, consulte el Captulo 3.4.5.1";
const re = /consulte el (captulo \d+(\.\d)*)/i;
const found = str.match(re);

console.log(found);
// [
//   'consulte el Captulo 3.4.5.1',
//   'Captulo 3.4.5.1',
//   '.1',
//   index: 22,
//   input: 'Para ms informacin, consulte el Captulo 3.4.5.1',
//   groups: undefined
// ]

En el resultado anterior:

• 'consulte el Captulo 3.4.5.1' es la ocurrencia completa.
• 'Captulo 3.4.5.1' fue capturado por (captulo \d+(\.\d)*).
• '.1' fue el ltimo valor capturado por (\.\d).
• La propiedad index (22) es el ndice de la coincidencia completa.
• La propiedad input es la cadena original que se analiz.

Uso de las banderas global e ignoreCase

El siguiente ejemplo demuestra el uso de la bandera global e ignorar maysculas con match(). Se devuelven todas las letras de la A a la E y de la a a la e, cada una con su propio elemento en el array.

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

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

Uso de grupos de captura con nombre

En los navegadores que soporten grupos de captura con nombre, el siguiente cdigo captura 'zorro' o 'gato' en un grupo llamado animal:

const paragraph = "El veloz zorro marrn salta sobre el perro perezoso. Ladr.";
const capturingRegex = /(?<animal>zorro|gato) marrn/;
const found = paragraph.match(capturingRegex);

console.log(found.groups); // { animal: 'zorro' }

Uso de match() sin parmetros

const str = "Nada saldr de la nada.";

str.match(); // ['']

Uso de match() sin RegExp implementando @@match

Si un objeto tiene un mtodo Symbol.match, entonces se puede usar como un comparador personalizado. El valor de retorno de Symbol.match se convierte en el valor de retorno de match().

const str = "Mmmm, esto es interesante.";

str.match({
  [Symbol.match](str) {
    return ["S lo es!"];
  },
}); // Devuelve ['S lo es!']

Vase RegExp.prototype[@@match]().

Uso de parmetros distintos de RegEx

Cuando el parmetro regexp es una cadena o un nmero, se convierte implcitamente en RegExp mediante el uso de new RegExp(regexp).

const str1 =
  "NaN significa que no es un nmero. Infinity contiene -Infinity e +Infinity en JavaScript.";
const str2 = "Mi abuelo tiene 65 aos y mi abuela tiene 63 aos.";
const str3 = "El contrato fue declarado null (nulo) y sin efecto.";

str1.match("nmero"); // 'nmero' es una cadena - devuelve ['nmero']
str1.match(NaN); // NaN es de tipo nmero - devuelve ['NaN']
str1.match(Infinity); // Infinity es de tipo nmero - devuelve ['Infinity']
str1.match(+Infinity); // devuelve ['Infinity']
str1.match(-Infinity); // devuelve ['-Infinity']
str2.match(65); // devuelve ['65']
str2.match(+65); // un nmero con signo positivo - devuelve ['65']
str3.match(null); // devuelve ['null']

Esto puede tener resultados inesperados si los caracteres especiales no se escapan correctamente.

console.log("123".match("1.3")); // ['123']

Esta es una ocurrencia porque . en una expresin regular coincide con todos los caracteres. Para que solo coincida con el carcter de punto, se debe escapar de la entrada.

console.log("123".match("1\\.3")); // null

Especificaciones

Compatibilidad con navegadores

Vase tambin

• Polyfill de String.prototype.match en core-js con correcciones e implementacin del comportamiento moderno como el soporte para Symbol.match
• String.prototype.matchAll()
• RegExp
• RegExp.prototype.exec()
• RegExp.prototype.test()