String.prototype.substr()‎

الدالة String.prototype.substr()‎ تُعيد عددًا معيّنًا من المحارف بدءًا من الموضع المُحدَّد.

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

str.substr(start[, length])

start

فهرس مكان بدء الاستخراج (يبدأ العد من الصفر)، وإذا كان سالبًا فسيعامل على أنَّه strLength + start، إذ إنَّ strLength هو طول السلسلة النصية (على سبيل المثال، إذا كان start يساوي -3 فسيعامل على أنه strLength - 3).

length

عدد المحارف التي نريد استخراجها؛ إذا كانت قيمة هذه الوسيط هي undefined فستُستخرج جميع المحارف بدءًا من الفهرس start.

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

سلسلة نصية جديدة تحتوي على القسم المستخرج من السلسلة النصية الأصل. إذا كانت قيمة الوسيط length عددًا سالبًا أو 0، فستُعاد سلسلةٌ نصيةٌ فارغة.

الوصف

الوسيط start هو فهرس البداية، ويكون فهرس أوّل محرف هو 0، وفهرس آخر محرف هو «طول السلسلة النصية - 1». لاحظ أنَّ الدالة substr()‎ تبدأ استخراج المحارف من الفهرس start وتستمر باستخراج عدد من المحارف يساوي قيمة الوسيط length (ما لم تصل إلى نهاية السلسلة النصية أولًا، مما يجعلها تستخرج عدد محارف أقل من قيمة length).

إذا كانت قيمة الوسيط start موجبةً وكانت أكبر أو تساوي طول السلسلة النصية الأصلية، فستُعيد هذه الدالة سلسلةً نصيةً فارغةً.

إذا كانت قيمة start سالبةً، فستُعدّ على أنها فهرس البداية لكن بدءًا من نهاية السلسلة النصة، أي أنَّ فهرس آخر محرف هو ‎-1. وإذا كانت قيمة start سالبةً وكانت نتيجة abs(start)‎ أكبر من طول السلسلة النصية، فستستخدم الدالة substr()‎ القيمة 0 كفهرس بداية.

إذا كانت قيمة الوسيط length سالبةً أو 0، فستُعيد هذه الدالة سلسلةً نصيةً فارغةً، وإذا لم تُحدَّد قيمةٌ للوسيط length فستستخرج هذه الدالة المحارف من فهرس البداية حتى نهاية السلسلة النصية.

أمثلة

استخدام substr()‎

يبيّن المثال الآتي بعض حالات استخدام الدالة substr()‎:

var str = 'abcdefghij';

console.log('(1, 2): '   + str.substr(1, 2));   // '(1, 2): bc'
console.log('(-3, 2): '  + str.substr(-3, 2));  // '(-3, 2): hi'
console.log('(-3): '     + str.substr(-3));     // '(-3): hij'
console.log('(1): '      + str.substr(1));      // '(1): bcdefghij'
console.log('(-20, 2): ' + str.substr(-20, 2)); // '(-20, 2): ab'
console.log('(20, 2): '  + str.substr(20, 2));  // '(20, 2): '

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

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

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

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