عرض مصدر PHP/strpos

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

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

== الوصف ==
<syntaxhighlight lang="php">
int strpos ( string $haystack , mixed $needle [, int $offset = 0 ] )
</syntaxhighlight>تبحث هذه الدالة على أول ظهور للمحارف <code>needle</code> ضمن السلسلة النصيَّة <code>haystack</code> ثمَّ تعيد رقم موقعها في تلك السلسلة.

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

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

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

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

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

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

تحذير: تعيد أحيانًا هذه الدالة القيمة المنطقيَّة <code>FALSE</code>، وتعيد أحيانًا أخرى قيمة غير منطقيَّة ولكنَّها تعادل القيمة <code>FALSE</code>، لذا استعمل المعامل <code>[[PHP/comparison operators|===]]</code> للتحقق من القيمة التي تعيدها. يُفضل قراءة قسم [[PHP/boolean|القيم المنطقيَّة]] (boolean) للاطلاع على المزيد من المعلومات.

== جدول التغييرات ==
{| class="wikitable"
!الإصدار
!الوصف
|-
|7.1.0
|إضافة ميزة دعم القيم السالبة لمعامل الإزاحة <code>offset</code>.
|}

== أمثلة ==
المثال 1: استعمال المعامل <code>===</code><syntaxhighlight lang="php">
<?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";
}
?>
</syntaxhighlight>المثال 2: استعمال المعامل <code>==!</code><syntaxhighlight lang="php">
<?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'";
}
?>
</syntaxhighlight>المثال 3: استعمال المعامل <code>offset</code><syntaxhighlight lang="php">
<?php
// سيُتجاهل أي شيء يقع ضمن مجال الإزاحة عند بدء عملية البحث
$newstring = 'abcdef abcdef';
$pos = strpos($newstring, 'a', 1); // $pos = 7, not 0
?>
</syntaxhighlight>

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

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

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