عرض مصدر PHP/substr replace

<noinclude>{{DISPLAYTITLE:الدالة <code>substr_replace()</code>‎ في PHP}}</noinclude>
(PHP 4, PHP 5, PHP 7)

تبدِّل الدالة <code>substr_replace()‎</code> جزءًا معطى مكان جزءٍ موجودٍ ومحدَّدٍ ضمن سلسلة نصيَّة.

== الوصف ==
<syntaxhighlight lang="php">
mixed substr_replace ( mixed $string , mixed $replacement , mixed$start [, mixed $length ] )
</syntaxhighlight>تعيد هذه الدالة السلسلة النصيَّة <code>string</code> بعد أن تبدِّل السلسلة النصيَّة <code>replacement</code> المعطاة مكان الجزء المحدَّد بموقع البداية <code>start</code> وطول المحارف المراد استبدالها <code>length</code> (وهو معامل اختياري).

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

=== <code>string</code> ===
السلسلة النصيَّة التي سيُبحث فيها.

يمكن أن يكون هذا العامل مصفوفة وستُطبَّق آنذاك عمليَّة الاستبدال على كلِّ عنصر من عناصرها. يمكن في هذه الحالة أن تكون قيمة المعامل <code>replacement</code> والمعامل <code>start</code> والمعامل <code>length</code> قيمًا ذات أنواع بيانات أوليَّة (scalar) وستُطبَّق حينئذٍ تلك المعاملات على كلِّ عنصر من عناصر المصفوفة أثناء عمليَّة الاستبدال. يمكن أيضًا أن تكون تلك المعاملات مصفوفاتٍ وحينئذٍ سيُطبَّق كل عنصر من عناصر تلك المعاملات على العنصر المقابل له في المصفوفة <code>string</code> أثناء عمليَّة الاستبدال.

=== <code>replacement</code> ===
السلسلة النصيَّة التي ستحلُّ محلَّ الجزء المراد استبداله في المعامل <code>string</code>.

=== <code>start</code> ===
قيمة إزاحة موقع مؤشر البداية الذي ستبدأ عمليَّة الاستبدال عنده وذلك من بداية السلسلة النصيَّة إن كان موجبًا. إذا كانت قيمة هذا المعامل سالبة، فسيُزاح موقع المؤشر بدءًا من نهاية السلسلة النصيَّة لتبدأ بعد ذلك عمليَّة الاستبدال.

=== <code>length</code> ===
معامل اختياري وهو طول المحارف (عددها) المراد استبدالها وذلك بعد تحديد قيمة المعامل <code>start</code>. إن كانت قيمة هذا المعامل سالبة، فتمثِّل هذه القيمة عدد المحارف المراد استبدالها بدءًا من نهاية المعامل <code>string</code> وبعد أخذ قيمة المعامل <code>start</code> بالحسبان.

إن لم تعطَ قيمة هذا المعامل، فقيمته الافتراضيَّة هي القيمة <code>[[PHP/strlen|strlen(string)‎]]</code> أي تنتهي عمليَّة الاستبدال عند نهاية المعامل <code>string</code>. إن كانت قيمة هذا المعامل صفرًا، فسيَحلُّ المعامل <code>replacement</code> مكان المعامل <code>string</code> أينما وجد مع أخذ قيمة المعامل <code>start</code> بالحسبان.

== القيم المعادة ==
يُعاد المعامل <code>string</code> بعد تبديل المعامل <code>replacement</code> مكان الجزء المحدَّد بالمعامل <code>start</code> والمعامل <code>length</code>. يتبع النوع المُعاد نوع المعامل <code>string</code> أي إذا كان نوع هذا المعامل مصفوفة فستُعاد مصفوفة.

== أمثلة ==
المثال 1: استعمال الدالة <code>substr_replace()‎</code><syntaxhighlight lang="php">
<?php
$var = 'ABCDEFGH:/MNRPQR/';
echo "Original: $var<hr />\n";

/*$var بالسلسلة النصيَّة 'bob' يوضح هذان المثالان كيفيَّة استبدال العبارة */
echo substr_replace($var, 'bob', 0) . "<br />\n";
echo substr_replace($var, 'bob', 0, strlen($var)) . "<br />\n";

/*$var في بداية السلسلة النصيَّة 'bob' إدراج العبارة*/
echo substr_replace($var, 'bob', 0, 0) . "<br />\n";

/*$var الموجودة في السلسلة النصيَّة 'MNRPQR' بالقيمة 'bob' يوضح المثالان التاليان كيفيَّة استبدال القيمة */
echo substr_replace($var, 'bob', 10, -1) . "<br />\n";
echo substr_replace($var, 'bob', -7, -1) . "<br />\n";

/*$var من السلسلة النصيَّة 'MNRPQR' حذف العبارة */
echo substr_replace($var, '', 10, -1) . "<br />\n";
?>
</syntaxhighlight>المثال 2: استعمال الدالة <code>substr_replace()‎</code> لاستبدال عدَّة سلاسل نصيَّة مرة واحدة<syntaxhighlight lang="php">
<?php
$input = array('A: XXX', 'B: XXX', 'C: XXX');

//في كل سلسلة نصيَّة YYY بالقيمة XXX حالة بسيطة وهي استبدال القيمة
echo implode('; ', substr_replace($input, 'YYY', 3, 3))."\n";

// حالة معقدة قليلًا إذ يختلف هنا كلُّ استبدال عن غيره
$replace = array('AAA', 'BBB', 'CCC');
echo implode('; ', substr_replace($input, $replace, 3, 3))."\n";

// استبدال عدد مختلف من المحارف في كل مرَّة
$length = array(1, 2, 3);
echo implode('; ', substr_replace($input, $replace, 3, $length))."\n";
?>
</syntaxhighlight>سيُظهر المثال السابق النتيجة التالية:<syntaxhighlight lang="php">
A: YYY; B: YYY; C: YYY
A: AAA; B: BBB; C: CCC
A: AAAXX; B: BBBX; C: CC
</syntaxhighlight>

== ملاحظة ==
هذه الدالة آمنة ثنائيًّا (binary safe).

== انظر أيضًا ==
* الدالة <code>[[PHP/str replace|str_replace()‎]]</code>: استبدال سلسلة نصية معينة بجميع السلاسل النصية التي يُعثر عليها.
* الدالة <code>[[PHP/substr|substr()‎]]</code>: تعيد جزءًا من السلسلة النصيَّة.
* [[PHP/String|الوصول إلى السلاسل النصية وتعديل محارفها]].

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