svn: /phpdoc/en/trunk/reference/strings/functions/ strtr.xml

From: Date: Sat, 02 Oct 2010 08:48:14 +0000
Subject: svn: /phpdoc/en/trunk/reference/strings/functions/ strtr.xml
Groups: php.doc.cvs 
Request: Send a blank email to doc-cvs+get-7183@lists.php.net to get a copy of this message
cataphract Sat, 02 Oct 2010 08:48:14 +0000 Revision: http://svn.php.net/viewvc?view=revision&revision=303931 Log: - Substantially improved the documentation of strtr(). Closes bug #52968. Bug: http://bugs.php.net/52968 (Bogus) Static private attributes visibility Changed paths: U phpdoc/en/trunk/reference/strings/functions/strtr.xml Modified: phpdoc/en/trunk/reference/strings/functions/strtr.xml =================================================================== --- phpdoc/en/trunk/reference/strings/functions/strtr.xml 2010-10-02 06:35:36 UTC (rev 303930) +++ phpdoc/en/trunk/reference/strings/functions/strtr.xml 2010-10-02 08:48:14 UTC (rev 303931) @@ -3,7 +3,7 @@ <refentry xmlns="http://docbook.org/ns/docbook" xml:id="function.strtr" xmlns:xlink="http://www.w3.org/1999/xlink"> <refnamediv> <refname>strtr</refname> - <refpurpose>Translate certain characters</refpurpose> + <refpurpose>Translate characters or replace substrings</refpurpose> </refnamediv> <refsect1 role="description"> @@ -20,16 +20,35 @@ <methodparam><type>array</type><parameter>replace_pairs</parameter></methodparam> </methodsynopsis> <para> - This function returns a copy of <parameter>str</parameter>, - translating all occurrences of each character in - <parameter>from</parameter> to the corresponding character in - <parameter>to</parameter>. + If given three arguments, this function returns a copy of + <parameter>str</parameter> where all occurrences of each (single-byte) + character in <parameter>from</parameter> have been translated to the + corresponding character in <parameter>to</parameter>, i.e., every + occurrence of <literal>$from[$n]</literal> has been replaced with + <literal>$to[$n]</literal>, where <literal>$n</literal> is a valid + offset in both arguments. </para> <para> - If <parameter>from</parameter> and <parameter>to</parameter> are + If <parameter>from</parameter> and <parameter>to</parameter> have different lengths, the extra characters in the longer of the two - are ignored. + are ignored. The length of <parameter>str</parameter> will be the same as + the return value's. </para> + <para> + If given two arguments, the second should be an <type>array</type> in the + form <literal>array('from' => 'to', ...)</literal>. The return value is + a <type>string</type> where all the occurrences of the array keys have been + replaced by the corresponding values. The longest keys will be tried first. + Once a substring has been replaced, its new value will not be searched + again. + </para> + <para> + In this case, the keys and the values may have any length, provided that + there is no empty key; additionaly, the length of the return value may + differ from that of <parameter>str</parameter>. + However, this function will be the most efficient when all the keys have the + same size. + </para> </refsect1> <refsect1 role="parameters"> @@ -64,8 +83,8 @@ <term><parameter>replace_pairs</parameter></term> <listitem> <para> - The <parameter>replace_pairs</parameter> parameter may be used as a substitute for - <parameter>to</parameter> and <parameter>from</parameter> in which case it's an + The <parameter>replace_pairs</parameter> parameter may be used instead of + <parameter>to</parameter> and <parameter>from</parameter>, in which case it's an <type>array</type> in the form <literal>array('from' => 'to', ...)</literal>. </para> </listitem> @@ -94,6 +113,8 @@ <programlisting role="php"> <![CDATA[ <?php +//In this form, strtr() does byte-by-byte translation +//Therefore, we are assuming a single-byte encoding here: $addr = strtr($addr, "äåö", "aao"); ?> ]]> @@ -101,20 +122,17 @@ </example> </para> <para> - <function>strtr</function> may be called with only two - arguments. If called with two arguments it behaves in a new way: - <parameter>from</parameter> then has to be an array that contains - string -> string pairs that will be replaced in the source - string. <function>strtr</function> will always look for the - longest possible match first and will *NOT* try to replace stuff - that it has already worked on. + The next example shows the behavior of <function>strtr</function> when + called with only two arguments. Note the preference of the replacements + (<literal>"h"</literal> is not picked because there are longer matches) + and how replaced text was not searched again. </para> <example> <title><function>strtr</function> example with two arguments</title> <programlisting role="php"> <![CDATA[ <?php -$trans = array("hello" => "hi", "hi" => "hello"); +$trans = array("h" => "-", "hello" => "hi", "hi" => "hello"); echo strtr("hi all, I said hello", $trans); ?> ]]> @@ -126,6 +144,31 @@ ]]> </screen> </example> + <para> + The two modes of behavior are substantially different. With three arguments, + <function>strtr</function> will replace bytes; with two, it may replace + longer substrings. + </para> + <example> + <title><function>strtr</function> behavior comparison</title> + <programlisting role="php"> +<![CDATA[ +<?php +echo strtr("baab", "ab", "01"),"\n"; + +$trans = array("ab" => "01"); +echo strtr("baab", $trans); +?> +]]> + </programlisting> + &example.outputs; + <screen> +<![CDATA[ +1001 +ba01 +]]> + </screen> + </example> </refsect1> <refsect1 role="seealso">

« previous php.doc.cvs (#7183) next »