PHP/strspn

(PHP 4, PHP 5, PHP 7)

تبحث الدالة strspn()‎ عن الجزء الذي تبدأ به السلسلة النصيَّة الممرَّرة والذي تكون جميع محارفه محدَّدة ومعرَّفة مسبقًا ثمَّ تعيد بعدئذٍ طول ذلك الجزء.

الوصف

int strspn ( string $subject , string $mask [, int $start [, int$length ]] )

تبحث هذه الدالة عن القسم الذي تبدأ به السلسلة النصيَّة subject والذي تتكون جميع محارفه من المحارف mask المعطاة. إن لم يعطَ موقع بداية البحث start والطول الذي ستبحث الدالة فيه length، فستبحث الدالة في جميع محارف السلسلة النصيَّة subject. إن أُعطيت قيمة هذين المعاملين، فسنحصل على نتيجة مشابه تمامًا للنتيجة strspn(substr($subject, $start, $length), $mask)‎. راجع صفحة الدالة substr()‎ للمزيد من المعلومات. انظر إلى السطر البرمجي التالي:

<?php

$var = strspn("42 is the answer to the 128th question.", "1234567890");

?>

ستُسند القيمة 2 للمتغير var لأنَّ السلسلة النصيَّة "42" هي أول جزء بدأت به السلسلة النصيَّة subject والذي كانت جميع محارفه من ضمن المحارف "1234567890" المعطاة.

المعاملات

subject

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

mask

مجموعة المحارف المسموحة التي ستبحث الدالة عنها.

start

معامل اختياري وهو موقع المحرف في السلسلة النصيَّة subject الذي سيبدأ البحث عنده.

إن كانت قيمة هذا المعامل موجبة، فستبدأ الدالة strspn()‎ عمليَّة البحث في السلسلة النصيَّة subject عند المحرف ذو الموقع  start من بداية السلسلة. ستجد مثلًا أنَّ المحرف ذو الموقع 0 في السلسلة النصيَّة "abcdef" هو 'a' والمحرف ذو الموقع 2 هو 'c' وهلم جرًّا.

إن كانت قيمة هذا المعامل سالبة، فستبدأ الدالة strspn()‎ عملية البحث في السلسلة النصيَّة subject عند المحرف ذي الموقع start من نهاية السلسلة.

length

معامل اختياري وهو طول الجزء الذي ستبحث به الدالة فقط ضمن السلسلة النصيَّة subject.

إن كانت قيمة هذا المعامل موجبة، فستبدأ عمليَّة البحث في السلسلة النصيَّة subject من موقع البداية start وبطول length وذلك من بداية السلسلة.

إن كانت قيمة هذا المعامل سالبة، فستبدأ عمليَّة البحث في السلسلة النصيَّة subject من موقع البداية start وبطول length وذلك من نهاية السلسلة أي بطريقة معاكسة.

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

تُعاد قيمة تمثل طول الجزء الذي يبدأ به المعامل subject والذي تتكون جميع محارفه من المحارف المحدَّدة في المعامل mask.

ملاحظة: إن مُرِّر المعامل start، فستكون بداية الطول المُعاد هي من الموقع start المعطى وليست من بداية السلسلة النصيَّة subject.

أمثلة

المثال 1: استعمال الدالة strspn()‎

<?php
// لا تبدأ السلسلة النصيَّة بأي محرف من المحارف المعطاة
var_dump(strspn("foo", "o"));

// بدء عملية البحث من موقع المحرف 1 وبطول 2 وبذلك تعثر الدالة على محرفين بدأت بهما السلسلة النصيَّّة
var_dump(strspn("foo", "o", 1, 2));

// بدء عملية البحث من موقع المحرف 1 وبطول 1 وبذلك تعثر الدالة على محرف واحد بدأت به السلسلة النصيَّة
var_dump(strspn("foo", "o", 1, 1));
?>

سيُظهر المثال السابق النتيجة التالية:

int(0)
int(2)
int(1)

ملاحظات

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

انظر أيضًا

• الدالة strcspn()‎: تبحث عن أول جزء تبدأ به السلسلة النصيَّة الممرَّرة والذي تكون جميع محارفه غير متطابقة مع المحارف المعطاة ثمَّ تعيد بعدئذٍ طول ذلك الجزء.

مصادر

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