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

<noinclude>{{DISPLAYTITLE:<code>String.prototype.split()‎</code>}}</noinclude>
الدالة <code>String.prototype.split()‎</code> تقسم كائن <code>[[JavaScript/String|String]]</code> إلى مصفوفة من السلاسل النصية بفصلها إلى سلاسل نصية فرعية، وذلك باستخدام محرف فصل مُعيّن لمعرفة أين سيكون كل قسم.
==البنية العامة==
<syntaxhighlight lang="javascript">
str.split([separator[, limit]])

</syntaxhighlight>
=== <code>separator</code> ===
السلسلة النصية التي تُشير إلى مكان فصل السلسلة النصية، ويمكن أن يكون الفاصل <code>separator</code> سلسلةً نصيةً أو تعبيرًا نمطيًا. وإذا استخدمنا سلسلةً نصيةً عاديةً تحتوي على أكثر من حرف فيجب العثور على السلسلة النصية كلها في مكان الفصل؛ أما لم تُحدَّد قيمة الوسيط <code>separator</code> أو لم يكن موجودًا ضمن السلسلة النصية <code>str</code> فستُعاد مصفوفة تحتوي على عنصرٍ وحيدٍ ألا وهو السلسلة النصية كاملةً. إذا كان <code>separator</code> سلسلةً نصيةً فارغةً فستحوّل السلسلة <code>str</code> إلى مصفوفة من المحارف.

=== <code>limit</code> ===
عدد صحيح يضبط الحد الأقصى لعدد الأجزاء التي ستُقسَّم السلسلة النصية إليها. وعند تحديد قيمة لهذا الوسيط، فستُقسِّم هذه الدالة السلسلة النصية عند كل مُطابَقة لقيمة <code>separator</code> لكنها ستتوقف عند بلوغ عدد عناصر المصفوفة القيمةَ المُحدَّدة بالوسيط <code>limit</code>. لاحظ أنَّ من الممكن أن تكون هنالك عناصر في المصفوفة عددها أقل من قيمة <code>limit</code>.

=== القيمة المعادة ===
مصفوفة من أقسام السلسلة النصية الأصل عند كل مكان تمت مطابقة قيمة <code>separator</code> فيه.

== الوصف ==
عندما يُعثَر على الفاصل <code>separator</code> فسيُحذَف من السلسلة النصية وستُعاد السلاسل النصية الفرعية في مصفوفة؛ وإذا لم يُعثَر على قيمة الوسيط <code>separator</code> أو لم يكن موجودًا، فستحتوي المصفوفة على عنصر وحيد هو السلسلة النصية الأصلية كاملةً. وإذا كانت قيمة <code>separator</code> هي سلسلة نصية فارغة، فستحوَّل السلسلة النصية <code>str</code> إلى مصفوفة من المحارف؛ وإذا ظهرت قيمة <code>separator</code> في بداية أو نهاية السلسلة النصية أو في كلا المكانين، فستبدأ المصفوفة أو تنتهي أو تبدأ وتنتهي بسلسلةٍ نصيةٍ فارغة (على التوالي وبالترتيب)؛ وبالتالي لو احتوت السلسلة النصية على قيمة الفاصل <code>separator</code> فقط، فستتألف المصفوفة من عنصرين فارغين.

ملاحظة: عندما تكون السلسلة النصية فارغة، فستُعيد الدالة <code>split</code> مصفوفةً تحتوي على سلسلة نصية فارغة، وإذا كانت السلسلة النصية وقيمة الوسيط <code>separator</code> هي سلسلةٌ نصيةٌ فارغة، فستُعاد مصفوفة فارغة.

== أمثلة ==

=== استخدام <code>split()‎</code> ===
المثال الآتي يُعرِّف دالةً تُقسِّم السلسلة النصية إلى مصفوفة من السلاسل النصية الفرعية عبر الفاصل المُحدَّد. وبعد تقسيم السلسلة النصية فستطبع الدالة عدّة رسائل تُشير إلى السلسلة النصية الأصلية، والفاصل، وعدد عناصر المصفوفة، وكل عنصر من عناصرها:<syntaxhighlight lang="javascript">
function splitString(stringToSplit, separator) {
  var arrayOfStrings = stringToSplit.split(separator);

  console.log('The original string is: "' + stringToSplit + '"');
  console.log('The separator is: "' + separator + '"');
  console.log('The array has ' + arrayOfStrings.length + ' elements: ' + arrayOfStrings.join(' / '));
}

var tempestString = 'Oh brave new world that has such people in it.';
var monthString = 'Jan,Feb,Mar,Apr,May,Jun,Jul,Aug,Sep,Oct,Nov,Dec';

var space = ' ';
var comma = ',';

splitString(tempestString, space);
splitString(tempestString);
splitString(monthString, comma);
</syntaxhighlight>المثال السابق سيُظهِر الناتج الآتي:<syntaxhighlight lang="javascript">
The original string is: "Oh brave new world that has such people in it."
The separator is: " "
The array has 10 elements: Oh / brave / new / world / that / has / such / people / in / it.

The original string is: "Oh brave new world that has such people in it."
The separator is: "undefined"
The array has 1 elements: Oh brave new world that has such people in it.

The original string is: "Jan,Feb,Mar,Apr,May,Jun,Jul,Aug,Sep,Oct,Nov,Dec"
The separator is: ","
The array has 12 elements: Jan / Feb / Mar / Apr / May / Jun / Jul / Aug / Sep / Oct / Nov / Dec

</syntaxhighlight>

=== إزالة الفراغات من سلسلة نصية ===
ستبحث الدالة <code>split</code> في المثال الآتي عن 0 فراغًا أو أكثر يتبعها فاصلة منقوطة، ويليها 0 فراغًا. وعند العثور على ذلك فستحذف الفراغات والفاصلة المنقوطة وستحوّل السلاسل النصية الفرعية إلى عناصر مصفوفة باسم <code>nameList</code>:<syntaxhighlight lang="javascript">
var names = 'Jaber Hammad ;Mahdi Thabit; Ahmad Rida ; Rawda Hussien ;Kareem al-Hamdan';

// Jaber Hammad ;Mahdi Thabit; Ahmad Rida ; Rawda Hussien ;Kareem al-Hamdan
console.log(names);

var re = /\s*;\s*/;
var nameList = names.split(re);

// ["Jaber Hammad", "Mahdi Thabit", "Ahmad Rida", "Rawda Hussien", "Kareem al-Hamdan"]
console.log(nameList);

</syntaxhighlight>

=== إعادة عدد محدود من السلاسل النصية الفرعية ===
في المثال الآتي، ستبحث الدالة <code>split</code> عن الفراغات في السلسلة النصية وستُعيد أوّل ثلاث سلاسل فرعية تجدها:<syntaxhighlight lang="javascript">
var myString = 'Hello World. How are you doing?';
var splits = myString.split(' ', 3);

console.log(splits); // ["Hello", "World.", "How"]

</syntaxhighlight>

=== الأنماط الفرعية ===
إذا احتوى <code>separator</code> على أنماطٍ فرعيةٍ موجودةٍ ضمن أقواس، فستُعاد النتائج المُطابَقة في المصفوفة:<syntaxhighlight lang="javascript">
var myString = 'Hello 1 word. Sentence number 2.';
var splits = myString.split(/(\d)/);

console.log(splits); // [ "Hello ", "1", " word. Sentence number ", "2", "." ]

</syntaxhighlight>

=== عكس سلسلة نصية ===
يمكننا تقسيم السلسلة النصية إلى عناصر مصفوفة تتألف من أحرفها بجعل قيمة الوسيط <code>separator</code> سلسلةً نصيةً فارغةً، ثم باستخدام دوال معالجة المصفوفات (<code>[[JavaScript/Array/reverse|reverse]]</code> و <code>[[JavaScript/Array/join|join]]</code>):<syntaxhighlight lang="javascript">
var str = 'asdfghjkl';
var strReverse = str.split('').reverse().join(''); // 'lkjhgfdsa'

</syntaxhighlight>

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