Improve docs of round()

git-svn-id: https://svn.php.net/repository/phpdoc/ja/trunk@350531 c90b9560-bf6c-de11-be94-00142212c4b1

Author: Yoshinari Takaoka

reference/math/functions/round.xml

@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="utf-8"?>
 <!-- $Revision$ -->
-<!-- EN-Revision: 1ef2fdddacc294b73c467162d8430e4590291530 Maintainer: hirokawa Status: ready -->
+<!-- EN-Revision: 23482f94b527c729bcbf2c390e33a7379551e915 Maintainer: hirokawa Status: ready -->
 <!-- CREDITS: takagi,mumumu -->
 <refentry xml:id="function.round" xmlns="http://docbook.org/ns/docbook">
  <refnamediv>
@@ -68,13 +68,17 @@
       </para>
       <para>
        <parameter>precision</parameter> が正の値の場合、
-       丸めは小数点より後ろの桁に対して行われます。
+       <parameter>val</parameter> は
+       小数点以下、有効桁数 <parameter>precision</parameter> 桁に丸められます。
       </para>
       <para>
        <parameter>precision</parameter> が負の場合、
-       丸め処理は小数点より前の桁に対して行われます。
-       <parameter>precision</parameter> の絶対値が
-       桁数以上の場合は、丸めの結果は <literal>0</literal> になります。
+       <parameter>val</parameter> の
+       丸め処理は小数点より前の <parameter>precision</parameter> 桁に対して行われます。
+       つまり、<literal>pow(10, -precision)</literal> の倍数に一番近い値に丸められます。
+       たとえば、<parameter>precision</parameter> が -1 の場合、
+       <parameter>val</parameter> は 10の倍数、
+       <parameter>precision</parameter> が -2 の場合は 100の倍数に近くなるように丸められる、という具合です。
       </para>
      </listitem>
     </varlistentry>
@@ -95,29 +99,33 @@
           <row>
            <entry><constant>PHP_ROUND_HALF_UP</constant></entry>
            <entry>
-            <parameter>val</parameter> が小数点第 <parameter>precision</parameter> 位の値になるように、
-            ゼロから離れる方向に丸めます。1.5 は 2 に、そして -1.5 は -2 になります。
+            端数が半分の場合、
+            <parameter>val</parameter> をゼロから離れる方向に丸めます。
+            1.5 は 2 に、そして -1.5 は -2 になります。
            </entry>
           </row>
           <row>
            <entry><constant>PHP_ROUND_HALF_DOWN</constant></entry>
            <entry>
-            <parameter>val</parameter> が小数点第 <parameter>precision</parameter> 位の値になるように、
-            ゼロに近づく方向に丸めます。1.5 は 1 に、そして -1.5 は -1 になります。
+            端数が半分の場合、
+            <parameter>val</parameter> をゼロに近づく方向に丸めます。
+            1.5 は 1 に、そして -1.5 は -1 になります。
            </entry>
           </row>
           <row>
            <entry><constant>PHP_ROUND_HALF_EVEN</constant></entry>
            <entry>
-            <parameter>val</parameter> が小数点第 <parameter>precision</parameter> 位の値になるように、
-            もっとも近い偶数に丸めます。
+            端数が半分の場合、
+            <parameter>val</parameter> をもっとも近い偶数に丸めます。
+            1.5 や 2.5 は 2 になります。
            </entry>
           </row>
           <row>
            <entry><constant>PHP_ROUND_HALF_ODD</constant></entry>
            <entry>
-            <parameter>val</parameter> が小数点第 <parameter>precision</parameter> 位の値になるように、
-            もっとも近い奇数に丸めます。
+            端数が半分の場合、
+            <parameter>val</parameter> をもっとも近い奇数に丸めます。
+            1.5 は 1 に、そして 2.5 は 3 になります。
            </entry>
           </row>
          </tbody>
@@ -147,10 +155,12 @@ var_dump(round(3.4));
 var_dump(round(3.5));
 var_dump(round(3.6));
 var_dump(round(3.6, 0));
-var_dump(round(1.95583, 2));
-var_dump(round(1241757, -3));
 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>
@@ -161,10 +171,12 @@ float(3)
 float(4)
 float(4)
 float(4)
-float(1.96)
-float(1242000)
 float(5.05)
 float(5.06)
+float(300)
+float(0)
+float(700)
+float(1000)
 ]]>
     </screen>
    </example>
@@ -175,27 +187,27 @@ float(5.06)
     <programlisting role="php">
 <![CDATA[
 <?php
-$number = 1346.21;
+$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));
-var_dump(round($number, -4));
 ?>
 ]]>
     </programlisting>
     &example.outputs;
     <screen role="php">
 <![CDATA[
-float(1346.21)
-float(1346.2)
-float(1346)
-float(1350)
-float(1300)
-float(1000)
+float(135.79)
+float(135.79)
+float(135.8)
+float(136)
+float(140)
+float(100)
 float(0)
 ]]>
     </screen>
@@ -213,6 +225,7 @@ 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));
@@ -229,6 +242,7 @@ float(10)
 float(9)
 float(10)
 float(9)
+
 Rounding modes with 8.5
 float(9)
 float(8)
@@ -246,30 +260,22 @@ float(9)
 <?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.54, 1, PHP_ROUND_HALF_UP));
 var_dump(round(-1.55, 1, PHP_ROUND_HALF_UP));
-var_dump(round(-1.54, 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.54, 1, PHP_ROUND_HALF_DOWN));
 var_dump(round(-1.55, 1, PHP_ROUND_HALF_DOWN));
-var_dump(round(-1.54, 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.54, 1, PHP_ROUND_HALF_EVEN));
 var_dump(round(-1.55, 1, PHP_ROUND_HALF_EVEN));
-var_dump(round(-1.54, 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.54, 1, PHP_ROUND_HALF_ODD));
 var_dump(round(-1.55, 1, PHP_ROUND_HALF_ODD));
-var_dump(round(-1.54, 1, PHP_ROUND_HALF_ODD));
 ?>
 ]]>
     </programlisting>
@@ -278,26 +284,18 @@ var_dump(round(-1.54, 1, PHP_ROUND_HALF_ODD));
 <![CDATA[
 Using PHP_ROUND_HALF_UP with 1 decimal digit precision
 float(1.6)
-float(1.5)
 float(-1.6)
-float(-1.5)
 
 Using PHP_ROUND_HALF_DOWN with 1 decimal digit precision
 float(1.5)
-float(1.5)
-float(-1.5)
 float(-1.5)
 
 Using PHP_ROUND_HALF_EVEN with 1 decimal digit precision
 float(1.6)
-float(1.5)
 float(-1.6)
-float(-1.5)
 
 Using PHP_ROUND_HALF_ODD with 1 decimal digit precision
 float(1.5)
-float(1.5)
-float(-1.5)
 float(-1.5)
 ]]>
     </screen>