String.prototype.matchAll()

Метод matchAll() повертає ітератор з усіма збігами рядка з регулярним виразом, а також захоплені групи (en-US).

Синтаксис

str.matchAll(regexp)

Параметри

regexp

Об'єкт регулярного виразу.

Якщо передано об'єкт obj, який не є регулярним виразом, він неявно перетворюється на RegExp за допомогою new RegExp(obj).

Об'єкт RegExp повинен мати прапор /g, інакше буде викинуто помилку TypeError.

Значення, що повертається

Ітератор (ітерабельний об'єкт, який не можна повторно запустити).

Приклади

Regexp.exec() та matchAll()

До появи у JavaScript методу matchAll можна було використовувати виклики regexp.exec (а також регулярні вирази з прапором /g) у циклі, щоб отримати усі збіги:

const regexp = RegExp('фу[а-я]*','g');
const str = 'настільний футбол, фусбол';
let match;

while ((match = regexp.exec(str)) !== null) {
  console.log(`Знайдено ${match[0]} початок=${match.index} кінець=${regexp.lastIndex}.`);
  // виведе: "Знайдено футбол початок=11 кінець=17."
  // виведе: "Знайдено фусбол початок=19 кінець=25."
}

З методом matchAll можна уникнути використання циклу while та методу exec з g.

Замість цього, використовуючи matchAll, ви отримуєте ітератор, який можна використовувати з більш зручними конструкціями for...of, розкладанням масиву чи Array.from():

const regexp = RegExp('фу[а-я]*','g');
const str = 'настільний футбол, фусбол';
const matches = str.matchAll(regexp);

for (const match of matches) {
  console.log(`Знайдено ${match[0]} початок=${match.index} кінець=${match.index + match[0].length}.`);
}
// виведе: "Знайдено футбол початок=11 кінцець=17."
// виведе: "Знайдень фусбол початок=19 кінець=25."

// Ітератор matches є вичерпаним після перебору for..of
// Викличте matchAll ще раз, щоб створити новий ітератор
Array.from(str.matchAll(regexp), m => m[0]);
// Array [ "футбол", "фусбол" ]

Метод matchAll викине виняток, якщо прапор g відсутній.

const regexp = RegExp('[а-в]','');
const str = 'абв';
str.matchAll(regexp);
// TypeError

matchAll робить внутрішній клон regexp, тому, на відміну від regexp.exec(), lastIndex не змінюється під час пошуку.

const regexp = RegExp('[а-в]','g');
regexp.lastIndex = 1;
const str = 'абв';
Array.from(str.matchAll(regexp), m => `${regexp.lastIndex} ${m[0]}`);
// Array [ "1 б", "1 в" ]

Кращий доступ до захоплених груп (ніж у String.prototype.match())

Ще одна приваблива причина використовувати matchAll - покращений доступ до захоплених груп.

Захоплені групи ігноруються при використанні match() з глобальним прапором /g:

let regexp = /т(е)(ст(\d?))/g;
let str = 'тест1тест2';

str.match(regexp);
// Array ['тест1', 'тест2']

Використовуючи matchAll, ви можете легко звертатись до захоплених груп:

let array = [...str.matchAll(regexp)];

array[0];
// ['тест1', 'е', 'ст1', '1', index: 0, input: 'тест1тест2', length: 4]
array[1];
// ['тест2', 'е', 'ст2', '2', index: 5, input: 'тест1тест2', length: 4]

Специфікації

Специфікація
ECMAScript (ECMA-262)
The definition of 'String.prototype.matchAll' in that specification.

Сумісність з веб-переглядачами

BCD tables only load in the browser

Див. також