round.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: 15b93836d93f01ea6d90a68cacf04ce0d9fb8eff Maintainer: hirokawa Status: ready -->
<!-- CREDITS: takagi,mumumu -->
<refentry xml:id="function.round" xmlns="http://docbook.org/ns/docbook">
 <refnamediv>
  <refname>round</refname>
  <refpurpose>浮動小数点数を丸める</refpurpose>
 </refnamediv>
 <refsect1 role="description">
  &reftitle.description;
   <methodsynopsis>
   <type>float</type><methodname>round</methodname>
   <methodparam><type class="union"><type>int</type><type>float</type></type><parameter>num</parameter></methodparam>
   <methodparam choice="opt"><type>int</type><parameter>precision</parameter><initializer>0</initializer></methodparam>
   <methodparam choice="opt"><type class="union"><type>int</type><type>RoundingMode</type></type><parameter>mode</parameter><initializer>RoundingMode::HalfAwayFromZero</initializer></methodparam>
  </methodsynopsis>
  <para>
   <parameter>num</parameter> を、指定した
   <parameter>precision</parameter>(小数点以下の桁数)に丸めた値を
   返します。<parameter>precision</parameter> を負またはゼロ(デフォルト)
   とすることも可能です。
  </para>
  <!-- It's not true
  <para>
   <caution>
    <simpara>
     When rounding on exact halves <function>round</function> rounds down on
     evens and up on odds.  If you want to always force it in one direction
     on a .5 (or .05 in your case) add or substract a tiny fuzz factor.  The
     reason behind rounding half the values down and the other half up is to
     avoid the classical banking problem where if you always rounded down
     you would be stealing money from your customers, or if you always
     rounded up you would end up over time losing money.  By averaging it
     out through evens and odds you statistically break even.
    </simpara>
   </caution>
  </para>
  -->
 </refsect1>
 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>num</parameter></term>
     <listitem>
      <para>
       丸める値。
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>precision</parameter></term>
     <listitem>
      <para>
       オプションで指定する、丸める桁数。
      </para>
      <para>
       <parameter>precision</parameter> が正の値の場合、
       <parameter>num</parameter> は
       小数点以下、有効桁数 <parameter>precision</parameter> 桁に丸められます。
      </para>
      <para>
       <parameter>precision</parameter> が負の場合、
       <parameter>num</parameter> の
       丸め処理は小数点より前の <parameter>precision</parameter> 桁に対して行われます。
       つまり、一番近い <code>pow(10, -$precision)</code> の倍数に丸められます。
       たとえば、<parameter>precision</parameter> が -1 の場合、
       <parameter>num</parameter> は 一番近い10の倍数に、
       <parameter>precision</parameter> が -2 の場合は 一番近い100の倍数に丸められる、という具合です。
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>mode</parameter></term>
     <listitem>
      <para>
       <enumname>RoundingMode</enumname> もしくは次の定数のいずれかを使って、丸めのモードを指定します。
       <informaltable>
        <tgroup cols="2">
         <thead>
          <row>
           <entry>&Constants;</entry>
           <entry>&Description;</entry>
          </row>
         </thead>
         <tbody>
          <row>
           <entry><constant>PHP_ROUND_HALF_UP</constant></entry>
           <entry>
            端数が5(半分)の場合、
            <parameter>num</parameter> をゼロから離れる方向に丸めます。
            1.5 は 2 に、そして -1.5 は -2 になります。
           </entry>
          </row>
          <row>
           <entry><constant>PHP_ROUND_HALF_DOWN</constant></entry>
           <entry>
            端数が5(半分)の場合、
            <parameter>num</parameter> をゼロに近づく方向に丸めます。
            1.5 は 1 に、そして -1.5 は -1 になります。
           </entry>
          </row>
          <row>
           <entry><constant>PHP_ROUND_HALF_EVEN</constant></entry>
           <entry>
            端数が5(半分)の場合、
            <parameter>num</parameter> をもっとも近い偶数に丸めます。
            1.5 や 2.5 は 2 になります。
           </entry>
          </row>
          <row>
           <entry><constant>PHP_ROUND_HALF_ODD</constant></entry>
           <entry>
            端数が5(半分)の場合、
            <parameter>num</parameter> をもっとも近い奇数に丸めます。
            1.5 は 1 に、そして 2.5 は 3 になります。
           </entry>
          </row>
         </tbody>
        </tgroup>
       </informaltable>
       ただし、新規に追加されたいくつかのモードは <enumname>RoundingMode</enumname> にのみ存在します。
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>
 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   <parameter>precision</parameter> で与えられた精度に丸められた値を &float; で返します。
  </para>
 </refsect1>

 <refsect1 role="errors">
  &reftitle.errors;
  <simpara>
   この関数は、無効な <parameter>mode</parameter> が指定された場合に <exceptionname>ValueError</exceptionname> をスローします。
   PHP 8.4.0 より前では、、エラーにはならずに <constant>PHP_ROUND_HALF_UP</constant> を使用していました。
  </simpara>
 </refsect1>

 <refsect1 role="changelog">
  &reftitle.changelog;
  <informaltable>
   <tgroup cols="2">
    <thead>
     <row>
      <entry>&Version;</entry>
      <entry>&Description;</entry>
     </row>
    </thead>
    <tbody>
     <row>
      <entry>8.4.0</entry>
      <entry>
       新しい4つのモードが追加されました。
      </entry>
     </row>
     <row>
      <entry>8.4.0</entry>
      <entry>
       無効な <parameter>mode</parameter> が指定された場合に <exceptionname>ValueError</exceptionname> をスローするようになりました。
      </entry>
     </row>
     <row>
      <entry>8.0.0</entry>
      <entry>
       <parameter>num</parameter> は、
       数値への変換をサポートした内部オブジェクトを受け入れなくなりました。
      </entry>
     </row>
    </tbody>
   </tgroup>
  </informaltable>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title><function>round</function> の例</title>
    <programlisting role="php">
<![CDATA[
<?php
var_dump(round(3.4));
var_dump(round(3.5));
var_dump(round(3.6));
var_dump(round(3.6, 0));
var_dump(round(5.045, 2));
var_dump(round(5.055, 2));
var_dump(round(345, -2));
var_dump(round(345, -3));
var_dump(round(678, -2));
var_dump(round(678, -3));
?>
]]>
    </programlisting>
    &example.outputs;
    <screen role="php">
<![CDATA[
float(3)
float(4)
float(4)
float(4)
float(5.05)
float(5.06)
float(300)
float(0)
float(700)
float(1000)
]]>
    </screen>
   </example>
  </para>
  <para>
   <example>
    <title><parameter>precision</parameter> が、どうfloatの値に影響するか</title>
    <programlisting role="php">
<![CDATA[
<?php
$number = 135.79;

var_dump(round($number, 3));
var_dump(round($number, 2));
var_dump(round($number, 1));
var_dump(round($number, 0));
var_dump(round($number, -1));
var_dump(round($number, -2));
var_dump(round($number, -3));
?>
]]>
    </programlisting>
    &example.outputs;
    <screen role="php">
<![CDATA[
float(135.79)
float(135.79)
float(135.8)
float(136)
float(140)
float(100)
float(0)
]]>
    </screen>
   </example>
  </para>
  <para>
   <example>
    <title><parameter>mode</parameter> の例</title>
    <programlisting role="php">
<![CDATA[
<?php
echo 'Rounding modes with 9.5' . PHP_EOL;
var_dump(round(9.5, 0, PHP_ROUND_HALF_UP));
var_dump(round(9.5, 0, PHP_ROUND_HALF_DOWN));
var_dump(round(9.5, 0, PHP_ROUND_HALF_EVEN));
var_dump(round(9.5, 0, PHP_ROUND_HALF_ODD));

echo PHP_EOL;
echo 'Rounding modes with 8.5' . PHP_EOL;
var_dump(round(8.5, 0, PHP_ROUND_HALF_UP));
var_dump(round(8.5, 0, PHP_ROUND_HALF_DOWN));
var_dump(round(8.5, 0, PHP_ROUND_HALF_EVEN));
var_dump(round(8.5, 0, PHP_ROUND_HALF_ODD));
?>
]]>
    </programlisting>
    &example.outputs;
    <screen role="php">
<![CDATA[
Rounding modes with 9.5
float(10)
float(9)
float(10)
float(9)

Rounding modes with 8.5
float(9)
float(8)
float(8)
float(9)
]]>
    </screen>
   </example>
  </para>
  <para>
   <example>
    <title>桁数を指定した <parameter>mode</parameter> の例</title>
    <programlisting role="php">
<![CDATA[
<?php
echo 'Using PHP_ROUND_HALF_UP with 1 decimal digit precision' . PHP_EOL;
var_dump(round( 1.55, 1, PHP_ROUND_HALF_UP));
var_dump(round(-1.55, 1, PHP_ROUND_HALF_UP));

echo PHP_EOL;
echo 'Using PHP_ROUND_HALF_DOWN with 1 decimal digit precision' . PHP_EOL;
var_dump(round( 1.55, 1, PHP_ROUND_HALF_DOWN));
var_dump(round(-1.55, 1, PHP_ROUND_HALF_DOWN));

echo PHP_EOL;
echo 'Using PHP_ROUND_HALF_EVEN with 1 decimal digit precision' . PHP_EOL;
var_dump(round( 1.55, 1, PHP_ROUND_HALF_EVEN));
var_dump(round(-1.55, 1, PHP_ROUND_HALF_EVEN));

echo PHP_EOL;
echo 'Using PHP_ROUND_HALF_ODD with 1 decimal digit precision' . PHP_EOL;
var_dump(round( 1.55, 1, PHP_ROUND_HALF_ODD));
var_dump(round(-1.55, 1, PHP_ROUND_HALF_ODD));
?>
]]>
    </programlisting>
    &example.outputs;
    <screen role="php">
<![CDATA[
Using PHP_ROUND_HALF_UP with 1 decimal digit precision
float(1.6)
float(-1.6)

Using PHP_ROUND_HALF_DOWN with 1 decimal digit precision
float(1.5)
float(-1.5)

Using PHP_ROUND_HALF_EVEN with 1 decimal digit precision
float(1.6)
float(-1.6)

Using PHP_ROUND_HALF_ODD with 1 decimal digit precision
float(1.5)
float(-1.5)
]]>
    </screen>
   </example>
  <example>
   <title><enumname>RoundingMode</enumname> を使用した例</title>
   <programlisting role="php">
<![CDATA[
<?php
foreach (RoundingMode::cases() as $mode) {
    foreach ([
        8.5,
        9.5,
        -3.5,
    ] as $number) {
        printf("%-17s: %+.17g -> %+.17g\n", $mode->name, $number, round($number, 0, $mode));
    }
    echo "\n";
}
?>
]]>
   </programlisting>
   &example.outputs;
   <screen role="php">
<![CDATA[
HalfAwayFromZero : +8.5 -> +9
HalfAwayFromZero : +9.5 -> +10
HalfAwayFromZero : -3.5 -> -4

HalfTowardsZero  : +8.5 -> +8
HalfTowardsZero  : +9.5 -> +9
HalfTowardsZero  : -3.5 -> -3

HalfEven         : +8.5 -> +8
HalfEven         : +9.5 -> +10
HalfEven         : -3.5 -> -4

HalfOdd          : +8.5 -> +9
HalfOdd          : +9.5 -> +9
HalfOdd          : -3.5 -> -3

TowardsZero      : +8.5 -> +8
TowardsZero      : +9.5 -> +9
TowardsZero      : -3.5 -> -3

AwayFromZero     : +8.5 -> +9
AwayFromZero     : +9.5 -> +10
AwayFromZero     : -3.5 -> -4

NegativeInfinity : +8.5 -> +8
NegativeInfinity : +9.5 -> +9
NegativeInfinity : -3.5 -> -4

PositiveInfinity : +8.5 -> +9
PositiveInfinity : +9.5 -> +10
PositiveInfinity : -3.5 -> -3
]]>
   </screen>
  </example>
  </para>
 </refsect1>

 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   <simplelist>
    <member><function>ceil</function></member>
    <member><function>floor</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
-->