sprintf.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: ec67e42ba8860cf21fb00437cebbc6cf309e7b5d Maintainer: seros Status: ready -->
<!-- Reviewed: no Maintainer: seros -->
<refentry xmlns="http://docbook.org/ns/docbook" xml:id="function.sprintf">
 <refnamediv>
  <refname>sprintf</refname>
  <refpurpose>Devuelve un string formateado</refpurpose>
 </refnamediv>
 
 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <type>string</type><methodname>sprintf</methodname>
   <methodparam><type>string</type><parameter>format</parameter></methodparam>
   <methodparam choice="opt"><type>mixed</type><parameter>args</parameter></methodparam>
   <methodparam choice="opt"><type>mixed</type><parameter>...</parameter></methodparam>
  </methodsynopsis>
  <para>
   Devuelve un string producido según el string de formateo dado por
   <parameter>format</parameter>.
  </para>
 </refsect1>
 
 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>format</parameter></term>
     <listitem>
      <para>
       El string de formateo está compuesto de cero o más directivas:
       caracteres ordinarios (excluyendo <literal>%</literal>) que son
       copiados directamente al resultado, y <emphasis>especificaciones
       de conversión</emphasis>, donde cada una de las cuales da lugar a extraer
       su propio parámetro. Esto se aplica tanto para <function>sprintf</function>
       como para <function>printf</function>.
      </para>
      <para>
       Cada especificación de conversión consiste en un signo de porcentaje 
       (<literal>%</literal>), seguido por uno o más de estos
       elementos, en orden:
       <orderedlist>
        <listitem>
         <simpara>
          Un <emphasis>especificador de signo</emphasis> opcional que fuerza a usar
          un signo (- o +) en un número. Por defecto, sólo el signo - se utiliza
          en un número si es negativo. Esta especificación fuerza números positivos
          para que también tengan adjunto el signo + (agregado en PHP 4.3.0).
         </simpara>
        </listitem>
        <listitem>
         <simpara>
          Un <emphasis>especificador de relleno</emphasis> opcional que
          indica qué carácter se utiliza para rellenar el resultado hasta
          el tamaño justo del string. Este puede ser un carácter de espacio o un 
          <literal>0</literal> (el carácter cero). El valor por defecto es rellenar
          con espacios. Un carácter de relleno alternativo se puede especificar
          prefijándolo con una comilla simple (<literal>'</literal>).
          Ver los ejemplos más adelante.
         </simpara>
        </listitem>
        <listitem>
         <simpara>
          Un <emphasis>especificador de alineación</emphasis> opcional que indica
          si el resultado debe ser alineado a la izquierda o a la derecha.
          El valor por defecto es justificado a la derecha, un carácter
          <literal>-</literal> lo justificará a la izquierda.
         </simpara>
        </listitem>
        <listitem>
         <simpara>
          Un número opcional, un <emphasis>especificador de ancho</emphasis>
          que indica de cuántos caracteres (mínimo) resultará esta
          conversión.
         </simpara>
        </listitem>
        <listitem>
         <simpara>
          Un <emphasis>especificador de precisión</emphasis> opcional en la forma
          de un punto (<literal>.</literal>) seguido de un string opcional de dígitos decimales
          que indica cuántos dígitos decimales deben mostrarse para
          los números de punto flotante. Cuando se utiliza este especificador con un string,
          actúa como un punto de corte, estableciendo un límite máximo de caracteres al
          string. Además, el carácter para empleado cuando se rellena un
          número podría especificarse opcionalmente entre el punto y el
          dígito.
         </simpara>
        </listitem>
        <listitem>
         <para>
          Un <emphasis>especificador de tipo</emphasis> que indica con qué tipo
          deben ser tratados los datos del argumento. Los tipos posibles son: 
          <simplelist>
           <member>
            <literal>%</literal> - un carácter de porcentaje literal. No
            se requiere argumento.
           </member>
           <member>
            <literal>b</literal> - el argumento es tratado como un valor de tipo
            integer y presentado como un número binario.
           </member>
           <member>
            <literal>c</literal> - el argumento es tratado como un valor de tipo
            integer y presentado como el carácter con ese valor
            ASCII.
           </member>
           <member>
            <literal>d</literal> - el argumento es tratado como un valor de tipo
            integer y presentado como un número decimal (con signo).
           </member>
           <member>
            <literal>e</literal> - el argumento es tratado con notación
            científica (e.g. 1.2e+2).
            El especificador de precisión indica el número de dígitos después del
            punto decimal a partir de PHP 5.2.1. En versiones anteriores, se tomó como
            el número de dígitos significativos (menos uno).
           </member>
           <member>
            <literal>E</literal> - como <literal>%e</literal> pero utiliza
            la letra mayúscula (e.g. 1.2E+2).
           </member>
           <member>
            <literal>f</literal> - el argumento es tratado como un valor de tipo
            float y presentado como un número de punto flotante (considerando la configuración regional).
           </member>
           <member>
            <literal>F</literal> - el argumento es tratado como un valor de tipo
            float y presentado como un número de punto flotante (no considerando la configuración regional).
            Disponible desde PHP 4.3.10 y PHP 5.0.3.
           </member>
           <member>
            <literal>g</literal> - lo mismo que <literal>%e</literal> y
            <literal>%f</literal>.
           </member>
           <member>
            <literal>G</literal> - lo mismo que <literal>%E</literal> y
            <literal>%f</literal>.
           </member>
           <member>
            <literal>o</literal> - el argumento es tratado como un valor de tipo
            integer y presentado como un número octal.
           </member>
           <member>
            <literal>s</literal> - el argumento es tratado y
            presentado como un string.
           </member>
           <member>
            <literal>u</literal> - el argumento es tratado como un valor de tipo
            integer y presentado como un número decimal sin signo.
           </member>
           <member>
            <literal>x</literal> - el argumento es tratado como un valor de tipo integer
            y presentado como un número hexadecimal (con las letras
            en minúsculas).
           </member>
           <member>
            <literal>X</literal> - el argumento es tratado como un valor de tipo integer
            y presentado como un número hexadecimal (con las letras
            en mayúsculas).
           </member>
          </simplelist>
         </para>
        </listitem>
       </orderedlist>
      </para>
      <para>
       Las variables serán forzadas por el especificador a un tipo adecuado:
       <table xml:id="sprintf.coercion">
        <title>Manejo de tipos</title>
        <tgroup cols="2">
         <thead>
          <row>
           <entry>Tipo</entry>
           <entry>Especificador</entry>
          </row>
         </thead>
         <tbody>
          <row>
           <entry><literal>string</literal></entry>
           <entry><literal>s</literal></entry>
          </row>
          <row>
           <entry><literal>integer</literal></entry>
           <entry>
            <literal>d</literal>, 
            <literal>u</literal>, 
            <literal>c</literal>,
            <literal>o</literal>,
            <literal>x</literal>,
            <literal>X</literal>,
            <literal>b</literal>
           </entry>
          </row>
          <row>
           <entry><literal>double</literal></entry>
           <entry>
            <literal>g</literal>,
            <literal>G</literal>,
            <literal>e</literal>,
            <literal>E</literal>,
            <literal>f</literal>,
            <literal>F</literal>
           </entry>
          </row>
         </tbody>
        </tgroup>
       </table>
      </para>
      <warning>
       <para>
        Intentar usar una combinación de especificadores de string y ancho con conjuntos de caracteres que requieran más de un byte por carácter podría tener resultados inesperados.
       </para>
      </warning>
      <para>
       El string de formato soporta la numeración/intercambio de argumentos. Aquí está un
       ejemplo:
       <example>
        <title>Intercambio de argumentos</title>
        <programlisting role="php">
<![CDATA[
<?php
$num = 5;
$ubicación = 'árbol';

$formato = 'Hay %d monos en el %s';
echo sprintf($formato, $num, $ubicación);
?>
]]>
        </programlisting>
       </example>
       Esto producirá " Hay 5 monos en el árbol". Pero
       imaginemos que estamos creando un string de formato en un fichero aparte,
       generalmente por que nos gustaría internacionalizarlo,
       reescribiéndolo así:
       <example>
        <title>Intercambio de argumentos</title>
        <programlisting role="php">
<![CDATA[
<?php
$formato = 'El %s contiene %d monos';
echo sprintf($formato, $num, $ubicación);
?>
]]>
        </programlisting>
       </example>
       Ahora tenemos un problema. El orden de los marcadores de posición en el
       string de formato no coincide con el orden de los argumentos en el
       código. Nos gustaría dejar el código tal cual y simplemente indicar
       en el string de formato a cuáles argumentos de los marcadores de posición se refieren.
       Tendríamos que escribir el string de formato de esta forma:
       <example>
        <title>Intercambio de argumentos</title>
        <programlisting role="php">
<![CDATA[
<?php
$formato = 'El %2$s contiene %1$d monos';
echo sprintf($formato, $num, $ubicación);
?>
]]>
        </programlisting>
       </example>
       Un beneficio adicional es que se pueden repetir los marcadores de posición sin
       agregar más argumentos en el código. Por ejemplo:
       <example>
        <title>Intercambio de argumentos</title>
        <programlisting role="php">
<![CDATA[
<?php
$formato = 'El %2$s contiene %1$d monos.
            Es un bonito %2$s con %1$d monos.';
echo sprintf($formato, $num, $ubicación);
?>
]]>
        </programlisting>
       </example>
       Cuando se utiliza el intercambio de argumentos, el <emphasis>especificador de posición</emphasis>
       <literal>n$</literal> debe ir inmediatamente
       después del signo de porcentaje (<literal>%</literal>), antes de cualquier otro
       especificador, tal como se muestra en el ejemplo siguiente.
       <example>
        <title>Especificar un carácter de relleno</title>
        <programlisting role="php">
<![CDATA[
<?php
echo sprintf("%'.9d\n", 123);
echo sprintf("%'.09d\n", 123);
?>
]]>
        </programlisting>
        &example.outputs;
        <screen>
<![CDATA[
......123
000000123
]]>
        </screen>
       </example>
       <example>
        <title>Especificador de posición con otros especificadores</title>
        <programlisting role="php">
<![CDATA[
<?php
$formato = 'El %2$s contiene %1$04d monos';
echo sprintf($formato, $num, $ubicación);
?>
]]>
        </programlisting>
        &example.outputs;
        <screen>
<![CDATA[
 El árbol contiene 0005 monos
]]>
        </screen>
       </example>
      </para>
      <note>
       <para>
        Tratar de utilizar marcadores de posición mayores que
        <constant>PHP_INT_MAX</constant> provocará que
        <function>sprintf</function> genere mensajes de advertencia.
       </para>
      </note>
      <warning>
       <para>
        El especificador de tipo <literal>c</literal> ignora el relleno y el ancho
       </para>
      </warning>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>args</parameter></term>
     <listitem>
      <para>
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>...</parameter></term>
     <listitem>
      <para>
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>
 
 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   Devuelve un string producido de acuerdo con el string de formato
   <parameter>format</parameter>.
  </para>
 </refsect1>
 
 <refsect1 role="examples">
  &reftitle.examples;
  <example>
   <title><function>printf</function>: ejemplos varios</title>
   <programlisting role="php">
<![CDATA[
<?php
$n =  43951789;
$u = -43951789;
$c = 65; // ASCII 65 es 'A'

// observar el doble %%, esto muestra un carácter '%' literal
printf("%%b = '%b'\n", $n); // representación binaria
printf("%%c = '%c'\n", $c); // muestra el carácter ascii, igual que la función chr()
printf("%%d = '%d'\n", $n); // representación estándar de un entero
printf("%%e = '%e'\n", $n); // notación científica
printf("%%u = '%u'\n", $n); // representación sin signo de un entero positivo
printf("%%u = '%u'\n", $u); // representación sin signo de un entero negativo
printf("%%f = '%f'\n", $n); // representación de punto flotante
printf("%%o = '%o'\n", $n); // representación octal
printf("%%s = '%s'\n", $n); // representación en una cadena
printf("%%x = '%x'\n", $n); // representación hexadecimal (minúsculas)
printf("%%X = '%X'\n", $n); // representación hexadecimal (mayúsculas)

printf("%%+d = '%+d'\n", $n); // especificador de signo sobre un entero positivo
printf("%%+d = '%+d'\n", $u); // especificador de signo sobre un entero negativo
?>
]]>
   </programlisting>
   &example.outputs;
   <screen>
<![CDATA[
%b = '10100111101010011010101101'
%c = 'A'
%d = '43951789'
%e = '4.39518e+7'
%u = '43951789'
%u = '4251015507'
%f = '43951789.000000'
%o = '247523255'
%s = '43951789'
%x = '29ea6ad'
%X = '29EA6AD'
%+d = '+43951789'
%+d = '-43951789'
]]>
   </screen>
  </example>
  <example>
   <title><function>printf</function>: especificadores de string</title>
   <programlisting role="php">
<![CDATA[
<?php
$s = 'mono';
$t = 'muchos monos';

printf("[%s]\n",      $s); // salida estándar de string 
printf("[%10s]\n",    $s); // justificación a la derecha con espacios
printf("[%-10s]\n",   $s); // justificación a la izquierda con espacios
printf("[%010s]\n",   $s); // rellenado con ceros también funciona con strings
printf("[%'#10s]\n",  $s); // utiliza el carácter de relleno personalizado '#'
printf("[%10.10s]\n", $t); // justificación a la izquierda pero con un corte a los 10 caracteres
?>
]]>
   </programlisting>
   &example.outputs;
   <screen>
<![CDATA[
[mono]
[      mono]
[mono      ]
[000000mono]
[######mono]
[muchos mon]
]]>
   </screen>
  </example>
  <example>
   <title><function>sprintf</function>: valores de tipo integer rellenados con ceros</title>
   <programlisting role="php">
<![CDATA[
<?php
$fecha_iso = sprintf("%04d-%02d-%02d", $año, $mes, $día);
?>
]]>
   </programlisting>
  </example>
  <example>
   <title><function>sprintf</function>: formato de moneda</title>
   <programlisting role="php">
<![CDATA[
<?php
$dinero1 = 68.75;
$dinero2 = 54.35;
$dinero = $dinero1 + $dinero2;
// echo $dinero producirá "123.1";
$formateado = sprintf("%01.2f", $dinero);
// echo $formateado producirá "123.10"
?>
]]>
   </programlisting>
  </example>
  <example>
   <title><function>sprintf</function>: notación científica</title>
   <programlisting role="php">
<![CDATA[
<?php
$número = 362525200;

echo sprintf("%.3e", $número); // produce 3.625e+8
?>
]]>
   </programlisting>
  </example>
 </refsect1>
 
 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   <simplelist>
    <member><function>printf</function></member>
    <member><function>sscanf</function></member>
    <member><function>fscanf</function></member>
    <member><function>vsprintf</function></member>
    <member><function>number_format</function></member>
    <member><function>date</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
-->