PHP/strtr

(PHP 4, PHP 5, PHP 7)

تحوِّل الدالة strtr()‎ محارف أو سلاسل نصيَّة محدَّدة أو تستبدل بها أخرى غيرها.

الوصف

string strtr ( string $str , string $from , string $to )
string strtr ( string $str , array $replace_pairs )

إن مُرِّر إلى هذه الدالة ثلاثة معاملات، فستُعيد نسخةً عن السلسلة النصيَّة str بعد أن تستبدل بكل حرف (بايت واحد) من المعامل from والموجود في السلسلة النصيَّة str مع ما يقابله من المعامل to. أي تستبدل بكل معامل ‏‎$from[$n]‎ المعامل ‏‎$to[$n]‎ إذ ‏‎$n هي فهرسٌ صالحٌ موجودٌ في كلا المعاملين.

إن كان طول المعامل from مختلفًا عن المعامل to أو العكس، فستُهمل الأحرف الزائدة في المعامل الأطول إذ يكون طول السلسلة النصيَّة str هو ذاته ولا يتغير عند إعادته.

من جهة أخرى، إن مُرِّر إلى الدالة معاملين، فيجب أن يكون المعامل الثاني هو مصفوفة بالشكل array('from' => 'to', ...)‎. تُعاد حينئذٍ السلسلة النصيَّة string بعد تبديل كل عنصر من عناصر المصفوفة والموجود في تلك السلسلة مع القيمة المقابلة له. سيُستبدل العنصر الأطول من عناصر تلك المصفوفة أولًا، ولن يشمل البحث بعدئذٍ القيم الجديدة التي استُبدلت.

يمكن في هذه الحالة أن يختلف طول القيمة المراد استبدالها عن القيمة الجديدة، بغض النظر عن عدم امكانيَّة وجود قيم فارغة، وبذلك يكون طول القيمة المعادة مختلفًا عن طول المعامل str. على أي حال، تكون هذه الدالة ذات كفاءة أكبر عندما تكون كل القيم ذات طول متساوٍ.

المعاملات

str

السلسلة النصيَّة المراد تحويل محارفها إلى محارف أخرى.

from

السلسلة النصيَّة التي ستُحوَّل إلى المعامل to.

to

السلسلة النصيَّة التي ستَحلُّ محلَّ المعامل from.

replace_pairs

يمكن استعمال هذا المعامل عوضًا عن المعامل from والمعامل to، ويجب أن يكون مصفوفة وبالشكل array('from' => 'to', ...)‎.

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

تُعاد سلسلة نصيَّة كما في الأعلى.

إن احتوى المعامل replace_pairs على قيمة فارغة ("")، فستعاد القيمة FALSE. إن لم يكن نوع المعامل str من أحد أنواع البيانات الأوليَّة (scalar) فلن يُغيَّر نوعه إلى سلسلة نصيَّة، وستُعاد آنذاك القيمة NULL مع إصدار تنبيه.

أمثلة

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

<?php
//ستجري هذه الدالة عملية التحويل بايتًا ببايت
//وبذلك نفترض أن ترميز المحارف المستعمل هو تخزين كل محرف ببايت واحد
$addr = strtr($addr, "äåö", "aao");
?>

المثال 2: استعمال الدالة strtr()‎ مع معاملين سيشرح هذا المثال كيفيَّة استعمال الدالة strtr()‎ مع معاملين. لاحظ أنَّ عمليَّة استبدال الحرف 'h' لم تُنفَّذ لوجود قيم أطول تطابقت مع السلسلة النصيَّة الموجودة واستُبدلت بها قيم أخرى وبذلك استُثنت هذه القيم من عملية البحث والاستبدال مرة أخرى.

<?php
$trans = array("h" => "-", "hello" => "hi", "hi" => "hello");
echo strtr("hi all, I said hello", $trans);
?>

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

hello all, I said hi

إن وازنَّا هذا المثال مع المثال السابق، فنجد أنَّ هذين الوضعين مختلفين بصورة ملحوظة، فإذا استعملنا الدالة strtr()‎ مع ثلاثة معاملات، فستَستبدل كلَّ بايت مع ما يقابله بدءًا من بداية السلسلة بينما إن استعملناها مع معاملين فستستبدل السلسلة النصيَّة الأطول أولًا. المثال 3: موازنة سلوك الدالة strtr()‎ مع معاملين ومع ثلاثة معاملات

<?php
echo strtr("baab", "ab", "01"),"\n";

$trans = array("ab" => "01");
echo strtr("baab", $trans);
?>

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

1001
ba01

انظر أيضًا

• الدالة preg_match()‎: تبحث عن تعابير نمطيَّة (regular expression) في سلسلة نصيَّة وتستبدل به سلسلة نصيَّة أخرى.
• الدالة str_replace()‎: تبحث عن وجود سلسلة نصيَّة محدَّدة وتستبدل بها أخرى.

مصادر

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