archived-doc-es/reference/strings/functions/strtr.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: 14af302c9c0e561fa6f9cdd956268758ba9a89c5 Maintainer: seros Status: ready -->
<!-- Reviewed: yes Maintainer: seros -->
<refentry xmlns="http://docbook.org/ns/docbook" xml:id="function.strtr" xmlns:xlink="http://www.w3.org/1999/xlink">
 <refnamediv>
  <refname>strtr</refname>
  <refpurpose>Convierte caracteres o reemplaza substrings</refpurpose>
 </refnamediv>
 
 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <type>string</type><methodname>strtr</methodname>
   <methodparam><type>string</type><parameter>str</parameter></methodparam>
   <methodparam><type>string</type><parameter>from</parameter></methodparam>
   <methodparam><type>string</type><parameter>to</parameter></methodparam>
  </methodsynopsis>
  <methodsynopsis>
   <type>string</type><methodname>strtr</methodname>
   <methodparam><type>string</type><parameter>str</parameter></methodparam>
   <methodparam><type>array</type><parameter>replace_pairs</parameter></methodparam>
  </methodsynopsis>
  <para>
   Si se dan tres argumentos, esta función devuelve una copia de
   <parameter>str</parameter>, donde todas las apariciones de cada carácter
   (byte simple) en <parameter>from</parameter> han sido convertidas al
   carácter correspondiente en <parameter>to</parameter>, es decir, todas
   las apariciones de <literal>$from[$n]</literal> han sido reemplazadas con
   <literal>$to[$n]</literal>, donde <literal>$n</literal> es un índice
   válido en ambos argumentos.
  </para>
  <para> 
   Si <parameter>from</parameter> y <parameter>to</parameter> tienen
   distinta logitud, se ignoran los caracteres extra del string
   más largo. La longitud de <parameter>str</parameter> será la misma
   que la del valor devuelto.
  </para>
  <para>
   Si se dan dos argumentos, el segundo debería ser un <type>array</type> en la
   forma <literal>array('from' => 'to', ...)</literal>. El valor devuelto es
   un <type>string</type> donde todas las apariciones de las claves del array han sido
   reemplazadas por los valores correspondientes. Las claves más largas se probarán primero.
   Una vez un substring ha sido reemplazado, su nuevo valor no se buscará
   de nuevo.
  </para>
  <para>
   En este caso, las claves y los valores pueden tener cualquier longitud, siempre que
   no haya claves vacías; además, la longitud del valor devuelto podría
   diferir de la de <parameter>str</parameter>.
   Sin embargo, esta función será la más eficiente cuando todas las claves tienen el
   mismo tamaño.
  </para>
 </refsect1>
 
 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>string</parameter></term>
     <listitem>
      <para>
       El <type>string</type> a convertir.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>from</parameter></term>
     <listitem>
      <para>
       El <type>string</type> a convertir a <parameter>to</parameter>.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>to</parameter></term>
     <listitem>
      <para>
       El <type>string</type> que reemplaza a <parameter>from</parameter>.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>replace_pairs</parameter></term>
     <listitem>
      <para>
       El parámetro <parameter>replace_pairs</parameter> se podría usar en lugar de
       <parameter>to</parameter> y <parameter>from</parameter>, en cuyo caso sería un
       <type>array</type> en la forma <literal>array('from' => 'to', ...)</literal>.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>
 
 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   Devuelve el <type>string</type> convertido.
  </para>
  <para>
   Si <parameter>replace_pairs</parameter> contiene una clave que
   es un <type>string</type> vacío (<literal>""</literal>),
   devolverá &false;. Si <parameter>str</parameter> no es un escalar,
   no será convertido a un string, se emitirá una advertencia y
   devolverá &null;. 
  </para>
 </refsect1>
 
 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title>Ejemplo de <function>strtr</function></title>
    <programlisting role="php">
<![CDATA[
<?php
//De esta forma, strtr() hace una conversión byte a byte
//Por lo tanto, aquí se asume una codificación de un solo byte:
$addr = strtr($addr, "äåö", "aao");
?>
]]>
    </programlisting>
   </example>
  </para>
  <para>
   El siguiente ejemplo muestra el comportamiento de <function>strtr</function> cuando
   se llama con sólo dos argumentos. Observe la preferencia de los reemplazos
   (<literal>"h"</literal> no se toma porque hay coincidencias más largas)
   y cómo el texto remplazado no se busca de nuevo.
  </para>
  <example>
   <title>Ejemplo de <function>strtr</function> con dos argumentos</title>
   <programlisting role="php">
<![CDATA[
<?php
$conv = array("h" => "-", "hola" => "hey", "hey" => "hola");
echo strtr("hey, dije hola", $conv);
?>
]]>
   </programlisting>
   &example.outputs;
   <screen>
<![CDATA[
hola, dije hey
]]>
   </screen>
  </example>
  <para>
   Los dos modos de comportamiento son muy diferentes. Con tres argumentos,
   <function>strtr</function> reemplazará bytes; con dos, podría reemplazar
   substrings más largos.
  </para>
  <example>
   <title>Comparación del comportamiento de <function>strtr</function></title>
   <programlisting role="php">
<![CDATA[
<?php
echo strtr("baab", "ab", "01"),"\n";

$conv = array("ab" => "01");
echo strtr("baab", $conv);
?>
]]>
   </programlisting>
   &example.outputs;
   <screen>
<![CDATA[
1001
ba01
]]>
   </screen>
  </example>
 </refsect1>
 
 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   <simplelist>
    <member><function>str_replace</function></member>
    <member><function>preg_replace</function></member>
   </simplelist>
  </para>
 </refsect1>
</refentry>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->