number-format.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- EN-Revision: 45042fef652f1b4e904e809fcbfcf31f6c60670b Maintainer: simp Status: ready -->
<!-- Reviewed: no -->
<!-- Credits: sammywg -->
<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>Formatiert eine Zahl mit Tausender-Trennzeichen</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>
   Formatiert eine Zahl mit Tausender-Trennzeichen und optionalen
   Dezimalziffern und verwendet dabei das Kaufmännische Runden (aufrunden ab
   der Hälfte).
  </para>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>num</parameter></term>
     <listitem>
      <para>
       Die zu formatierende Zahl.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>decimals</parameter></term>
     <listitem>
      <para>
       Bestimmt die Anzahl an Nachkommastellen.
       Wenn der Wert <literal>0</literal> ist, wird das Dezimaltrennzeichen
       <parameter>decimal_separator</parameter> im Rückgabewert weggelassen.
       Wenn der Wert negativ ist, wird <parameter>num</parameter> seit
       PHP 8.3.0 auf <parameter>decimals</parameter> signifikante Stellen vor
       dem Dezimaltrennzeichen gerundet.
       Vor PHP 8.3.0 wurden negative Werte ignoriert und genauso behandelt wie
       <literal>0</literal>.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>decimal_separator</parameter></term>
     <listitem>
      <para>
       Bestimmt das Trennzeichen für die Nachkommastellen.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>thousands_separator</parameter></term>
     <listitem>
      <para>
       Bestimmt das Tausendertrennzeichen.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   Eine formatierte Version von <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>
        Behandlung negativer Werte für <parameter>decimals</parameter>
        hinzugefügt.
       </entry>
      </row>
      <row>
       <entry>8.0.0</entry>
       <entry>
        Vor dieser Version akzeptierte <function>number_format</function>
        einen, zwei oder vier Parameter (aber nicht drei).
       </entry>
      </row>
     <row>
       <entry>7.2.0</entry>
       <entry>
        <function>number_format</function> wurde geändert, so dass es nicht
        mehr <literal>-0</literal> zurückgeben kann; zuvor konnte
        <literal>-0</literal> zurückgegeben werden, &zb; wenn
        <parameter>num</parameter> gleich <literal>-0.01</literal> war.
       </entry>
      </row>
     </tbody>
    </tgroup>
   </informaltable>
  </para>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title><function>number_format</function>-Beispiel</title>
    <para>
     Beispielsweise notiert man in Frankreich normalerweise zwei
     Dezimalstellen mit einem Komma (',') als Trennzeichen sowie ein
     Leerzeichen (' ') zur Gruppierung der Tausender. Das folgende Beispiel
     zeigt verschiedene Varianten eine Zahl zu formatieren:
    </para>
    <programlisting role="php">
<![CDATA[
<?php

$number = 1234.56;

// Englische Notation (Standard)
echo number_format($number), PHP_EOL;
// 1,235

// Französische Notation
echo number_format($number, 2, ',', ' '), PHP_EOL;
// 1 234,56

$number = 1234.5678;

// Englische Notation ohne Tausendergruppierung
echo number_format($number, 2, '.', ''), PHP_EOL;
// 1234.57

?>
]]>
    </programlisting>
   </example>
  </para>
  <example>
   <title>Ein negativer Wert für <parameter>decimals</parameter></title>
   <simpara>
    Seit PHP 8.3.0 wird ein negativer Wert für <parameter>decimals</parameter>
    verwendet, um die Anzahl der signifikanten Ziffern vor dem
    Dezimaltrennzeichen zu runden.
   </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="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
-->