RegExp.prototype[Symbol.matchAll]()

Метод [Symbol.matchAll]() экземпляров RegExp определяет, как должна вести себя String.prototype.matchAll.

Попробуйте

class MyRegExp extends RegExp {
  [Symbol.matchAll](str) {
    const result = RegExp.prototype[Symbol.matchAll].call(this, str);
    if (!result) {
      return null;
    }
    return Array.from(result);
  }
}

const re = new MyRegExp("-\\d+", "g");
console.log("2016-01-02|2019-03-07".matchAll(re));
// Expected output: Array [Array ["-01"], Array ["-02"], Array ["-03"], Array ["-07"]]

Синтаксис

regexp[Symbol.matchAll](str)

Параметры

str

String, являющийся целью совпадения.

Возвращаемое значение

Итератор iterable iterator object (не перезапускаемый) совпадений. Каждое совпадение представляет собой массив той же формы, что и возвращаемое значение RegExp.prototype.exec().

Описание

Этот метод существует для настройки поведения matchAll() в подклассах RegExp. Он вызывается внутренне в String.prototype.matchAll(). Например, следующие два примера возвращают один и тот же результат.

"abc".matchAll(/a/g);

/a/g[Symbol.matchAll]("abc");

Как и [Symbol.split](), [Symbol.matchAll]() сначала использует [Symbol.species] для создания нового регулярного выражения, избегая при этом изменения исходного регулярного выражения. Конструктор получает this и исходные флаги. lastIndex принимает значение исходного регулярного выражения.

const regexp = /[a-c]/g;
regexp.lastIndex = 1;
const str = "abc";
Array.from(str.matchAll(regexp), (m) => `${regexp.lastIndex} ${m[0]}`);
// [ "1 b", "1 c" ]

Если регулярное выражение является глобальным (с флагом g), каждый раз, когда вызывается метод next() возвращаемого итератора, вызывается exec() регулярного выражения, и результат выдается. Если текущее совпадение является пустой строкой, lastIndex все равно будет увеличен. Если регулярное выражение имеет флаг u, он увеличивается на одну кодовую позицию Unicode; в противном случае он увеличивается на одну кодовую позицию UTF-16.

console.log(Array.from("😄".matchAll(/(?:)/g)));
// [ [ "" ], [ "" ], [ "" ] ]

console.log(Array.from("😄".matchAll(/(?:)/gu)));
// [ [ "" ], [ "" ] ]

Если регулярное выражение не является глобальным, возвращаемый итератор один раз выдает результат exec(), а затем завершается. (Проверка того, является ли входное значение глобальным регулярным выражением, выполняется в String.prototype.matchAll(). [Symbol.matchAll]() не проверяет флаги this.)

Когда регулярное выражение является "sticky" и глобальным, оно по-прежнему будет выполнять "sticky" совпадения — то есть, оно не будет соответствовать никаким вхождениям за пределами lastIndex.

console.log(Array.from("ab-c".matchAll(/[abc]/gy)));
// [ [ "a" ], [ "b" ] ]

Примеры

Прямой вызов

Этот метод можно использовать почти так же, как String.prototype.matchAll(), за исключением другого значения this и другого порядка аргументов.

const re = /\d+/g;
const str = "2016-01-02";
const result = re[Symbol.matchAll](str);

console.log(Array.from(result, (x) => x[0]));
// [ "2016", "01", "02" ]

Использование [Symbol.matchAll]() в подклассах

Подклассы RegExp могут переопределять метод [Symbol.matchAll]() для изменения поведения по умолчанию.

Например, чтобы вернуть Array вместо итератора:

class MyRegExp extends RegExp {
  [Symbol.matchAll](str) {
    const result = RegExp.prototype[Symbol.matchAll].call(this, str);
    return result ? Array.from(result) : null;
  }
}

const re = new MyRegExp("(\\d+)-(\\d+)-(\\d+)", "g");
const str = "2016-01-02|2019-03-07";
const result = str.matchAll(re);

console.log(result[0]);
// [ "2016-01-02", "2016", "01", "02" ]

console.log(result[1]);
// [ "2019-03-07", "2019", "03", "07" ]

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

Совместимость с браузерами

См. также

• Polyfill of RegExp.prototype[Symbol.matchAll] in core-js
• es-shims polyfill of RegExp.prototype[Symbol.matchAll]
• String.prototype.matchAll()
• RegExp.prototype[Symbol.match]()
• RegExp.prototype[Symbol.replace]()
• RegExp.prototype[Symbol.search]()
• RegExp.prototype[Symbol.split]()
• Symbol.matchAll