PHP/substr

(PHP 4, PHP 5, PHP 7)

تعيد الدالة substr()‎ جزءًا من السلسلة النصيَّة الممرَّرة إليها.

الوصف

string substr ( string $string , int $start [, int $length ] )

تعيد هذه الدالة جزءًا من السلسلة النصيَّة string المحدَّد بموقع البداية start وعدد المحارف length المطلوبة.

المعاملات

string

السلسلة النصيَّة المراد الحصول على جزء منها. يجب أن تتكون من محرف واحد على الأقل.

start

قيمة إزاحة موقع مؤشر البداية الذي يحدِّد بداية السلسلة النصيَّة التي ستُعاد بدءًا من بداية السلسلة النصيَّة string. ستجد مثلًا أنَّ المحرف ذو الموقع 0 في السلسلة النصيَّة "abcdef" هو 'a' والمحرف ذو الموقع 2 هو 'c' وهلم جرًّا.

إن كانت قيمة هذا المعامل سالبة، فستبدأ السلسلة النصية المُعادة من هذه الدالة من الموضع الذي يبعد مسافةً تُقدَّر بقيمة المعامل start عن نهاية السلسلة النصية string.

إن كان طول السلسلة النصيَّة string أقل من قيمة المعامل start، فستُعاد القيمة FALSE.

المثال 1: استعمال قيم سالبة مع المعامل start

<?php
$rest = substr("abcdef", -1);    // "f"
$rest = substr("abcdef", -2);    // "ef"
$rest = substr("abcdef", -3, 1); // "d"
?>

length

إن أعطيت قيمة هذا المعامل وكانت موجبة، فستمثِّل العدد الأقصى لمحارف السلسلة النصيَّة التي ستُعاد بدءًا من الموقع start وذلك من بداية السلسلة النصيَّة string (تتعلق تلك القيمة بطول المعامل string).

أمَّا إن كانت قيمة هذا المعامل سالبة، فهي عدد المحارف التي ستُحذف بدءًا من نهاية السلسلة النصيَّة string وذلك بعد حساب موقع البداية عندما يكون المعامل start سالبًا. إن أشار موقع البداية start إلى أيٍّ من تلك المحارف التي حذفت آنذاك أو إلى محارف خارج السلسلة، فستُعاد القيمة FALSE.

إن أعطيت قيمة المعامل length وكانت 0 أو FALSE أو NULL، فستُعاد سلسلة نصيَّة فارغة.

إن لم تُعطَ قيمة هذا المعامل، فستُعاد السلسلة النصيَّة التي تبدأ عند الموقع start وتنتهي عند نهاية السلسلة النصيَّة string.

المثال 2: استعمال قيم سالبة مع المعامل length

<?php
$rest = substr("abcdef", 0, -1);  // "abcde"
$rest = substr("abcdef", 2, -1);  // "cde"
$rest = substr("abcdef", 4, -4);  // false
$rest = substr("abcdef", -3, -1); // "de"
?>

القيم المعادة

يُعاد الجزء الذي اقتُطع من المعامل string، أو القيمة FALSE إن فشلت عمليَّة الاقتطاع، أو سلسلة نصيَّة فارغة.

سجل التغييرات

الإصدار	الوصف
7.0.0	إن كان طول المعامل string مساويًا إلى قيمة المعامل start، فستُعاد سلسلة نصيَّة فارغة. كانت تُعاد القيمة FALSE في هذه الحالة وذلك في الإصدارات السابقة.
5.2.2 - 5.2.6	إن أشار المعامل start إلى موقع المحارف المحذوفة (عندما يكون المعامل length سالبًا) أو إلى محارف خارج السلسلة، فستُعاد القيمة FALSE. بينما تُعاد السلسلة النصيَّة من البداية في الإصدارات الأخرى.

أمثلة

المثال 3: استعمال الدالة substr()‎

<?php
echo substr('abcdef', 1);     // bcdef
echo substr('abcdef', 1, 3);  // bcd
echo substr('abcdef', 0, 4);  // abcd
echo substr('abcdef', 0, 8);  // abcdef
echo substr('abcdef', -1, 1); // f

// يمكن الحصول على محرف واحد ضمن السلسلة النصية أيضًا
// باستعمال الأقواس المربَّعة [] كما موضح
$string = 'abcdef';
echo $string[0];                 // a
echo $string[3];                 // d
echo $string[strlen($string)-1]; // f

?>

المثال 4: توضيح سلوك التحويل (casting behaviour) للدالة substr()‎

<?php
class apple {
    public function __toString() {
        return "green";
    }
}

echo "1) ".var_export(substr("pear", 0, 2), true).PHP_EOL;
echo "2) ".var_export(substr(54321, 0, 2), true).PHP_EOL;
echo "3) ".var_export(substr(new apple(), 0, 2), true).PHP_EOL;
echo "4) ".var_export(substr(true, 0, 1), true).PHP_EOL;
echo "5) ".var_export(substr(false, 0, 1), true).PHP_EOL;
echo "6) ".var_export(substr("", 0, 1), true).PHP_EOL;
echo "7) ".var_export(substr(1.2e3, 0, 4), true).PHP_EOL;
?>

سيُظهر المثال السابق باستعمال إصدار PHP 7 النتيجة التالية:

1) 'pe'
2) '54'
3) 'gr'
4) '1'
5) ''
6) ''
7) '1200'

سيُظهر المثال السابق باستعمال إصدار PHP 5 النتيجة التالية:

1) 'pe'
2) '54'
3) 'gr'
4) '1'
5) false
6) false
7) '1200'

الأخطاء والاستثناءات

تعيد القيمة FALSE عند حصول أي خطأ.

<?php

var_dump(substr('a', 2)); // bool(false)

?>

انظر أيضًا

• الدالة strrchr()‎: تبحث عن وجود محرف معيَّن في سلسلة نصيَّة ثمَّ تعيد ما بعده.
• الدالة substr_replace()‎: تبدِّل جزءًا معطى مكان جزءٍ موجودٍ ومحدَّدٍ ضمن سلسلة نصيَّة.
• الدالة preg_match()‎: تبحث عن تعبير نمطي (regular expression) في سلسلة نصيَّة.
• الدالة trim()‎: تزيل المسافات البيضاء (whitespace) (جميع محارف الفراغات) أو أي محرف آخر من بداية السلسلة النصيَّة أو نهايتها.
• الدالة mb_substr()‎: تعيد جزءًا من سلسلة نصيَّة.
• الدالة wordwrap()‎: تؤمِّن التفاف السلسلة النصيِّة عند عدد محدَّد من المحارف.
• الوصول إلى السلاسل النصيَّة وتعديل محارفها.

مصادر

• صفحة الدالة substr في توثيق PHP الرسمي.