String.prototype.match()
Baseline Widely available
This feature is well established and works across many devices and browser versions. It’s been available across browsers since July 2015.
El método match()
devuelve todas las ocurrencias de una expresión regular dentro de una cadena.
Pruébalo
Sintaxis
match(regexp)
Parámetros
regexp
-
Un objeto de expresión regular o cualquier objeto que tenga un método
Symbol.match
.Si
regexp
no es un objetoRegExp
y no tiene un métodoSymbol.match
, se convierte implícitamente enRegExp
usandonew RegExp(regexp)
.Si no se proporciona ningún parámetro y se utiliza el método
match()
directamente, se obtendrá unArray
con una cadena vacía:['']
, ya que esto es equivalente amatch(/(?:)/)
.
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 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 queRegExp.prototype.exec()
(unArray
con algunas propiedades adicionales).
Descripción
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
, useRegExp.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 usarRegExp.prototype.exec()
oString.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]()
.
Ejemplos
Uso de 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ó.
Uso de las banderas global e ignoreCase
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']
Nota:
Véase también String.prototype.matchAll()
y Búsqueda avanzada con banderas.
Uso de grupos de captura con nombre
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' }
Uso de match() sin parámetros
const str = "Nada saldrá de la nada.";
str.match(); // ['']
Uso de match() sin RegExp implementando @@match
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]()
.
Uso de parámetros distintos de RegEx
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
Especificaciones
Specification |
---|
ECMAScript Language Specification # sec-string.prototype.match |
Compatibilidad con navegadores
BCD tables only load in the browser