String.prototype.match()

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

Синтаксис

str.match(regexp)

Параметри

regexp

Об'єкт регулярного виразу. Якщо передати значення value іншого типу, його буде зведено до RegExp за допомогою оператора new RegExp(value). Якщо жодного параметра не вказано, метод поверне масив з одним елементом — порожнім рядком: [''].

Вертає

Вертає масив, якщо знайдено збіги. Першим елементом масиву завжди буде ввесь підрядок, що відповідає регулярному виразові, а за ним — низка захоплених підрядків, які відповідають підвиразам у круглих дужках (якщо регулярний вираз містить такі).

Якщо збігів не знайдено, метод вертає значення null.

Опис

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

Повернений масив має дві додаткові властивості:

• input: містить цілком рядок, який порівнювали із регулярним виразом;
• index: позначає зсув (лік від нуля) знайденого підрядка всередині рядка input;

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

Див. також інші методи RegExp

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

Приклади

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

В прикладі нижче метод match() задіяно для пошуку слова «розділ» та однієї чи кількох цифр за ним, розділених крапкою. Регулярний вираз позначено прапорцем 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 (великі й малі):

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']

Використання 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"]

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

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

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

• Лише рушій Gecko підтримував параметр flags — другий аргумент метода: str.match(regexp, flags);
• З версії Gecko 27 (Firefox 27 / Thunderbird 27 / SeaMonkey 2.24) цей метод було узгоджено зі специфікацією ECMAScript. Коли match() викликано із регулярним виразом, що його позначено прапорцем g, властивість RegExp.lastIndex (якщо зазначено) скидається до 0 (bug 501739);
• З версії Gecko 39 (Firefox 39 / Thunderbird 39 / SeaMonkey 2.36) нестандартний параметр flags визнано застарілим і його використання спричиняє відповідне попередження в консолі (bug 1142351).
• З версії Gecko 47 (Firefox 47 / Thunderbird 47 / SeaMonkey 2.44) нестандартний параметр flags у проміжних складаннях (не випусках) більше не підтримується й невдовзі його остаточно буде вилучено (bug 1245801).
• З версії Gecko 49 (Firefox 49 / Thunderbird 49 / SeaMonkey 2.46) підтримка нестандартного параметра flags припинена (bug 1108382).

Див. також

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