RegExp.prototype[Symbol.match]()

Метод [Symbol.match]() экземпляров RegExp определяет, как должен вести себя String.prototype.match(). Кроме того, его присутствие (или отсутствие) может влиять на то, считается ли объект регулярным выражением.

Попробуйте

class RegExp1 extends RegExp {
  [Symbol.match](str) {
    const result = RegExp.prototype[Symbol.match].call(this, str);
    if (result) {
      return "VALID";
    }
    return "INVALID";
  }
}

console.log("2012-07-02".match(new RegExp1("(\\d+)-(\\d+)-(\\d+)")));
// Expected output: "VALID"

Синтаксис

regexp[Symbol.match](str)

Параметры

str

String, который является целью сопоставления.

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

Array, содержимое которого зависит от наличия или отсутствия глобального флага (g), или null, если совпадения не найдены.

• Если используется флаг g, будут возвращены все результаты, соответствующие полному регулярному выражению, но захватывающие группы не включаются.
• Если флаг g не используется, возвращается только первое полное совпадение и связанные с ним захватывающие группы. В этом случае match() вернет тот же результат, что и RegExp.prototype.exec() (массив с некоторыми дополнительными свойствами).

Описание

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

"abc".match(/a/);

/a/[Symbol.match]("abc");

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

console.log("😄".match(/(?:)/g)); // [ '', '', '' ]
console.log("😄".match(/(?:)/gu)); // [ '', '' ]

Если регулярное выражение не является глобальным, exec() будет вызван только один раз, и его результат становится возвращаемым значением [Symbol.match]().

Метод exec() автоматически сбрасывает lastIndex в 0, когда последнее сопоставление не удается, поэтому для глобальных регулярных выражений, у которых lastIndex начинается с 0, [Symbol.match]() обычно не имеет побочных эффектов. Однако, когда регулярное выражение является липким (sticky), но не глобальным, exec() вызывается только один раз и, следовательно, не сбрасывает lastIndex, если сопоставление было успешным. В этом случае каждый вызов match() может возвращать разный результат.

const re = /[abc]/y;
for (let i = 0; i < 5; i++) {
  console.log("abc".match(re), re.lastIndex);
}
// [ 'a' ] 1
// [ 'b' ] 2
// [ 'c' ] 3
// null 0
// [ 'a' ] 1

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

console.log("ab-c".match(/[abc]/gy)); // [ 'a', 'b' ]

Кроме того, свойство [Symbol.match] используется для проверки того, является ли объект регулярным выражением.

Примеры

Прямой вызов

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

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

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

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

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

const re = new MyRegExp("(\\d+)-(\\d+)-(\\d+)");
const str = "2016-01-02";
const result = str.match(re); // String.prototype.match calls re[Symbol.match]().
console.log(result.group(1)); // 2016
console.log(result.group(2)); // 01
console.log(result.group(3)); // 02

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

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

Смотрите также

• Полифилл RegExp.prototype[Symbol.match] в core-js
• String.prototype.match()
• RegExp.prototype[Symbol.matchAll]()
• RegExp.prototype[Symbol.replace]()
• RegExp.prototype[Symbol.search]()
• RegExp.prototype[Symbol.split]()
• RegExp.prototype.exec()
• RegExp.prototype.test()
• Symbol.match