عرض مصدر JavaScript/String/substring

<noinclude>{{DISPLAYTITLE:<code>String.prototype.substring()‎</code>}}</noinclude>
الدالة <code>String.prototype.substring()‎</code> تُعيد سلسلةً نصيةً فرعيةً من سلسلةٍ نصيةٍ أخرى والتي تقع بين فهرسين.
==البنية العامة==
<syntaxhighlight lang="javascript">
str.substring(indexStart[, indexEnd])

</syntaxhighlight>
=== <code>indexStart</code> ===
عدد صحيح بين 0 وطول السلسلة النصية يُحدِّد فهرس بداية السلسلة المستخرجة، وسيُضمَّن المحرف الموجود عند هذا الفهرس في السلسلة النصية المُستخرَجة.

=== <code>indexEnd</code> ===
قيمةٌ اختياريةٌ، وهي عددٌ صحيحٌ بين 0 طول السلسلة النصية يُحدِّد فهرس نهاية السلسلة المُستخرَجة. لاحظ أنَّ الحرف الموجود عند هذا الفهرس لن يُضمَّن في السلسلة النصية المُستخرَجة.

=== القيمة المعادة ===
سلسلة نصية جديدة تحتوي على القسم المستخرج من السلسلة المعطية.

== الوصف ==
الدالة <code>substring()‎</code> تستخرج المحارف بدءًا من <code>indexStart</code> حتى <code>indexEnd</code> (دون تضمين المحرف الموجود في الفهرس <code>indexEnd</code>):
* إذا كان <code>indexStart</code> يساوي <code>indexEnd</code>، فستُعيد الدالة <code>substring</code> سلسلةً نصية فارغةً.
* إذا لم تُحدَّد قيمة <code>indexEnd</code>، فستستخرج الدالة <code>substring</code> المحارف من فهرس البداية حتى نهاية السلسلة النصية.
* إذا كان أحد الوسيطين أقل من 0 أو <code>[[JavaScript/NaN|NaN]]</code>، فسيُعامَل على أنَّه 0.
* إذا كان أحد الوسيطين أكبر من <code>str.length</code> فسيُعامَل على أنَّه مساوٍ للقيمة <code>str.length</code>.
إذا كانت قيمة <code>indexStart</code> أكبر من <code>indexEnd</code>، فستعمل الدالة <code>substring</code> كما لو أننا بدّلنا بين الوسيطين، أي مثلًا: <code>str.substring(1, 0) == str.substring(0, 1)‎</code>.

== أمثلة ==

=== استخدام <code>substring()‎</code> ===
يبيّن المثال الآتي بعض حالات استخدام الدالة <code>substring()‎</code>:<syntaxhighlight lang="javascript">
var anyString = 'Hsoub';

// 'Hso'
console.log(anyString.substring(0, 3));
console.log(anyString.substring(3, 0));

// 'b'
console.log(anyString.substring(4, 5));
console.log(anyString.substring(4));
console.log(anyString.substring(5, 4));

// 'Hsou'
console.log(anyString.substring(0, 4));

// 'Hsoub'
console.log(anyString.substring(0, 5));
console.log(anyString.substring(0, 10));
</syntaxhighlight>

=== استخدام <code>substring()‎</code> مع الخاصية <code>[[JavaScript/String/length|length]]</code> ===
المثال الآتي يستخدم الدالة <code>substring</code> والخاصية <code>[[JavaScript/String/length|length]]</code> لاستخراج آخر عدّة محارف من السلسلة النصية. لاحظ أنَّ هذه الطريقة سهلة التذكر لأنَّك لا تحتاج إلى معرفة فهرس البداية وفهرس النهاية كما في الأمثلة السابقة:<syntaxhighlight lang="javascript">
// عرض آخر محرفين
var anyString = 'Hsoub';
var anyString4 = anyString.substring(anyString.length - 2);
console.log(anyString4); // 'ub'

// عرض آخر 3 محارف
var anyString = 'Hsoub';
var anyString5 = anyString.substring(anyString.length - 3);
console.log(anyString5); // 'oub'

</syntaxhighlight>

=== الفرق بين الدالتين <code>substring()‎</code> و <code>[[JavaScript/String/substr|substr()‎]]</code> ===
هنالك اختلافٌ طفيف بين الدالتين <code>substring()‎</code> و <code>[[JavaScript/String/substr|substr()‎]]</code> لذا احرص على عدم الخلط بينهما.

انتبه إلى أنَّ الدالة <code>substring()‎</code> تقبل فهرس البداية والنهاية كوسائط، أما وسائط الدالة <code>substr()‎</code> فهي فهرس البداية وطول المحارف التي تُشكِّل السلسلة النصية.<syntaxhighlight lang="javascript">
var text = 'Hsoub';
console.log(text.substring(2,5)); // "oub"
console.log(text.substr(2,3)); // "oub"
</syntaxhighlight>

== دعم المتصفحات ==
{| class="wikitable"
!الميزة
!|Chrome
!Firefox
!Internet Explorer
!Opera
!Safari
|-
! الدعم الأساسي
|نعم
|نعم
|نعم
|نعم
|نعم
|}
== مصادر ومواصفات ==
* مسودة المعيار [https://tc39.github.io/ecma262/#sec-string.prototype.substring ECMAScript Latest Draft].
* معيار [http://www.ecma-international.org/ecma-262/6.0/#sec-string.prototype.substring ECMAScript 2015 (6th Edition)]‎.
* معيار [http://www.ecma-international.org/ecma-262/5.1/#sec-15.5.4.15 ECMAScript 5.1].
* معيار [http://www.ecma-international.org/publications/files/ECMA-ST-ARCH/ECMA-262,%201st%20edition,%20June%201997.pdf ECMAScript 1st Edition] . 
[[تصنيف:JavaScript|{{SUBPAGENAME}}]]
[[تصنيف:JavaScript Global Objects|{{SUBPAGENAME}}]]
[[تصنيف:JavaScript String|{{SUBPAGENAME}}]]