الدالة substr_replace() في PHP
(PHP 4, PHP 5, PHP 7)
تبدِّل الدالة substr_replace() جزءًا معطى مكان جزءٍ موجودٍ ومحدَّدٍ ضمن سلسلة نصيَّة.
الوصف
mixed substr_replace ( mixed $string , mixed $replacement , mixed$start [, mixed $length ] )
تعيد هذه الدالة السلسلة النصيَّة string بعد أن تبدِّل السلسلة النصيَّة replacement المعطاة مكان الجزء المحدَّد بموقع البداية start وطول المحارف المراد استبدالها length (وهو معامل اختياري).
المعاملات
string
السلسلة النصيَّة التي سيُبحث فيها.
يمكن أن يكون هذا العامل مصفوفة وستُطبَّق آنذاك عمليَّة الاستبدال على كلِّ عنصر من عناصرها. يمكن في هذه الحالة أن تكون قيمة المعامل replacement والمعامل start والمعامل length قيمًا ذات أنواع بيانات أوليَّة (scalar) وستُطبَّق حينئذٍ تلك المعاملات على كلِّ عنصر من عناصر المصفوفة أثناء عمليَّة الاستبدال. يمكن أيضًا أن تكون تلك المعاملات مصفوفاتٍ وحينئذٍ سيُطبَّق كل عنصر من عناصر تلك المعاملات على العنصر المقابل له في المصفوفة string أثناء عمليَّة الاستبدال.
replacement
السلسلة النصيَّة التي ستحلُّ محلَّ الجزء المراد استبداله في المعامل string.
start
قيمة إزاحة موقع مؤشر البداية الذي ستبدأ عمليَّة الاستبدال عنده وذلك من بداية السلسلة النصيَّة إن كان موجبًا. إذا كانت قيمة هذا المعامل سالبة، فسيُزاح موقع المؤشر بدءًا من نهاية السلسلة النصيَّة لتبدأ بعد ذلك عمليَّة الاستبدال.
length
معامل اختياري وهو طول المحارف (عددها) المراد استبدالها وذلك بعد تحديد قيمة المعامل start. إن كانت قيمة هذا المعامل سالبة، فتمثِّل هذه القيمة عدد المحارف المراد استبدالها بدءًا من نهاية المعامل string وبعد أخذ قيمة المعامل start بالحسبان.
إن لم تعطَ قيمة هذا المعامل، فقيمته الافتراضيَّة هي القيمة strlen(string) أي تنتهي عمليَّة الاستبدال عند نهاية المعامل string. إن كانت قيمة هذا المعامل صفرًا، فسيَحلُّ المعامل replacement مكان المعامل string أينما وجد مع أخذ قيمة المعامل start بالحسبان.
القيم المعادة
يُعاد المعامل string بعد تبديل المعامل replacement مكان الجزء المحدَّد بالمعامل start والمعامل length. يتبع النوع المُعاد نوع المعامل string أي إذا كان نوع هذا المعامل مصفوفة فستُعاد مصفوفة.
أمثلة
المثال 1: استعمال الدالة substr_replace()
<?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";
?>
المثال 2: استعمال الدالة substr_replace() لاستبدال عدَّة سلاسل نصيَّة مرة واحدة
<?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";
?>
سيُظهر المثال السابق النتيجة التالية:
A: YYY; B: YYY; C: YYY
A: AAA; B: BBB; C: CCC
A: AAAXX; B: BBBX; C: CC
ملاحظة
هذه الدالة آمنة ثنائيًّا (binary safe).
انظر أيضًا
- الدالة
str_replace(): استبدال سلسلة نصية معينة بجميع السلاسل النصية التي يُعثر عليها. - الدالة
substr(): تعيد جزءًا من السلسلة النصيَّة. - الوصول إلى السلاسل النصية وتعديل محارفها.