String.prototype.match()

Метод match() шукає та повертає (якщо є) збіги рядка із зазначеним регулярним виразом.

Синтаксис

str.match(regexp)

Параметри

regexp

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

Якщо передати значення іншого типу, воно буде неявно перетворене на RegExp за допомогою оператора new RegExp(regexp).

Якщо жодного параметра не вказано, метод поверне масив з одним елементом — порожнім рядком: [""].

Вертає

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

• Якщо використовується прапор g, метод поверне усі результати, що збігаються з повним регулярним виразом, але не поверне захоплені групи.
• Якщо прапор g не використовується, метод поверне лише перший повний збіг та захоплені групи, які він містить. У цьому випадку повернений елемент матиме додаткові властивості, описані нижче.

Додаткові властивості

Як пояснювалось вище, деякі результати містять наступні додаткові властивості:

groups

Масив іменованих захоплених груп або undefined, якщо іменовані групи не були визначені. Дивіться Групи та діапазони, щоб дізнатись більше.

index

Індекс пошуку, за яким був знайдений результат.

input 

Копія рядка, в якому здійснювався пошук.

Опис

Якщо регулярний вираз не позначено прапорцем g, виклик str.match() повертає такий самий результат, що й RegExp.exec().

Інші методи

• Якщо вам треба з'ясувати, чи відповідає рядок регулярному виразові RegExp, скористайтеся методом RegExp.test().
• Якщо вас цікавить лише перший збіг, можете натомість використати RegExp.exec().
• Якщо ви хочете отримати захоплені групи, а прапорець g встановлено, вам потрібен метод RegExp.exec() або String.prototype.matchAll().

Приклади

Використання match()

У прикладі нижче метод match() задіяно, щоб знайти слово «розділ», за ним одну чи кілька цифр, далі десяткова крапка та 0 чи більше числових символів.

Регулярний вираз позначено прапорцем i, що означає відсутність розрізнювання великих та малих літер.

var str = 'Докладніше див. розділ 3.4.5.1';
var re = /див\. (розділ \d+(\.\d)*)/i;
var found = str.match(re);

console.log(found);

// Виводить:
// [
//   0: "див. розділ 3.4.5.1"
//   1: "розділ 3.4.5.1"
//   2: ".1"
//   index: 11
//   input: "Докладніше див. розділ 3.4.5.1"
// ]

// Рядок "див. розділ 3.4.5.1" є повним збігом.
// Рядок "розділ 3.4.5.1" — це підрядок, захоплений підвиразом '(розділ \d+(\.\d)*)'
// Рядок ".1" — це останній підрядок, захоплений підвиразом '(\.\d)'
// Властивість 'index' (11) — це зсув підрядка, що відповідає регулярному виразові
// Властивість 'input' — це повна копія досліджуваного рядка str

Вживання прапорців i та g із методом match()

Приклад нижче засвідчує дію прапорців i (ignore case — регістронезалежний режим) та g (global — пошук усіх збігів, а не тільки першого) при використанні метода match(). Будуть повернені усі літери від A до E та від a до e, кожна як окремий елемент масиву.

var str = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz';
var regexp = /[A-E]/gi;
var matches_array = str.match(regexp);

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

Використання іменованих груп

У переглядачах, які підтримують іменовані захоплені групи, наступний код захопить "їжак" чи "кіт" у групу на ім'я "тварина":

let paragraph = 'Єхидна, ґава, їжак ще й шиплячі плазуни бігцем форсують Янцзи.';

let capturingRegex = /(?<тварина>їжак|кіт) ще й/;
found = paragraph.match(capturingRegex);
console.log(found.groups); // {тварина: "їжак"}

Використання match() без параметрів

var str = "Я — Дух одвічної стихії";

// вертає ["", index: 0, input: "Я — Дух одвічної стихії"]
str.match();

Параметр відмінного від RegExp типу

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

Якщо це додатнє число, його знаком + буде знехтувано, проте для від'ємного числа знак - стане частиною регулярного виразу:

var str1 = "NaN означає «не число». Нескінченність у JavaScript має дві форми: -Infinity та +Infinity.",
    str2 = "Моїй бабці 65 років, а дідусеві — 63.",
    str3 = "Незмінна величина null позначає відсутність очікуваного значення.";

str1.match("число");    // "число" є рядком; вертає ["число"]
str1.match(NaN);        // величина NaN є числом; вертає ["NaN"]
str1.match(Infinity);   // величина Infinity також є числом; вертає ["Infinity"]
str1.match(+Infinity);  // вертає ["Infinity"]
str1.match(-Infinity);  // вертає ["-Infinity"]
str2.match(65);         // вертає ["65"]
str2.match(+65);        // додатнє число; вертає ["65"]
str3.match(null);       // вертає ["null"]

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

Підтримка веб-переглядачами

Базова підтримка методу match()

Підтримка іменованих груп

Зауваги щодо Firefox

• Аргумент flags був нестандартним другим аргументом, доступним лише у Firefox: str.match(regexp, flags). Він був прибраний, починаючи з Firefox 49.
• У Firefox 27 цей метод було узгоджено зі специфікацією ECMAScript. Коли match() викликано із глобальним регулярним виразом, властивість RegExp.lastIndex (якщо зазначено) скидається до 0 (bug 501739).

Див. також

• String.prototype.matchAll()
• RegExp
• RegExp.prototype.exec()
• RegExp.prototype.test()