PHP/strpos

(PHP 4, PHP 5, PHP 7)

تبحث الدالة strpos()‎ عن أول ظهور لمحارف معينَّة في سلسلة نصيَّة ثمَّ تعيد ترتيب موقعها في تلك السلسلة.

الوصف

int strpos ( string $haystack , mixed $needle [, int $offset = 0 ] )

تبحث هذه الدالة على أول ظهور للمحارف needle ضمن السلسلة النصيَّة haystack ثمَّ تعيد رقم موقعها في تلك السلسلة.

المعاملات

haystach

السلسلة النصيَّة التي ستبحث الدالة فيها.

needle

مجموعة المحارف التي ستبحث الدالة عنها. إن لم تكن تلك المحارف سلسلةً نصيَّةً، فستُحوَّل إلى عدد صحيح وتُعامل على أنَّها قيمة ترتيبيَّة للمحارف.

offset

معامل اختياري وهو قيمة إزاحة المؤشر من بداية السلسلة النصيَّة والذي يبدأ عنده البحث. إن كانت قيمة هذا المعامل سالبة، فسيبدأ البحث بعد إزاحة المؤشر من نهاية السلسلة النصيَّة والذي سيبدأ عند البحث.

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

تُعاد قيمة تمثل موقع وجود المعامل needle نسبةً إلى بداية المعامل haystack ودون أخذ قيمة الإزاحة offset بالحسبان. إن لم يُعثر على المعامل needle، فستُعاد القيمة FALSE.

تجدر الإشارة إلى أنَّ موقع أول محرف في السلسلة النصيَّة يبدأ من القيمة 0 وليس 1.

تحذير: تعيد أحيانًا هذه الدالة القيمة المنطقيَّة FALSE، وتعيد أحيانًا أخرى قيمة غير منطقيَّة ولكنَّها تعادل القيمة FALSE، لذا استعمل المعامل === للتحقق من القيمة التي تعيدها. يُفضل قراءة قسم القيم المنطقيَّة (boolean) للاطلاع على المزيد من المعلومات.

جدول التغييرات

الإصدار	الوصف
7.1.0	إضافة ميزة دعم القيم السالبة لمعامل الإزاحة offset.

أمثلة

المثال 1: استعمال المعامل ===

<?php
$mystring = 'abc';
$findme   = 'a';
$pos = strpos($mystring, $findme);

// لاحظ أنَّنا استعملنا المعامل ===. لن يجدي استعمال المعامل == نفعًا إذ لن يعمل كما 
//.هو الأول أي 0  'a' هو متوقع له لأنَّ موقع المحرف الذي نبحث عنه
if ($pos === false) {
    echo "The string '$findme' was not found in the string '$mystring'";
} else {
    echo "The string '$findme' was found in the string '$mystring'";
    echo " and exists at position $pos";
}
?>

المثال 2: استعمال المعامل ==!

<?php
$mystring = 'abc';
$findme   = 'a';
$pos = strpos($mystring, $findme);

// يمكن أيضًا استعمال المعامل ==!. لن يجدي استعمال المعامل =! نفعًا إذ لن يعمل كما 
//.هو الأول أي 0  'a' هو متوقع له لأن موقع المحرف الذي نبحث عنه
//.false القيمة (false != 0) تعادل العبارة 
if ($pos !== false) {
     echo "The string '$findme' was found in the string '$mystring'";
         echo " and exists at position $pos";
} else {
     echo "The string '$findme' was not found in the string '$mystring'";
}
?>

المثال 3: استعمال المعامل offset

<?php
// سيُتجاهل أي شيء يقع ضمن مجال الإزاحة عند بدء عملية البحث
$newstring = 'abcdef abcdef';
$pos = strpos($newstring, 'a', 1); // $pos = 7, not 0
?>

ملاحظات

تُعدُّ هذه الدالة آمنة ثنائيًّا (binary safe).

انظر أيضًا

• الدالة preg_match()‎: تبحث عن تعبير نمطي (regular expression) في سلسلة نصيَّة.
• الدالة strstr()‎: تبحث عن أول ظهور لسلسلة نصيَّة محدَّدة ضمن سلسلة نصيَّة أخرى.
• الدالة stripos()‎: تبحث عن أول ظهور لمحارف معينَّة في سلسلة نصيَّة دون تحسُّس حالة الأحرف ثمَّ تعيد رقم موقعها في تلك السلسلة.
• الدالة strrpos()‎: تبحث عن آخر ظهور لمحارف معينَّة في سلسلة نصيَّة ثمَّ تعيد رقم موقعها في تلك السلسلة.
• الدالة strripos()‎: تبحث عن آخر ظهور لمحارف معينَّة في سلسلة نصيَّة دون تحسُّس حالة الأحرف ثمَّ تعيد رقم موقعها في تلك السلسلة.
• الدالة substr()‎: تعيد جزءًا من السلسلة النصيَّة.
• الدالة strpbrk()‎: تبحث على مجموعة معيَّنة من المحارف ضمن سلسلة نصيَّة.

مصادر

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