عرض مصدر PHP/strtr

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

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

== الوصف ==
<syntaxhighlight lang="php">
string strtr ( string $str , string $from , string $to )
string strtr ( string $str , array $replace_pairs )
</syntaxhighlight>إن مُرِّر إلى هذه الدالة ثلاثة معاملات، فستُعيد نسخةً عن السلسلة النصيَّة <code>str</code> بعد أن تستبدل بكل حرف (بايت واحد) من المعامل <code>from</code> والموجود في السلسلة النصيَّة <code>str</code> مع ما يقابله من المعامل <code>to</code>. أي تستبدل بكل معامل <code>‏‎$from[$n]‎</code> المعامل <code>‏‎$to[$n]‎</code> إذ <code>‏‎$n</code> هي فهرسٌ صالحٌ موجودٌ في كلا المعاملين.

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

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

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

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

=== <code>str</code> ===
السلسلة النصيَّة المراد تحويل محارفها إلى محارف أخرى.

=== <code>from</code> ===
السلسلة النصيَّة التي ستُحوَّل إلى المعامل <code>to</code>.

=== <code>to</code> ===
السلسلة النصيَّة التي ستَحلُّ محلَّ المعامل <code>from</code>.

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

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

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

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

سيشرح هذا المثال كيفيَّة استعمال الدالة <code>strtr()‎</code> مع معاملين. لاحظ أنَّ عمليَّة استبدال الحرف 'h' لم تُنفَّذ لوجود قيم أطول تطابقت مع السلسلة النصيَّة الموجودة واستُبدلت بها قيم أخرى وبذلك استُثنت هذه القيم من عملية البحث والاستبدال مرة أخرى.<syntaxhighlight lang="php">
<?php
$trans = array("h" => "-", "hello" => "hi", "hi" => "hello");
echo strtr("hi all, I said hello", $trans);
?>
</syntaxhighlight>سيُظهر المثال السابق النتيجة التالية:<syntaxhighlight lang="php">
hello all, I said hi
</syntaxhighlight>إن وازنَّا هذا المثال مع المثال السابق، فنجد أنَّ هذين الوضعين مختلفين بصورة ملحوظة، فإذا استعملنا الدالة <code>strtr()‎</code> مع ثلاثة معاملات، فستَستبدل كلَّ بايت مع ما يقابله بدءًا من بداية السلسلة بينما إن استعملناها مع معاملين فستستبدل السلسلة النصيَّة الأطول أولًا.

المثال 3: موازنة سلوك الدالة <code>strtr()‎</code> مع معاملين ومع ثلاثة معاملات<syntaxhighlight lang="php">
<?php
echo strtr("baab", "ab", "01"),"\n";

$trans = array("ab" => "01");
echo strtr("baab", $trans);
?>
</syntaxhighlight>سيُظهر المثال السابق النتيجة التالية:<syntaxhighlight lang="php">
1001
ba01
</syntaxhighlight>

== انظر أيضًا ==
* الدالة <code>[[PHP/preg match|preg_match()‎]]</code>: تبحث عن تعابير نمطيَّة (regular expression) في سلسلة نصيَّة وتستبدل به سلسلة نصيَّة أخرى.
* الدالة <code>[[PHP/str replace|str_replace()‎]]</code>: تبحث عن وجود سلسلة نصيَّة محدَّدة وتستبدل بها أخرى.

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