From ef12785e5aa3ad82b079d0103c941470003cc970 Mon Sep 17 00:00:00 2001
From: Sherif Ramadan <googleguy@php.net>
Date: Sun, 2 Dec 2012 07:17:13 +0000
Subject: [PATCH] Added description for mode constants and an example to
 clarify further on the behavior of the different modes. Fixes bug #63568.

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@328606 c90b9560-bf6c-de11-be94-00142212c4b1
---
 reference/math/functions/round.xml | 79 ++++++++++++++++++++++++++++--
 1 file changed, 74 insertions(+), 5 deletions(-)

diff --git a/reference/math/functions/round.xml b/reference/math/functions/round.xml
index e9743a9203..bed0ef67d8 100644
--- a/reference/math/functions/round.xml
+++ b/reference/math/functions/round.xml
@@ -69,10 +69,47 @@
      <term><parameter>mode</parameter></term>
      <listitem>
       <para>
-       One of <constant>PHP_ROUND_HALF_UP</constant>,
-       <constant>PHP_ROUND_HALF_DOWN</constant>,
-       <constant>PHP_ROUND_HALF_EVEN</constant>, or
-       <constant>PHP_ROUND_HALF_ODD</constant>.
+       Use one of the following constants to specify the mode in which rounding occurs.
+       <informaltable>
+        <tgroup cols="2">
+         <thead>
+          <row>
+           <entry>Constant</entry>
+           <entry>&Description;</entry>
+          </row>
+         </thead>
+         <tbody>
+          <row>
+           <entry><constant>PHP_ROUND_HALF_UP</constant></entry>
+           <entry>
+            Round <parameter>val</parameter> up to <parameter>precision</parameter> decimal places
+            away from zero, when it is half way there. Making 1.5 into 2 and -1.5 into -2.
+           </entry>
+          </row>
+          <row>
+           <entry><constant>PHP_ROUND_HALF_DOWN</constant></entry>
+           <entry>
+            Round <parameter>val</parameter> down to <parameter>precision</parameter> decimal places
+            towards zero, when it is half way there. Making 1.5 into 2 and -1.5 into -2.
+           </entry>
+          </row>
+          <row>
+           <entry><constant>PHP_ROUND_HALF_EVEN</constant></entry>
+           <entry>
+            Round <parameter>val</parameter> to <parameter>precision</parameter> decimal places
+            towards the next even value.
+           </entry>
+          </row>
+          <row>
+           <entry><constant>PHP_ROUND_HALF_ODD</constant></entry>
+           <entry>
+            Round <parameter>val</parameter> to <parameter>precision</parameter> decimal places
+            towards the next odd value.      
+           </entry>
+          </row>
+         </tbody>
+        </tgroup>
+       </informaltable>
       </para>
      </listitem>
     </varlistentry>
@@ -122,6 +159,38 @@ echo round(8.5, 0, PHP_ROUND_HALF_DOWN); // 8
 echo round(8.5, 0, PHP_ROUND_HALF_EVEN); // 8
 echo round(8.5, 0, PHP_ROUND_HALF_ODD);  // 9
 ?>
+]]>
+    </programlisting>
+   </example>
+   <example>
+    <title><parameter>mode with precision</parameter> examples</title>
+    <programlisting role="php">
+<![CDATA[
+<?php
+/* Using PHP_ROUND_HALF_UP with 1 decimal digit precision */
+echo round( 1.55, 1, PHP_ROUND_HALF_UP);   //  1.6
+echo round( 1.54, 1, PHP_ROUND_HALF_UP);   //  1.5
+echo round(-1.55, 1, PHP_ROUND_HALF_UP);   // -1.6
+echo round(-1.54, 1, PHP_ROUND_HALF_UP);   // -1.5
+
+/* Using PHP_ROUND_HALF_DOWN with 1 decimal digit precision */
+echo round( 1.55, 1, PHP_ROUND_HALF_DOWN); //  1.5
+echo round( 1.54, 1, PHP_ROUND_HALF_DOWN); //  1.5
+echo round(-1.55, 1, PHP_ROUND_HALF_DOWN); // -1.5
+echo round(-1.54, 1, PHP_ROUND_HALF_DOWN); // -1.5
+
+/* Using PHP_ROUND_HALF_EVEN with 1 decimal digit precision */
+echo round( 1.55, 1, PHP_ROUND_HALF_EVEN); //  1.6
+echo round( 1.54, 1, PHP_ROUND_HALF_EVEN); //  1.5
+echo round(-1.55, 1, PHP_ROUND_HALF_EVEN); // -1.6
+echo round(-1.54, 1, PHP_ROUND_HALF_EVEN); // -1.5
+
+/* Using PHP_ROUND_HALF_ODD with 1 decimal digit precision */
+echo round( 1.55, 1, PHP_ROUND_HALF_ODD);  //  1.5
+echo round( 1.54, 1, PHP_ROUND_HALF_ODD);  //  1.5
+echo round(-1.55, 1, PHP_ROUND_HALF_ODD);  // -1.5
+echo round(-1.54, 1, PHP_ROUND_HALF_ODD);  // -1.5
+?>
 ]]>
     </programlisting>
    </example>
@@ -189,4 +258,4 @@ End:
 vim600: syn=xml fen fdm=syntax fdl=2 si
 vim: et tw=78 syn=sgml
 vi: ts=1 sw=1
--->
+-->
\ No newline at end of file