RegExp.prototype.test()‎

الدالة RegExp.prototype.test()‎ تجرى بحثًا عن مطابقة للتعبير النمطي في السلسلة النصية المُحدَّدة، وتُعيد true أو false.

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

regexObj.test(str)

str

السلسلة النصية التي سنبحث عن مُطابَقة للتعبير النمطي فيها.

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

إذا نجحت عملية المطابقة، فستُعيد الدالة test()‎ القيمة true، وإن لم يكن التعبير النمطي موجودًا في السلسلة النصية فستُعيد القيمة false.

الوصف

الدالة test()‎ تُحدِّد إن كان النمط موجودًا في السلسلة النصية أم لا، وستُعيد قيمة منطقيةً (Boolean)، وذلك على النقيض من الدالة String.prototype.search()‎ التي تُعيد فهرس المُطابَقة (أو القيمة ‎-1 إن لم يكن التعبير النمطي موجودًا). للحصول على معلومات إضافية (لكن سيكون التنفيذ أبطأ) فاستخدم الدالة exec()‎ (الشبيهة بالدالة String.prototype.match()‎).

وكما في الدالة exec()‎، يمكن استدعاء الدالة test()‎ عدِّة مرات على كائن التعابير النمطية الذي ضُبِطَت فيه الراية "g" للحصول على المُطابَقة التالية للتعبير النمطي في السلسلة النصية.

أمثلة

استخدام الدالة test()‎

هذا مثالٌ بسيطٌ يختبر وجود "hello" في بداية السلسلة النصية، وستُعيد الدالة قيمةً منطقيةً:

var str = 'hello world!';
var result = /^hello/.test(str);
console.log(result); // true

أما الدالة الآتية فتعرض رسالةً توضِّح إن كان النمط موجودًا في السلسلة النصية أم لا:

function testinput(re, str) {
  var midstring;
  if (re.test(str)) {
    midstring = ' contains ';
  } else {
    midstring = ' does not contain ';
  }
  console.log(str + midstring + re.source);
}

استخدام الدالة test()‎ مع تعبيرٍ نمطيٍ له الراية g

إذا امتلك التعبير النمطي الراية "g" (أي global، التي تبحث عن جميع المطابقات في السلسلة النصية)، فستستكمل الدالة test()‎ بحثها بدءًا من قيمة الخاصية lastIndex التابعة لكائن RegExp. المثال الآتي يوضِّح هذا السلوك:

var regex = /foo/g;

// regex.lastIndex: 0
regex.test('foo'); // true

// regex.lastIndex: 3
regex.test('foo'); // false

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

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

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

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