PHP/strtok

(PHP 4, PHP 5, PHP 7)

تُقطِّع الدالة strtok()‎ السلسلة النصيَّة الممرَّرة إليها إلى سلاسل نصيَّة أصغر تدعى بالقطع (tokens)، وتدعى هذه العمليَّة بعمليَّة تقطيع السلاسل النصيَّة (tokenization).

الوصف

string strtok ( string $str , string $token )
string strtok ( string $token )

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

لاحظ أنَّه يمكن مواصله تقطيع سلسلة نصيَّة إلى قطع باستمرار وذلك باستدعاء الدالة strtok()‎ مع تمرير المعامل str إليها مرة واحدة فقط ثمَّ استدعائها في المرات اللاحقة مع تمرير المعامل token فقط إذ تستطيع الدالة تتبُّع آخر مكان توقفت عنده في تلك السلسلة النصيَّة. إن أردت بدء عمليَّة التقطيع من جديد أو أردت تقطيع سلسلة نصيَّة أخرى، فاستدع الدالة مع تمرير سلسلة نصيَّة إليها مرة أخرى (أي تمرير المعامل str من جديد).

لاحظ أيضًا أنَّه يمكن استعمال محارف متعدِّدة مع المعامل token وستُقطَع السلسلة النصيَّة حينئذٍ حالما يُعثر على أي محرف من تلك المحارف ضمن السلسلة.

المعاملات

str

السلسلة النصيَّة التي ستُقطَّع إلى أجزاء صغيرة (tokens).

token

محدِّدات التقطيع (delimiter) التي ستستعمل عند تقطيع المعامل str.

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

تُعاد قطعة من السلسلة النصيَّة str.

أمثلة

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

<?php
$string = "This is\tan example\nstring";
/* يمكن استعمال مسافة الجدولة والسطر الجديد بوصفها محارف تقطيع  */
$tok = strtok($string, " \n\t");

while ($tok !== false) {
    echo "Word=$tok<br />";
    $tok = strtok(" \n\t");
}
?>

المثال 2: توضيح تصرف الدالة عند عثورها على أجزاء فارغة

<?php
$first_token  = strtok('/something', '/');
$second_token = strtok('/');
var_dump($first_token, $second_token);
?>

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

  string(9) "something"
  bool(false)

ملاحظات

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

انظر أيضًا

• الدالة split()‎: تُقسِّم السلسلة النصيَّة الممررة إليها إلى عدَّة عناصر وتضعها ضمن مصفوفة وذلك باستعمال التعابير النمطيَّة (regular expression).
• الدالة explode()‎: تُقسِّم السلسلة النصيَّة المُمرَّرة إليها باستعمال سلسلة نصيَّة أخرى.

مصادر

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