archived-doc-es/reference/strings/functions/money-format.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: 96c9d88bad9a7d7d44bfb7f26c226df7ee9ddf26 Maintainer: jpberdejo Status: ready -->
<refentry xmlns="http://docbook.org/ns/docbook" xml:id="function.money-format">
 <refnamediv>
  <refname>money_format</refname>
  <refpurpose>Da formato a un número como un string de moneda</refpurpose>
 </refnamediv>
 
 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <type>string</type><methodname>money_format</methodname>
   <methodparam><type>string</type><parameter>format</parameter></methodparam>
   <methodparam><type>float</type><parameter>number</parameter></methodparam>
  </methodsynopsis>
  <para>
   <function>money_format</function> devuelve una versión de 
   <parameter>number</parameter> con formato. Esta función se ajusta a la función
   <function>strfmon</function> de la librería de C, con la diferencia de que
   esta aplicación convierte sólo un número a la vez.
  </para>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>format</parameter></term>
     <listitem>
      <para>
       La especificación del formato se compone de la siguiente secuencia:
       <itemizedlist>
        <listitem><para>un caracter <literal>%</literal></para></listitem>
        <listitem><para>indicadores opcionales</para></listitem>
        <listitem><para>ancho de campo opcional</para></listitem>
        <listitem><para>precisión a la izquierda opcional</para></listitem>
        <listitem><para>precisión a la derecha opcional</para></listitem>
        <listitem><para>un caracter de conversión obligatorio</para></listitem>
       </itemizedlist>
      </para>
      <formalpara>
       <title>Indicadores</title>
       <para>
       Uno o más de los siguientes indicadores opcionales pueden ser utilizados:
        <variablelist>
         <varlistentry>
          <term><literal>=</literal><replaceable>f</replaceable></term>
          <listitem>
           <para>
            El caracter <literal>=</literal> seguido de un caracter <replaceable>f</replaceable>
            (byte único) que se utilizará como el caracter de relleno numérico.
            El carácter de relleno por defecto es el espacio.
           </para>
          </listitem>
         </varlistentry>
         <varlistentry>
          <term><literal>^</literal></term>
          <listitem>
           <para>
            Deshabilita el uso de caracteres de agrupamiento (según la definición
            de la configuración regional actual).
           </para>
          </listitem>
         </varlistentry>
         <varlistentry>
          <term><literal>+</literal> o <literal>(</literal></term>
          <listitem>
           <para>
            Especifica el estilo de formato para los números positivos y negativos.
            Si se utiliza <literal>+</literal>, el equivalente de la configuración regional para
            <literal>+</literal> y <literal>-</literal> será usado. Si se utiliza
            <literal>(</literal>, las cantidades negativas serán encerradas entre
            paréntesis. Si no se da ninguna especificación, el valor por defecto es
            <literal>+</literal>.
           </para>
          </listitem>
         </varlistentry>
         <varlistentry>
          <term><literal>!</literal></term>
          <listitem>
           <para>
            Suprime el símbolo de moneda del string producido.
           </para>
          </listitem>
         </varlistentry>
         <varlistentry>
          <term><literal>-</literal></term>
          <listitem>
           <para>
            Si está presente, hará todos los campos justificados a la izquierda (con relleno a la
            derecha), contrario al valor por defecto que es para que los campos se
            justifiquen a la derecha (con relleno a la izquierda).
           </para>
          </listitem>
         </varlistentry>
        </variablelist>
       </para>
      </formalpara>
      <formalpara>
       <title>Ancho de campo</title>
       <para>
        <variablelist>
         <varlistentry>
          <term><replaceable>w</replaceable></term>
          <listitem>
           <para>
            Un string de dígito decimal que especifica un ancho mínimo de campo. El campo será
            justificado a la derecha a menos que el indicador <literal>-</literal> sea utilizado.
            El valor por defecto es 0 (cero).
           </para>
          </listitem>
         </varlistentry>
        </variablelist>
       </para>
      </formalpara>
      <formalpara>
       <title>Precisión a la izquierda</title>
       <para>
        <variablelist>
         <varlistentry>
          <term><literal>#</literal><replaceable>n</replaceable></term>
          <listitem>
           <para>
            El número máximo de dígitos (<replaceable>n</replaceable>) que se espera
            a la izquierda del caracter decimal (por ejemplo, el punto decimal). Es
            utilizado generalmente para mantener la salida con formato alineada en las mismas columnas,
            usando el caracter de relleno si el número de dígitos sea menor que
            <replaceable>n</replaceable>. Si el número de dígitos real es
            mayor que <replaceable>n</replaceable>, entonces esta especificación es
            ignorada.
           </para>
           <para>
            Si la agrupación no ha sido suprimida mediante el indicador <literal>^</literal>,
            los separadores de agrupamiento serán insertados antes de que los caracteres de
            relleno (si los hay) sean agregados. Los separadores de agrupamiento no se
            aplicarán a los caracteres de relleno, aunque el carácter de relleno sea un dígito.
           </para>
           <para>
            Para asegurar la alineación, cualquier caracter que aparezca antes o después del
            número en la salida con formato, tales como símbolos de moneda o de signo,
            son rellenados cuando sea necesario con caracteres de espacio para hacer sus formatos
            positivos y negativos de una longitud igual.
           </para>
          </listitem>
         </varlistentry>
        </variablelist>
       </para>
      </formalpara>
      <formalpara>
       <title>
        Precisión a la derecha
       </title>
       <para>
        <variablelist>
         <varlistentry>
          <term><literal>.</literal><replaceable>p</replaceable></term>
          <listitem>
           <para>
            Un punto seguido por el número de dígitos
            (<replaceable>p</replaceable>) después del carácter decimal. Si el
            valor de <replaceable>p</replaceable> es 0 (cero), el carácter
            decimal y los dígitos a su derecha serán omitidos. Si no se incluye
            la precisión al la derecha, el valor por defecto será dictado por la configuración
            regional actual en uso. La cantidad que se está formateando se redondea al número
            especificado de dígitos antes de formatearla.
           </para>
          </listitem>
         </varlistentry>
        </variablelist>
       </para>
      </formalpara>
      <formalpara>
       <title>
        Conversion characters
       </title>
       <para>
        <variablelist>
         <varlistentry>
          <term><literal>i</literal></term>
          <listitem>
           <para>
            El número se formatea de acuerdo al formato internacional de moneda
            de la configuración regional (por ejemplo, para la configuración regional de EE.UU.: USD $ 1,234.56).
           </para>
          </listitem>
         </varlistentry>
         <varlistentry>
          <term><literal>n</literal></term>
          <listitem>
           <para>
            El número se formatea de acuerdo al formato nacional de moneda de
            la configuración regional (por ejemplo, para la configuración regional de_DE: EU1.234,56).
           </para>
          </listitem>
         </varlistentry>
         <varlistentry>
          <term><literal>%</literal></term>
          <listitem>
           <para>
            Devuelve el caracter <literal>%</literal>.
           </para>
          </listitem>
         </varlistentry>
        </variablelist>
       </para>
      </formalpara>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>number</parameter></term>
     <listitem>
      <para>
       El número a ser formateado.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   Devuelve el string con formato. Los caracteres antes y después del string 
   de formato se devolverán sin cambios.
   Un <parameter>number</parameter> no numérico causa que se devuelva &null; y
   se emite un <constant>E_WARNING</constant>.
  </para>
 </refsect1>

 <refsect1 role="notes">
  &reftitle.notes;
  <note>
   <para>
    La función <function>money_format</function> sólo está definida si
    el sistema tiene capacidad strfmon. Por ejemplo, Windows no lo hace,
    así que <function>money_format</function> no está definido en Windows.
   </para>
  </note>
  <note>
   <para>
    La categoría <constant>LC_MONETARY</constant> de la configuración regional,
    afecta el comportamiento de esta función. Utilizar <function>setlocale</function>
    para establecer la configuración regional predeterminada apropiada antes de usar esta función.
   </para>
  </note>   
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title>Ejemplos de <function>money_format</function></title>
    <para>
     Se utilizan diferentes configuraciones regionales y especificaciones de formato para
     ilustrar el uso de esta función.
    </para>
    <programlisting role="php">
<![CDATA[
<?php

$number = 1234.56;

// muestra el formato internacional para la configuración regional en_US
setlocale(LC_MONETARY, 'en_US');
echo money_format('%i', $number) . "\n";
// USD 1,234.56

// formato nacional italiano con 2 decimales`
setlocale(LC_MONETARY, 'it_IT');
echo money_format('%.2n', $number) . "\n";
// Eu 1.234,56

// utilizando un número negativo
$number = -1234.5672;

// formato nacional US, utilizando () para los números negativos
// y 10 dígitos de precisión a la izquierda
setlocale(LC_MONETARY, 'en_US');
echo money_format('%(#10n', $number) . "\n";
// ($        1,234.57)

// formato similar que el anterior, agregando el uso de 2 dígitos de precisión
// a la derecha y '*' como caracter de relleno
echo money_format('%=*(#10.2n', $number) . "\n";
// ($********1,234.57)

// justificado a la izquierda, con 14 posiciones de ancho, 8 dígitos de
// precisión a la izquierda, 2 de precisión a la derecha, sin caracter de agrupamiento
// y utilizando el formato internacional para la configuración regional de_DE.
setlocale(LC_MONETARY, 'de_DE');
echo money_format('%=*^-14#8.2i', 1234.56) . "\n";
// Eu 1234,56****

// añadir un poco de propaganda antes y después los especificación de conversión
setlocale(LC_MONETARY, 'en_GB');
$fmt = 'The final value is %i (after a 10%% discount)';
echo money_format($fmt, 1234.56) . "\n";
// The final value is  GBP 1,234.56 (after a 10% discount)

?>
]]>
    </programlisting>
   </example>
  </para>
 </refsect1>

 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   <simplelist>
    <member><function>setlocale</function></member>
    <member><function>sscanf</function></member>
    <member><function>sprintf</function></member>
    <member><function>printf</function></member>
    <member><function>number_format</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
-->