String.prototype.matchAll()
El método matchAll()
retorna un iterador de todos los resultados de ocurrencia en una cadena de texto contra una expresión regular, incluyendo grupos de captura.
The source for this interactive example is stored in a GitHub repository. If you'd like to contribute to the interactive examples project, please clone https://github.com/mdn/interactive-examples and send us a pull request.
Sintaxis
cadena.matchAll(expresionRegular)
Parámetros
- expresionRegular
- Un objeto expresión regular. Si se pasa un objeto no-RegExp
obj
, este es implícitamente convertido aRegExp
víanew RegExp(obj)
.
Valor devuelto
Un iterador (el cual no es reiniciable).
Ejemplo
Regexp.exec() y matchAll()
Antes de la adición de matchAll
a JavaScript, fue posible hacer llamados a regexp.exec (y usar expresiones regulares con la bandera /g
) en un ciclo para obtener las ocurrencias:
const regexp = RegExp('foo[a-z]*','g');
const cadena = 'mesa football, foosball';
let ocurrencia;
while ((ocurrencia = regexp.exec(cadena)) !== null) {
console.log(`Encontrado ${ocurrencia[0]} inicio=${ocurrencia.index} final=${regexp.lastIndex}.`);
// salida esperada: "Encontrado football inicio=5 final=13."
// salida esperada: "Encontrado foosball inicio=15 final=23."
}
Con matchAll
disponible, puedes evitar el ciclo while
y exec
con /g
. Por el contrario, usando matchAll
, obtienes un iterador con el cual puedes usar con constructores más convenientes for...of
, array spread, o Array.from()
:
const regexp = RegExp('foo[a-z]*','g');
const cadena = 'mesa football, foosball';
const ocurrencias = cadena.matchAll(regexp);
for (const ocurrencia of ocurrencias) {
console.log(`Encontrado ${ocurrencia[0]} inicio=${ocurrencia.index} final=${ocurrencia.index + ocurrencia[0].length}.`);
}
// salida esperada: "Encontrado football start=5 end=13."
// salida esperada: "Encontrado foosball start=15 end=23."
// el iterador ocurrencias es agotado después de la iteración for..of
// Llama matchAll de nuevo para crear un nuevo iterador
Array.from(cadena.matchAll(regexp), m => m[0]);
// Array [ "football", "foosball" ]
matchAll
solo devuelve la primer ocurrencia si la bandera /g
está ausente.
const regexp = RegExp('[a-c]','');
const cadena = 'abc';
Array.from(cadena.matchAll(regexp), m => m[0]);
// Array [ "a" ]
matchAll
internamente hace un clon de la expresión regular, entonces a diferencia de regexp.exec, lastIndex
no cambia a medida que la cadena es escaneada.
const regexp = RegExp('[a-c]','g');
regexp.lastIndex = 1;
const cadena = 'abc';
Array.from(cadena.matchAll(regexp), m => `${regexp.lastIndex} ${m[0]}`);
// Array [ "1 b", "1 c" ]
Mejor acceso para capturar grupos
Otra buena razón para matchAll
es el mejorado acceso a los grupos de captura. Los grupos de captura son ignorados cuando se usa match()
con la bandera global /g
:
var regexp = /t(e)(st(\d?))/g;
var cadena = 'test1test2';
cadena.match(regexp);
// Array ['test1', 'test2']
Con matchAll
puedes acceder a ellos:
let array = [...str.matchAll(regexp)];
array[0];
// ['test1', 'e', 'st1', '1', index: 0, input: 'test1test2', length: 4]
array[1];
// ['test2', 'e', 'st2', '2', index: 5, input: 'test1test2', length: 4]
Especificaciones
Especificación | Estado | Comentario |
---|---|---|
ECMAScript (ECMA-262) La definición de 'String.prototype.matchAll' en esta especificación. |
Living Standard |
Compatibilidad de navegadores
BCD tables only load in the browser
The compatibility table on this page is generated from structured data. If you'd like to contribute to the data, please check out https://github.com/mdn/browser-compat-data and send us a pull request.