String.prototype.match()

Метод match() объектов String извлекает результат сопоставления этой строки с регулярным выражением.

Попробуйте

const paragraph = "The quick brown fox jumps over the lazy dog. It barked.";
const regex = /[A-Z]/g;
const found = paragraph.match(regex);

console.log(found);
// Expected output: Array ["T", "I"]

Синтаксис

match(regexp)

Параметры

regexp

Объект регулярного выражения или любой объект, имеющий метод Symbol.match.

Если regexp не является объектом RegExp и не имеет метода Symbol.match, он неявно преобразуется в RegExp с помощью new RegExp(regexp).

Если вы не передадите никакого параметра и будете использовать метод match() напрямую, вы получите Array с пустой строкой: [""], так как это эквивалентно match(/(?:)/).

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

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

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

Описание

Реализация String.prototype.match сводится к вызову метода Symbol.match аргумента, передавая строку в качестве первого параметра. Фактическая реализация находится в RegExp.prototype[Symbol.match]().

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

Для получения дополнительной информации о семантике match() при передаче регулярного выражения см. RegExp.prototype[Symbol.match]().

Примеры

Использование match()

В следующем примере match() используется для поиска "Chapter", за которым следует одна или несколько цифр, точка и затем ноль или более цифр.

Регулярное выражение включает флаг i, чтобы игнорировать различия в верхнем и нижнем регистре.

const str = "For more information, see Chapter 3.4.5.1";
const re = /see (chapter \d+(\.\d)*)/i;
const found = str.match(re);

console.log(found);
// [
//   'see Chapter 3.4.5.1',
//   'Chapter 3.4.5.1',
//   '.1',
//   index: 22,
//   input: 'For more information, see Chapter 3.4.5.1',
//   groups: undefined
// ]

В приведенном выше результате сопоставления 'see Chapter 3.4.5.1' — это полное совпадение. 'Chapter 3.4.5.1' было захвачено (chapter \d+(\.\d)*). '.1' было последним значением, захваченным (\.\d). Свойство index (22) — это нулевой индекс полного совпадения. Свойство input — это исходная строка, которая была проанализирована.

Использование флагов global и ignoreCase с match()

Следующий пример демонстрирует использование флага global и ignore-case с match(). Возвращаются все буквы A-E и a-e, каждая в отдельном элементе массива.

const str = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz";
const regexp = /[a-e]/gi;
const matches = str.match(regexp);

console.log(matches);
// ['A', 'B', 'C', 'D', 'E', 'a', 'b', 'c', 'd', 'e']

Использование именованных захватывающих групп

В браузерах, поддерживающих именованные захватывающие группы, следующий код захватывает "fox" или "cat" в группу с именем animal:

const paragraph = "The quick brown fox jumps over the lazy dog. It barked.";

const capturingRegex = /(?<animal>fox|cat) jumps over/;
const found = paragraph.match(capturingRegex);
console.log(found.groups); // {animal: "fox"}

Использование match() без параметра

const str = "Nothing will come of nothing.";

str.match(); // returns [""]

Использование match() с объектом, реализующим [Symbol.match](), но не являющимся RegExp

Если объект имеет метод Symbol.match, он может быть использован как пользовательский сопоставитель. Возвращаемое значение Symbol.match становится возвращаемым значением match().

const str = "Hmm, this is interesting.";

str.match({
  [Symbol.match](str) {
    return ["Yes, it's interesting."];
  },
}); // returns ["Yes, it's interesting."]

Не-RegExp в качестве параметра

Когда параметр regexp является строкой или числом, он неявно преобразуется в RegExp с помощью new RegExp(regexp).

const str1 =
  "All numbers except NaN satisfy <= Infinity and >= -Infinity in JavaScript.";
const str2 =
  "My grandfather is 65 years old and My grandmother is 63 years old.";
const str3 = "The contract was declared null and void.";
str1.match("number"); // "number" is a string. returns ["number"]
str1.match(NaN); // the type of NaN is the number. returns ["NaN"]
str1.match(Infinity); // the type of Infinity is the number. returns ["Infinity"]
str1.match(-Infinity); // returns ["-Infinity"]
str2.match(65); // returns ["65"]
str3.match(null); // returns ["null"]

Это может привести к неожиданным результатам, если специальные символы не экранированы должным образом.

console.log("123".match("1.3")); // [ "123" ]

Это совпадение, потому что . в регулярном выражении соответствует любому символу. Чтобы сопоставить только конкретный символ точки, вам нужно экранировать ввод.

console.log("123".match("1\\.3")); // null

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

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

См. также

• Polyfill для String.prototype.match в core-js с исправлениями и реализацией современного поведения, такого как поддержка Symbol.match
• Руководство по регулярным выражениям
• String.prototype.matchAll()
• RegExp
• RegExp.prototype.exec()
• RegExp.prototype.test()