PHP/substr compare

(PHP 4, PHP 5, PHP 7)

توازن الدالة substr_compare()‎ بطريقة آمنة ثنائيًّا (binary safe) بين سلسلتين نصيَّتين وذلك من قيمة إزاحة معيَّنة وحتى طول محدَّد من المحارف.

الوصف

int substr_compare ( string $main_str , string $str , int $offset [, int $length [, bool $case_insensitivity = FALSE ]] )

توازن هذه الدالة السلسلة النصيَّة الرئيسية main_str بدءًا من موقع الإزاحة offset وبطول length -عدد المحارف التي ستُوازن- مع السلسلة النصيَّة str.

المعاملات

main_str

السلسلة النصيَّة الرئيسيَّة التي ستُوازن.

str

السلسلة النصيَّة الثانويَّة التي ستُوازن.

offset

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

length

معامل اختياري وهو طول المحارف (عددها) التي ستدخل في عمليَّة الموازنة. القيمة الافتراضيَّة لهذا المعامل هي القيمة الأكبر لطول المعامل str بالموازنة مع طول المعامل main_str مطروحًا منه قيمة المعامل offset.

case_insensitivity

معامل اختياري. إن كانت قيمته TRUE، فستُجرى عمليَّة الموازنة دون تحسُّس حالة الأحرف.

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

تُعاد قيمة أصغر من الصفر إن كان المعامل main_str بدءًا من الموقع offset أصغر من المعامل str، وقيمة أكبر من الصفر إن كانت تلك القيمة أكبر من المعامل str، والقيمة صفر إن كانتا متساويتان. إن كانت قيمة المعامل offset أكبر من طول المعامل main_str أو كانت قيمة المعامل length أصغر من الواحد (في إصدار ما قبل PHP 5.5.11)، فستُعاد القيمة FALSE مع ظهور تنبيه.

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

الإصدار	الوصف
5.5.11	يمكن أن تكون قيمة المعامل length صفرًا.
5.1.0	إضافة امكانيَّة أن تكون قيمة المعامل offset سالبة.

أمثلة

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

<?php
echo substr_compare("abcde", "bc", 1, 2); // 0
echo substr_compare("abcde", "de", -2, 2); // 0
echo substr_compare("abcde", "bcg", 1, 2); // 0
echo substr_compare("abcde", "BC", 1, 2, true); // 0
echo substr_compare("abcde", "bc", 1, 3); // 1
echo substr_compare("abcde", "cd", 1, 2); // -1
echo substr_compare("abcde", "abc", 5, 1); // warning
?>

انظر أيضًا

• الدالة strncmp()‎: توازن بطريقة آمنة ثنائيًّا بين سلسلتين نصيَّتين لعدد معيّن من المحارف انطلاقًا من بداية السلسلة النصيَّّة.

مصادر

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