عرض مصدر PHP/array splice

<noinclude>{{DISPLAYTITLE:<code>array_splice()‎</code>}}</noinclude>
(PHP 4, PHP 5, PHP 7)

تُزيل الدالة <code>array_splice()</code>‎ جزءًا من المصفوفة وتستبدله بشيء آخر.

== الوصف ==
<syntaxhighlight lang="php">
array array_splice ( array &$input , int $offset [, int $length = count($input) [, mixed$replacement = array() ]] )
</syntaxhighlight>تزيل الدالةُ العناصرَ المُعيّنة عن طريق المعاملَيْن <code>offset</code> و<code>length</code> من المصفوفة <code>input</code>، ويستبدلها بعناصر المصفوفة <code>replacement</code>، إذا تم توفيرها.

لاحظ أنه لا يُحتَفَظ بمفاتيح رقمية للمصفوفة <code>input</code>.

ملاحظة: إذا لم يكن المعامل <code>replacement</code> مصفوفةً، [[PHP/array#.D8.A7.D9.84.D8.AA.D8.AD.D9.88.D9.8A.D9.84 .D8.A5.D9.84.D9.89 .D9.85.D8.B5.D9.81.D9.88.D9.81.D8.A7.D8.AA|فسيعوَّض بواحد]] (على سبيل المثال <code>array) $replacement)</code> ). قد ينتج عن هذا سلوكٌ غير متوقع عند استخدام كائن أو الاستبدال بالقيمة <code>NULL</code>.

== المعاملات ==

=== <code>input</code> ===
المصفوفة المدخلة.

=== <code>offset</code> ===
إذا كان معامل الإزاحة <code>offset</code> موجبًا، فإن إزاحة الجزء المُزال ستكون من بداية المصفوفة <code>input</code>. أما إذا كان <code>offset</code> سالبًا فإن الإزاحة ستبدأ من نهاية المصفوفة <code>input</code>.

=== <code>length</code> ===
إذا حُذِفَ معامل الطول <code>length</code>، فستزيل الدالة كل شيء بداية من <code>offset</code> وحتى نهاية المصفوفة. وإذا كان <code>length</code> محددًا وموجبًا ، فستُزيل هذا العدد من العناصر. وإذا كان <code>length</code> محددًا وسالبًا، فستكون نهاية الجزء الذي يُزال هو عدد العناصر تنازليًا من نهاية المصفوفة. وإذا حُدِّدت قيمة المعامل  <code>length</code> وكان صفرًا، فلن يزال أي عناصر. نصيحة: لإزالة كل شيء من offset إلى نهاية المصفوفة وعندما تكون المصفوفة <code>replacement</code> معرّفة أيضًا، فاستخدم <code>count($input)</code>‎ كقيمةٍ للمعامل <code>length</code>.

=== <code>replacement</code> ===
إذا حُدِّدَت المصفوفة <code>replacement</code>، فستستبدل العناصر التي أُزيلت بعناصر من هذه المصفوفة.

إذا كانت قيم المعاملَيْن offset وlength محدَدَيْن بحيث لا تزيل أي شيء، فستدرج العناصر من المصفوفة <code>replacement</code> في المكان المحدد بواسطة المعامل <code>offset</code>. لاحظ أن المفاتيح في مصفوفة الاستبدال لا تُحفظ.

إذا كان المعامل <code>replacement</code> يُمثِّل عنصرًا واحدًا فقط، فليس من الضروري وضع <code>array()</code>‎ حوله، ما لم يكن العنصر عبارة عن مصفوفة بحد ذاته أو كائن أو <code>NULL</code>.

== القيم المعادة ==
تعيد الدالة مصفوفة مكونة من العناصر المستخرجة.

== أمثلة ==
المثال 1: أمثلة على الدالة <code>array_splice()</code>‎<syntaxhighlight lang="php">
<?php
$input = array("red", "green", "blue", "yellow");
array_splice($input, 2);
// $input أصبحت الآن array("red", "green")
$input = array("red", "green", "blue", "yellow");
array_splice($input, 1, -1);
// $input أصبحت الآن array("red", "yellow")
$input = array("red", "green", "blue", "yellow");
array_splice($input, 1, count($input), "orange");
// $input أصبحت الآن array("red", "orange")
$input = array("red", "green", "blue", "yellow");
array_splice($input, -1, 1, array("black", "maroon"));
// $input أصبحت الآن array("red", "green",
//          "blue", "black", "maroon")
$input = array("red", "green", "blue", "yellow");
array_splice($input, 3, 0, "purple");
// $input أصبحت الآن array("red", "green",
//          "blue", "purple", "yellow");
?>
</syntaxhighlight>المثال 2: أمثلة على الدالة <code>array_splice()</code>‎

الأمثلة التالية تغير قيم ‎ <code>$input</code>بنفس الطريقة:<syntaxhighlight lang="php">
<?php
// إلحاق عنصرين إلى  ‎ $input
array_push($input, $x, $y);
array_splice($input, count($input), 0, array($x, $y));
// إزالة آخر عنصرين من  ‎ $input
array_pop($input);
array_splice($input, -1);
// أزل العنصر الأول من  ‎ $input
array_shift($input);
array_splice($input, 0, 1);
// إدراج عنصر في بداية  ‎ $input
array_unshift($input, $x, $y);
array_splice($input, 0, 0, array($x, $y));
// استبدال القيمة في ‎ $inputعند المؤشر ‎$x
$input[$x] = $y; // للمصفوفات عندما يساوي المفتاح الإزاحة
array_splice($input, $x, 1, $y);
?>
</syntaxhighlight>

== انظر أيضًا ==
* الدالة <code>[[PHP/array_slice|array_slice()]]</code>‎: استخراج شريحة من المصفوفة.
* الدالة <code>[[PHP/array_unset|unset()]]</code>‎: إلغاء تعيين متغير معين.
* الدالة <code>[[PHP/array_merge|array_merge()]]</code>‎: دمج مصفوفة واحدة أو أكثر.

== مصادر ==
* [http://php.net/manual/en/function.array-splice.php صفحة الدالة array_splice في توثيق PHP الرسمي].
[[تصنيف:PHP]]
[[تصنيف:PHP Function]]
[[تصنيف:PHP Array]]