String.prototype.match()

regexp

Un objeto de expresión regular o cualquier objeto que tenga un método Symbol.match.

Si regexp no es un objeto RegExp y no tiene un método Symbol.match, se convierte implícitamente en RegExp usando new RegExp(regexp).

Si no se proporciona ningún parámetro y se utiliza el método match() directamente, se obtendrá un Array con una cadena vacía: [''], ya que esto es equivalente a match(/(?:)/).

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 devolverán todos los resultados que coincidan con la expresión regular completa, pero no se incluirán los grupos de captura.

• Si no se usa la bandera g, se devolverán sólo 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).

La implementación de String.prototype.match en sí es muy simple. Se llama al método Symbol.match del argumento con la cadena como primer parámetro. La implementación real proviene de RegExp.prototype[@@match]().

• Si se necesita saber si una cadena coincide con una expresión 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 más información sobre la semántica de match() cuando se pasa una expresión regular, consulte RegExp.prototype[@@match]().

En el siguiente ejemplo, se usa match para hallar 'Capítulo' seguido de uno o más caracteres numéricos seguidos de un punto decimal y caracteres numéricos cero o más veces.

La expresión regular incluye la bandera i por lo que las diferencias entre mayúsculas y minúsculas serán ignoradas.

const str = "Para más información, consulte el Capítulo 3.4.5.1";
const re = /consulte el (capítulo \d+(\.\d)*)/i;
const found = str.match(re);

console.log(found);
// [
//   'consulte el Capítulo 3.4.5.1',
//   'Capítulo 3.4.5.1',
//   '.1',
//   index: 22,
//   input: 'Para más información, consulte el Capítulo 3.4.5.1',
//   groups: undefined
// ]

En el resultado anterior:

• 'consulte el Capítulo 3.4.5.1' es la ocurrencia completa.
• 'Capítulo 3.4.5.1' fue capturado por (capítulo \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ó.

El siguiente ejemplo demuestra el uso de la bandera global e ignorar mayúsculas 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 = "ABCDEFGHIJKLMNÑOPQRSTUVWXYZabcdefghijklmnñopqrstuvwxyz";
var regexp = /[A-E]/gi;
var matches = str.match(regexp);

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

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

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

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

Si un objeto tiene un método 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!']

Véase RegExp.prototype[@@match]().

Cuando el parámetro regexp es una cadena o un número, se convierte implícitamente en RegExp mediante el uso de new RegExp(regexp).

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

str1.match("número"); // 'número' es una cadena - devuelve ['número']
str1.match(NaN); // NaN es de tipo número - devuelve ['NaN']
str1.match(Infinity); // Infinity es de tipo número - devuelve ['Infinity']
str1.match(+Infinity); // devuelve ['Infinity']
str1.match(-Infinity); // devuelve ['-Infinity']
str2.match(65); // devuelve ['65']
str2.match(+65); // un número 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 expresión regular coincide con todos los caracteres. Para que solo coincida con el carácter de punto, se debe escapar de la entrada.

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

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