number-format.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: ae148826a6830492a51e47f21e1ad4f80373f2a6 Maintainer: yannick Status: ready -->
<!-- Reviewed: yes -->
<refentry xml:id="function.number-format" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
 <refnamediv>
  <refname>number_format</refname>
  <refpurpose>Formate un nombre pour l'affichage</refpurpose>
 </refnamediv>
 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <type>string</type><methodname>number_format</methodname>
   <methodparam><type>float</type><parameter>num</parameter></methodparam>
   <methodparam choice="opt"><type>int</type><parameter>decimals</parameter><initializer>0</initializer></methodparam>
   <methodparam choice="opt"><type class="union"><type>string</type><type>null</type></type><parameter>decimal_separator</parameter><initializer>"."</initializer></methodparam>
   <methodparam choice="opt"><type class="union"><type>string</type><type>null</type></type><parameter>thousands_separator</parameter><initializer>","</initializer></methodparam>
  </methodsynopsis>
  <para>
   Formate un nombre avec les milliers groupés et optionnellement des chiffres décimaux utilisant la règle d'arrondi arrondi au plus proche.
  </para>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>num</parameter></term>
     <listitem>
      <para>
       Le nombre à formater.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>decimals</parameter></term>
     <listitem>
      <para>
       Définit le nombre de chiffres décimales.
       Si <literal>0</literal>, le <parameter>decimal_separator</parameter> est
       omis de la valeur de retour.
       À partir de PHP 8.3.0, lorsque la valeur est négative, <parameter>num</parameter>
       est arrondi à <parameter>decimals</parameter> chiffres significatifs avant
       le point décimal.
       Avant PHP 8.3.0, les valeurs négatives étaient ignorées et traitées de la
       même manière que <literal>0</literal>.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>decimal_separator</parameter></term>
     <listitem>
      <para>
       Définit le séparateur pour le point décimal.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>thousands_separator</parameter></term>
     <listitem>
      <para>
       Définit le séparateur des milliers.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>
 
 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   Une version formatée du nombre <parameter>num</parameter>.
  </para>
 </refsect1>
 
 <refsect1 role="changelog">
  &reftitle.changelog;
  <para>
   <informaltable>
    <tgroup cols="2">
     <thead>
      <row>
       <entry>&Version;</entry>
       <entry>&Description;</entry>
      </row>
     </thead>
     <tbody>
      <row>
       <entry>8.3.0</entry>
       <entry>
        Ajout de la gestion des valeurs négatives pour <parameter>decimals</parameter>.
       </entry>
      </row>
      <row>
       <entry>8.0.0</entry>
       <entry>
        Antérieur à cette version, <function>number_format</function> accepte
        un, deux, ou quatre paramètres (mais pas trois).
       </entry>
      </row>
      <row>
       <entry>7.2.0</entry>
       <entry>
        <function>number_format</function> a été modifié pour ne plus permettre de
        retourner <literal>-0</literal>, précédemment <literal>-0</literal> pouvait
        être retourné pour des cas où <parameter>num</parameter> valait <literal>-0.01</literal>.
       </entry>
      </row>
     </tbody>
    </tgroup>
   </informaltable>
  </para>
  <example>
   <title>Une valeur négative pour <parameter>decimals</parameter></title>
   <simpara>
    À partir de PHP 8.3.0, une valeur négative pour <parameter>decimals</parameter>
    est utilisée pour arrondir le nombre de chiffres significatifs avant le point
    décimal.
   </simpara>
   <programlisting role="php">
<![CDATA[
<?php
$number = "1234.5678";
var_dump(number_format($number, -1));
var_dump(number_format($number, -2));
var_dump(number_format($number, -3));
?>
]]>
   </programlisting>
   &example.outputs;
   <screen>
<![CDATA[
string(5) "1 230"
string(5) "1 200"
string(5) "1 000"
]]>
   </screen>
  </example>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title>Exemple avec <function>number_format</function></title>
    <para>
     En notation française, on utilise généralement deux chiffres
     après la virgule, une virgule comme séparateur décimal, et un
     espace comme séparateur de milliers. L'exemple suivant montre
     comment formater un nombre de différentes façons :
    </para>
    <programlisting role="php">
<![CDATA[
<?php

$number = 1234.56;

// Notation anglaise (par défaut)
$english_format_number = number_format($number);
// 1,235

// Notation française
$nombre_format_francais = number_format($number, 2, ',', ' ');
// 1 234,56

$number = 1234.5678;

// Notation anglaise sans séparateur de milliers
$english_format_number = number_format($number, 2, '.', '');
// 1234.57

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

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