String.prototype.matchAll()

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

Синтаксис

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.

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

Update compatibility data on GitHub
DesktopMobileServer
ChromeEdgeFirefoxInternet ExplorerOperaSafariAndroid webviewChrome for AndroidFirefox for AndroidOpera for AndroidSafari on iOSSamsung InternetNode.js
matchAllChrome Full support 73Edge Full support 79Firefox Full support 67IE No support NoOpera Full support 60Safari Full support 13WebView Android Full support 73Chrome Android Full support 73Firefox Android Full support 67Opera Android Full support 52Safari iOS Full support 13Samsung Internet Android No support Nonodejs Full support 12.0.0

Legend

Full support  
Full support
No support  
No support

Див. також