Update round() for PHP-8.4 and Minor fixes for BCMath's round (#4425)

Author: SakiTakamachi

reference/bc/bcmath/number/round.xml

@@ -25,11 +25,11 @@
   <variablelist>
    <!-- precision parameter -->
    <xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('function.round')/db:refsect1[@role='parameters']/descendant::db:varlistentry[2])" />
-   <varlistentry>
+   <varlistentry xml:id="bcmath-number.round..parameters.mode">
     <term><parameter>mode</parameter></term>
     <listitem>
      <simpara>
-      Specifies the rounding mode.
+      Specifies the rounding mode. For more information about modes, see <enumname>RoundingMode</enumname>.
      </simpara>
     </listitem>
    </varlistentry>

reference/bc/functions/bcround.xml

@@ -27,14 +27,7 @@
   <variablelist>
    <xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('function.round')/db:refsect1[@role='parameters']/descendant::db:varlistentry[1])" />
    <xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('function.round')/db:refsect1[@role='parameters']/descendant::db:varlistentry[2])" />
-   <varlistentry>
-    <term><parameter>mode</parameter></term>
-    <listitem>
-     <simpara>
-      Specifies the rounding mode.
-     </simpara>
-    </listitem>
-   </varlistentry>
+   <xi:include xpointer="bcmath-number.round..parameters.mode" />
   </variablelist>
  </refsect1>
 

reference/math/functions/round.xml

@@ -11,7 +11,7 @@
    <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>int</type><parameter>mode</parameter><initializer><constant>PHP_ROUND_HALF_UP</constant></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>
    Returns the rounded value of <parameter>num</parameter> to
@@ -71,7 +71,7 @@
      <term><parameter>mode</parameter></term>
      <listitem>
       <para>
-       Use one of the following constants to specify the mode in which rounding occurs.
+       Use <enumname>RoundingMode</enumname> or one of the following constants to specify the mode in which rounding occurs.
        <informaltable>
         <tgroup cols="2">
          <thead>
@@ -112,6 +112,7 @@
          </tbody>
         </tgroup>
        </informaltable>
+       However, please note that some newly added modes only exist in <link linkend="enum.roundingmode">RoundingMode</link>.
       </para>
      </listitem>
     </varlistentry>
@@ -145,6 +146,12 @@
      </row>
     </thead>
     <tbody>
+     <row>
+      <entry>8.4.0</entry>
+      <entry>
+       Four new rounding modes have been added.
+      </entry>
+     </row>
      <row>
       <entry>8.4.0</entry>
       <entry>
@@ -321,6 +328,61 @@ float(-1.5)
 ]]>
     </screen>
    </example>
+  <example>
+   <title>Example of using <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>
 

reference/math/roundingmode.xml

@@ -9,7 +9,7 @@
    <simpara>
     The <enumname>RoundingMode</enumname> enum is used to specify how rounding
     should be performed for <function>round</function>,
-    <function>bcround</function>, and <methodname>BCMath::round</methodname>.
+    <function>bcround</function>, and <methodname>BcMath\Number::round</methodname>.
    </simpara>
   </section>