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

<?xml version="1.0" encoding="utf-8"?>
<!-- EN-Revision: 45042fef652f1b4e904e809fcbfcf31f6c60670b Maintainer: PhilDaiguille Status: ready -->
<!-- Reviewed: yes -->
<refentry xml:id="function.strtr" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
 <refnamediv>
  <refname>strtr</refname>
  <refpurpose>Reemplaza caracteres en un string</refpurpose>
 </refnamediv>

 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <type>string</type><methodname>strtr</methodname>
   <methodparam><type>string</type><parameter>string</parameter></methodparam>
   <methodparam><type>string</type><parameter>from</parameter></methodparam>
   <methodparam><type>string</type><parameter>to</parameter></methodparam>
  </methodsynopsis>
  <simpara>Firma alternativa (no soportada con argumentos nombrados):</simpara>
  <methodsynopsis>
   <type>string</type><methodname>strtr</methodname>
   <methodparam><type>string</type><parameter>string</parameter></methodparam>
   <methodparam><type>array</type><parameter>replace_pairs</parameter></methodparam>
  </methodsynopsis>
  <para>
   Si se utilizan tres argumentos, <function>strtr</function> devuelve el string
   <parameter>string</parameter> después de haber reemplazado cada carácter (de un octeto)
   del parámetro <parameter>from</parameter> por su equivalente en el parámetro
   <parameter>to</parameter>, cada ocurrencia de <literal>$from[$n]</literal> es
   reemplazada por <literal>$to[$n]</literal>, donde <literal>$n</literal> es un valor
   válido para cada argumento.
  </para>
  <para>
   Si <parameter>from</parameter> y <parameter>to</parameter> son de
   tamaños diferentes, los caracteres adicionales en uno u otro
   serán ignorados. El tamaño de <parameter>string</parameter> será el mismo que el de
   los valores devueltos.
  </para>
  <para>
   Si solo se utilizan dos argumentos, el segundo debe ser un <type>array</type>
   de la forma <literal>array('from' =&gt; 'to', ...)</literal>. El dato devuelto es
   un <type>string</type> en el que todas las ocurrencias de las claves del array han
   sido reemplazadas por los valores correspondientes. Las claves más largas serán utilizadas primero.
   Una vez que una subcadena es reemplazada, su nuevo valor no será buscado nuevamente.
  </para>
  <para>
   En este caso, las claves y los valores pueden tener cualquier tamaño, asumiendo
   que no hay una clave vacía; así, el tamaño del valor devuelto puede diferir del de
   <parameter>string</parameter>. Sin embargo, esta función será más eficiente cuando todas
   las claves tengan el mismo tamaño.
  </para>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>string</parameter></term>
     <listitem>
      <para>
       El string a procesar.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>from</parameter></term>
     <listitem>
      <para>
       Los caracteres de origen.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>to</parameter></term>
     <listitem>
      <para>
       Los caracteres de reemplazo.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>replace_pairs</parameter></term>
     <listitem>
      <para>
       El parámetro <parameter>replace_pairs</parameter> puede ser utilizado
       en lugar de <parameter>to</parameter> y <parameter>from</parameter>
       y en este caso, será un array en la forma
       <literal>array('from' =&gt; 'to', ...)</literal>.
      </para>
      <para>
       Si <parameter>replace_pairs</parameter> contiene una clave que es un
       <type>string</type> vacío (<literal>""</literal>), el elemento es ignorado;
       a partir de PHP 8.0.0 se genera una <constant>E_WARNING</constant> en este caso.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   Devuelve el string modificado.
  </para>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title>Ejemplo con <function>strtr</function></title>
    <programlisting role="php">
<![CDATA[
<?php
$addr = "The river å";

// Aquí, strtr() reemplaza octeto por octeto, por lo tanto
// se asume aquí codificaciones de un solo octeto:
$addr = strtr($addr, "äåö", "aao");
echo $addr, PHP_EOL;
?>
]]>
    </programlisting>
   </example>
  </para>
  <para>
   El siguiente ejemplo muestra el uso de <function>strtr</function> con
   dos argumentos. Observe la preferencia de los reemplazos (<literal>h</literal> no
   es utilizado porque hay coincidencias más largas) y cómo el texto
   reemplazado no es reutilizado posteriormente.
  </para>
  <example>
   <title>Ejemplo con <function>strtr</function> y 2 argumentos</title>
    <programlisting role="php">
<![CDATA[
<?php
$trans = array("h" => "-", "hello" => "hi", "hi" => "hello");
echo strtr("hi all, I said hello", $trans);
?>
]]>
    </programlisting>
    &example.outputs;
    <screen>
<![CDATA[
hello all, I said hi
]]>
    </screen>
  </example>
  <para>
   Los dos comportamientos son diferentes. Con tres argumentos,
   <function>strtr</function> reemplazará los octetos; con dos, puede
   reemplazar subcadenas más largas.
  </para>
  <example>
   <title>Comparación de comportamiento de <function>strtr</function></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">
  &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
-->