`String.prototype.match()‎`

الدالة String.prototype.match()‎ تُعيد ما يُطابِقه تعبيرٌ نمطيٌ (regular expression) في سلسلة نصية.

البنية العامة

str.match(regexp)

`regexp`

كائن التعابير النمطية، وإذا مُرِّرَ كائن obj ليس من النوع RegExp، فسيحوَّل إليه ضمنيًا باستخدام الدالة البانية new RegExp(obj)‎، وإذا لم تُمرِّر أيّ وسيط واستخدمتَ الدالة match مباشرةً، فستحصل على مصفوفة Array فيها سلسلة نصية فارغة (أي [""]).

القيمة المعادة

إذا كانت هنالك مُطابَقة بين التعبير النمطي والسلسلة النصية، فستُعاد مصفوفة Array تحتوي على كامل السلسلة النصية المُطابَقة كأوّل عنصر فيها، ويليها أيّة نتائج تمت مُطابَقتها في التعابير النمطية الفرعية الموجودة بين قوسين. وإذا لم تُطابَق أيّة نتائج فستُعاد القيمة null.

الوصف

إذا لم يحتوِ التعبير النمطي على الراية g، فستُعيد الدالة str.match()‎ نفس النتيجة التي ستُعيدها الدالة RegExp.exec()‎. المصفوفة Array المُعادة ستحتوي على خاصية input إضافية، التي ستحتوي على السلسلة النصية الأصلية التي جرت معالجتها، أضف إلى ذلك أنَّ المصفوفة فيها الخاصية index، التي تُمثِّل فهرس الجزء المُطابَق من السلسلة النصية.

إذا تضمن التعبير النمطي الراية g، فستُعيد هذه الدالة مصفوفةً فيها جميع السلاسل النصية الفرعية المُطابَقة بدلًا من الكائنات المُطابَقة، ولن تُعاد التعابير النمطية الفرعية (الموجودة بين أقواس)، وإذا لم تكن هنالك أيّة مطابَقة فستُعيد هذه الدالة القيمة null.

يمكنك أيضًا الاطلاع على الدوال التابعة للكائن RegExp:

إذا أردتَ أن تعرف إن كانت السلسلة النصية تُطابِق تعبيرًا نمطيًا، فاستخدم الدالة RegExp.test()‎.
إذا أردتَ الحصول على أوّل مطابقة فقط، فاستخدم الدالة RegExp.exec()‎.
إذا أردتَ الحصول على المجموعات الفرعية وكانت الراية g مضبوطةً (وهي راية global) فاستخدم الدالة RegExp.exec()‎.

أمثلة

استخدام `match()‎`

تُستخدَم الدالة match في المثال الآتي للعثور على الكلمة Chapter، يتبعها رقم واحد أو أكثر ويليه فاصلة عشرية، ثم عدد يُكرَّر لصفر مرة أو أكثر. لاحظ أنَّ هذا التعبير النمطي يتضمن الراية i لكي يتم تجاهل الاختلافات بين حالات الحروف:

var str = 'For more information, see Chapter 3.4.5.1';
var re = /see (chapter \d+(\.\d)*)/i;
var 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' ]

شرح الناتج السابق:

'see Chapter 3.4.5.1' هي السلسلة النصية المُطابَقة كاملةً
'Chapter 3.4.5.1' تمت مطابقتها عبر التعبير النمطي الفرعي '‎(chapter \d+(\.\d)*)‎'
'‎.1' هي آخر قيمة وتمت مطابقتها عبر التعبير النمطي الفرعي '‎(\.\d)‎'
الخاصية index قيمتها 22 وهي فهرس السلسلة النصية المُطابَقة
الخاصية input هي السلسلة النصية الأصلية التي جرت معالجتها

استخدام المطابقة في كامل السلسلة النصية وتجاهل حالة الأحرف

المثال الآتي يوضِّح كيفية استخدام راية البحث في كامل السلسلة النصية (g أي global) وراية تجاهل حالة الأحرف (i):

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 = "Nothing will come of nothing.";

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

تمرير كائن ليس من النوع `RegExp`

عندما يكون المعامل سلسلةً نصيةً أو عددًا، فسيحوّل ضمنيًا إلى كائن RegExp باستخدام الدالة البانية new RegExp(obj)‎:

var str1 = "NaN means not a number. Infinity contains -Infinity and +Infinity in JavaScript.",
    str2 = "My grandfather is 65 years old and My grandmother is 63 years old.",
    str3 = "The contract was declared null and void.";
str1.match("number");   // ["number"]
str1.match(NaN);        // ["NaN"]
str1.match(Infinity);   // ["Infinity"]
str1.match(+Infinity);  // ["Infinity"]
str1.match(-Infinity);  // ["-Infinity"]
str2.match(65);         // ["65"]
str2.match(+65);        // ["65"]
str3.match(null);       // ["null"]

دعم المتصفحات

الميزة	Chrome	Firefox	Internet Explorer	Opera	Safari
الدعم الأساسي	نعم	نعم	نعم	نعم	نعم

مصادر ومواصفات

مسودة المعيار ECMAScript Latest Draft.
معيار ECMAScript 2015 (6th Edition)‎.
معيار ECMAScript 5.1.
معيار ECMAScript 3rd Edition .