From 00ac2703e51c2ca9cbdccf94ad449860ad96cd46 Mon Sep 17 00:00:00 2001
From: Saki Takamachi <saki@php.net>
Date: Sat, 23 Nov 2024 16:02:18 +0900
Subject: [PATCH 01/12] Added bcceil, bcfloor, bcround and bcdivmod

---
 reference/bc/functions/bcceil.xml   |  91 ++++++++
 reference/bc/functions/bcdiv.xml    |   1 +
 reference/bc/functions/bcdivmod.xml | 142 +++++++++++++
 reference/bc/functions/bcfloor.xml  |  91 ++++++++
 reference/bc/functions/bcmod.xml    |   1 +
 reference/bc/functions/bcround.xml  | 316 ++++++++++++++++++++++++++++
 reference/bc/versions.xml           |   4 +
 7 files changed, 646 insertions(+)
 create mode 100644 reference/bc/functions/bcceil.xml
 create mode 100644 reference/bc/functions/bcdivmod.xml
 create mode 100644 reference/bc/functions/bcfloor.xml
 create mode 100644 reference/bc/functions/bcround.xml

diff --git a/reference/bc/functions/bcceil.xml b/reference/bc/functions/bcceil.xml
new file mode 100644
index 000000000000..d95b07847740
--- /dev/null
+++ b/reference/bc/functions/bcceil.xml
@@ -0,0 +1,91 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- $Revision$ -->
+<refentry xml:id="function.bcceil" xmlns="http://docbook.org/ns/docbook">
+ <refnamediv>
+  <refname>bcceil</refname>
+  <refpurpose>Round arbitrary precision number fractions up</refpurpose>
+ </refnamediv>
+
+ <refsect1 role="description">
+  &reftitle.description;
+  <methodsynopsis>
+   <type>string</type><methodname>bcceil</methodname>
+   <methodparam><type>string</type><parameter>num</parameter></methodparam>
+  </methodsynopsis>
+  <para>
+   Returns the next highest integer value by rounding up
+   <parameter>num</parameter> if necessary.
+  </para>
+ </refsect1>
+
+ <refsect1 role="parameters">
+  &reftitle.parameters;
+  <para>
+   <variablelist>
+    <varlistentry>
+     <term><parameter>num</parameter></term>
+     <listitem>
+      <para>
+       The value to round.
+      </para>
+     </listitem>
+    </varlistentry>
+   </variablelist>
+  </para>
+ </refsect1>
+
+ <refsect1 role="returnvalues">
+  &reftitle.returnvalues;
+  <para>
+   num rounded up to the next highest number as a string.
+  </para>
+ </refsect1>
+
+ <refsect1 role="examples">
+  &reftitle.examples;
+  <para>
+   <example>
+    <title><function>ceil</function> example</title>
+    <programlisting role="php">
+<![CDATA[
+<?php
+echo bcceil('4.3');    // '5'
+echo bcceil('9.999');  // '10'
+echo bcceil('-3.14');  // '-3'
+?>
+]]>
+    </programlisting>
+   </example>
+  </para>
+ </refsect1>
+
+ <refsect1 role="seealso">
+  &reftitle.seealso;
+  <para>
+   <simplelist>
+    <member><function>bcfloor</function></member>
+    <member><function>bcround</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
+-->
diff --git a/reference/bc/functions/bcdiv.xml b/reference/bc/functions/bcdiv.xml
index 7c5fb94d4dbd..685dc5e437fe 100644
--- a/reference/bc/functions/bcdiv.xml
+++ b/reference/bc/functions/bcdiv.xml
@@ -95,6 +95,7 @@ echo bcdiv('105', '6.55957', 3);  // 16.007
   &reftitle.seealso;
   <para>
    <simplelist>
+    <member><function>bcmod</function></member>
     <member><function>bcmul</function></member>
    </simplelist>
   </para>
diff --git a/reference/bc/functions/bcdivmod.xml b/reference/bc/functions/bcdivmod.xml
new file mode 100644
index 000000000000..95831fd14ae1
--- /dev/null
+++ b/reference/bc/functions/bcdivmod.xml
@@ -0,0 +1,142 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- $Revision$ -->
+<refentry xml:id="function.bcdivmod" xmlns="http://docbook.org/ns/docbook">
+ <refnamediv>
+  <refname>bcdivmod</refname>
+  <refpurpose>Get the quotient and modulus of an arbitrary precision number</refpurpose>
+ </refnamediv>
+
+ <refsect1 role="description">
+  &reftitle.description;
+  <methodsynopsis>
+   <type>string</type><methodname>bcdivmod</methodname>
+   <methodparam><type>string</type><parameter>num1</parameter></methodparam>
+   <methodparam><type>string</type><parameter>num2</parameter></methodparam>
+   <methodparam choice="opt"><type class="union"><type>int</type><type>null</type></type><parameter>scale</parameter><initializer>&null;</initializer></methodparam>
+  </methodsynopsis>
+  <para>
+   Get the quotient and remainder of dividing <parameter>num1</parameter> by
+   <parameter>num2</parameter>.
+  </para>
+ </refsect1>
+
+ <refsect1 role="parameters">
+  &reftitle.parameters;
+  <para>
+   <variablelist>
+    <varlistentry>
+     <term><parameter>num1</parameter></term>
+     <listitem>
+      <para>
+       The dividend, as a string.
+      </para>
+     </listitem>
+    </varlistentry>
+    <varlistentry>
+     <term><parameter>num2</parameter></term>
+     <listitem>
+      <para>
+       The divisor, as a string.
+      </para>
+     </listitem>
+    </varlistentry>
+    &bc.scale.description;
+   </variablelist>
+  </para>
+ </refsect1>
+
+ <refsect1 role="returnvalues">
+  &reftitle.returnvalues;
+  <para>
+   Returns an array, the first element is the quotient as a string and the second
+   element is the remainder as a string.
+  </para>
+ </refsect1>
+
+ <refsect1 role="errors">
+  &reftitle.errors;
+  <para>
+   This function throws a <classname>ValueError</classname> in the following cases:
+   <simplelist>
+    <member><parameter>num1</parameter> or <parameter>num2</parameter> is not a well-formed BCMath numeric string</member>
+    <member><parameter>scale</parameter> is outside the valid range</member>
+   </simplelist>
+  </para>
+  <para>
+   This function throws a <classname>DivisionByZeroError</classname> exception if <parameter>num2</parameter>
+   is <literal>0</literal>.
+  </para>
+ </refsect1>
+
+ <refsect1 role="examples">
+  &reftitle.examples;
+  <example>
+   <title><function>bcdivmod</function> example</title>
+   <programlisting role="php">
+<![CDATA[
+<?php
+bcscale(0);
+
+[$quot, $rem] = bcdivmod('5',  '3');
+echo $quot; // 1
+echo $rem;  // 2
+
+[$quot, $rem] = bcdivmod('5',  '-3');
+echo $quot; // -1
+echo $rem;  // 2
+
+[$quot, $rem] = bcdivmod('-5',  '3');
+echo $quot; // -1
+echo $rem;  // -2
+
+[$quot, $rem] = bcdivmod('-5',  '-3');
+echo $quot; // 1
+echo $rem;  // -2
+?>
+]]>
+   </programlisting>
+  </example>
+  <example>
+   <title><function>bcdivmod</function> with decimals</title>
+   <programlisting role="php">
+<![CDATA[
+<?php
+[$quot, $rem] = bcdivmod('5.7', '1.3', 1);
+echo $quot; // 4
+echo $rem;  // 0.5
+?>
+]]>
+   </programlisting>
+  </example>
+ </refsect1>
+
+ <refsect1 role="seealso">
+  &reftitle.seealso;
+  <para>
+   <simplelist>
+    <member><function>bcdiv</function></member>
+    <member><function>bcmod</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
+-->
diff --git a/reference/bc/functions/bcfloor.xml b/reference/bc/functions/bcfloor.xml
new file mode 100644
index 000000000000..068f0ef2cba3
--- /dev/null
+++ b/reference/bc/functions/bcfloor.xml
@@ -0,0 +1,91 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- $Revision$ -->
+<refentry xml:id="function.bcfloor" xmlns="http://docbook.org/ns/docbook">
+ <refnamediv>
+  <refname>bcfloor</refname>
+  <refpurpose>Round arbitrary precision number fractions down</refpurpose>
+ </refnamediv>
+
+ <refsect1 role="description">
+  &reftitle.description;
+  <methodsynopsis>
+   <type>string</type><methodname>bcfloor</methodname>
+   <methodparam><type>string</type><parameter>num</parameter></methodparam>
+  </methodsynopsis>
+  <para>
+   Returns the next lowest integer value by rounding down
+   <parameter>num</parameter> if necessary.
+  </para>
+ </refsect1>
+
+ <refsect1 role="parameters">
+  &reftitle.parameters;
+  <para>
+   <variablelist>
+    <varlistentry>
+     <term><parameter>num</parameter></term>
+     <listitem>
+      <para>
+       The value to round.
+      </para>
+     </listitem>
+    </varlistentry>
+   </variablelist>
+  </para>
+ </refsect1>
+
+ <refsect1 role="returnvalues">
+  &reftitle.returnvalues;
+  <para>
+   num rounded down to the next lowest number as a string.
+  </para>
+ </refsect1>
+
+ <refsect1 role="examples">
+  &reftitle.examples;
+  <para>
+   <example>
+    <title><function>ceil</function> example</title>
+    <programlisting role="php">
+<![CDATA[
+<?php
+echo bcfloor('4.3');    // '4'
+echo bcfloor('9.999');  // '9'
+echo bcfloor('-3.14');  // '-4'
+?>
+]]>
+    </programlisting>
+   </example>
+  </para>
+ </refsect1>
+
+ <refsect1 role="seealso">
+  &reftitle.seealso;
+  <para>
+   <simplelist>
+    <member><function>bcceil</function></member>
+    <member><function>bcround</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
+-->
diff --git a/reference/bc/functions/bcmod.xml b/reference/bc/functions/bcmod.xml
index 399bda9967b1..aa24c38c2224 100644
--- a/reference/bc/functions/bcmod.xml
+++ b/reference/bc/functions/bcmod.xml
@@ -125,6 +125,7 @@ echo bcmod('5.7', '1.3'); // 0.5 as of PHP 7.2.0; 0 previously
   <para>
    <simplelist>
     <member><function>bcdiv</function></member>
+    <member><function>bcdivmod</function></member>
    </simplelist>
   </para>
  </refsect1>
diff --git a/reference/bc/functions/bcround.xml b/reference/bc/functions/bcround.xml
new file mode 100644
index 000000000000..ce55db84f5c5
--- /dev/null
+++ b/reference/bc/functions/bcround.xml
@@ -0,0 +1,316 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- $Revision$ -->
+<refentry xml:id="function.bcround" xmlns="http://docbook.org/ns/docbook">
+ <refnamediv>
+  <refname>bcround</refname>
+  <refpurpose>Rounds a arbitrary precision number</refpurpose>
+ </refnamediv>
+
+ <refsect1 role="description">
+  &reftitle.description;
+  <methodsynopsis>
+   <type>string</type><methodname>bcround</methodname>
+   <methodparam><type>string</type><parameter>num</parameter></methodparam>
+   <methodparam choice="opt"><type>int</type><parameter>precision</parameter><initializer>0</initializer></methodparam>
+   <methodparam choice="opt"><type>RoundingMode</type><parameter>mode</parameter><initializer>RoundingMode::HalfAwayFromZero</initializer></methodparam>
+  </methodsynopsis>
+  <para>
+   Returns the rounded value of <parameter>num</parameter> to
+   specified <parameter>precision</parameter>
+   (number of digits after the decimal point).
+   <parameter>precision</parameter> can also be negative or zero (default).
+  </para>
+ </refsect1>
+
+ <refsect1 role="parameters">
+  &reftitle.parameters;
+  <para>
+   <variablelist>
+    <varlistentry>
+     <term><parameter>num</parameter></term>
+     <listitem>
+      <para>
+       The value to round.
+      </para>
+     </listitem>
+    </varlistentry>
+    <varlistentry>
+     <term><parameter>precision</parameter></term>
+     <listitem>
+      <para>
+       The optional number of decimal digits to round to.
+      </para>
+      <para>
+       If the <parameter>precision</parameter> is positive, <parameter>num</parameter> is
+       rounded to <parameter>precision</parameter> significant digits after the decimal point.
+      </para>
+      <para>
+       If the <parameter>precision</parameter> is negative, <parameter>num</parameter> is
+       rounded to <parameter>precision</parameter> significant digits before the decimal point,
+       i.e. to the nearest multiple of <code>pow(10, -$precision)</code>, e.g. for a
+       <parameter>precision</parameter> of -1 <parameter>num</parameter> is rounded to tens,
+       for a <parameter>precision</parameter> of -2 to hundreds, etc.
+      </para>
+     </listitem>
+    </varlistentry>
+    <varlistentry>
+     <term><parameter>mode</parameter></term>
+     <listitem>
+      <para>
+       Specifies the rounding mode.
+      </para>
+     </listitem>
+    </varlistentry>
+   </variablelist>
+  </para>
+ </refsect1>
+
+ <refsect1 role="returnvalues">
+  &reftitle.returnvalues;
+  <para>
+   The value rounded to the given precision, as a string.
+  </para>
+ </refsect1>
+
+ <refsect1 role="examples">
+  &reftitle.examples;
+  <para>
+   <example>
+    <title><function>bcround</function> examples</title>
+    <programlisting role="php">
+<![CDATA[
+<?php
+var_dump(bcround('3.4'));
+var_dump(bcround('3.5'));
+var_dump(bcround('3.6'));
+var_dump(bcround('3.6', 0));
+var_dump(bcround('5.045', 2));
+var_dump(bcround('5.055', 2));
+var_dump(bcround('345', -2));
+var_dump(bcround('345', -3));
+var_dump(bcround('678', -2));
+var_dump(bcround('678', -3));
+?>
+]]>
+    </programlisting>
+    &example.outputs;
+    <screen role="php">
+<![CDATA[
+string(1) "3"
+string(1) "4"
+string(1) "4"
+string(1) "4"
+string(4) "5.05"
+string(4) "5.06"
+string(3) "300"
+string(1) "0"
+string(3) "700"
+string(4) "1000"
+]]>
+    </screen>
+   </example>
+  </para>
+  <para>
+   <example>
+    <title><parameter>precision</parameter> examples</title>
+    <programlisting role="php">
+<![CDATA[
+<?php
+$number = '123.45';
+
+var_dump(bcround($number, 3));
+var_dump(bcround($number, 2));
+var_dump(bcround($number, 1));
+var_dump(bcround($number, 0));
+var_dump(bcround($number, -1));
+var_dump(bcround($number, -2));
+var_dump(bcround($number, -3));
+?>
+]]>
+    </programlisting>
+    &example.outputs;
+    <screen role="php">
+<![CDATA[
+string(7) "123.450"
+string(6) "123.45"
+string(5) "123.5"
+string(3) "123"
+string(3) "120"
+string(3) "100"
+string(1) "0"
+]]>
+    </screen>
+   </example>
+  </para>
+  <para>
+   <example>
+    <title><parameter>mode</parameter> examples</title>
+    <programlisting role="php">
+<![CDATA[
+<?php
+echo 'Rounding modes with 9.5' . PHP_EOL;
+var_dump(bcround('9.5', 0, RoundingMode::HalfAwayFromZero));
+var_dump(bcround('9.5', 0, RoundingMode::HalfTowardsZero));
+var_dump(bcround('9.5', 0, RoundingMode::HalfEven));
+var_dump(bcround('9.5', 0, RoundingMode::HalfOdd));
+var_dump(bcround('9.5', 0, RoundingMode::TowardsZero));
+var_dump(bcround('9.5', 0, RoundingMode::AwayFromZero));
+var_dump(bcround('9.5', 0, RoundingMode::NegativeInfinity));
+var_dump(bcround('9.5', 0, RoundingMode::PositiveInfinity));
+
+echo PHP_EOL;
+echo 'Rounding modes with 8.5' . PHP_EOL;
+var_dump(bcround('8.5', 0, RoundingMode::HalfAwayFromZero));
+var_dump(bcround('8.5', 0, RoundingMode::HalfTowardsZero));
+var_dump(bcround('8.5', 0, RoundingMode::HalfEven));
+var_dump(bcround('8.5', 0, RoundingMode::HalfOdd));
+var_dump(bcround('8.5', 0, RoundingMode::TowardsZero));
+var_dump(bcround('8.5', 0, RoundingMode::AwayFromZero));
+var_dump(bcround('8.5', 0, RoundingMode::NegativeInfinity));
+var_dump(bcround('8.5', 0, RoundingMode::PositiveInfinity));
+?>
+]]>
+    </programlisting>
+    &example.outputs;
+    <screen role="php">
+<![CDATA[
+Rounding modes with 9.5
+string(2) "10"
+string(1) "9"
+string(2) "10"
+string(1) "9"
+string(1) "9"
+string(2) "10"
+string(1) "9"
+string(2) "10"
+
+Rounding modes with 8.5
+string(1) "9"
+string(1) "8"
+string(1) "8"
+string(1) "9"
+string(1) "8"
+string(1) "9"
+string(1) "8"
+string(1) "9"
+]]>
+    </screen>
+   </example>
+  </para>
+  <para>
+   <example>
+    <title><parameter>mode</parameter> with <parameter>precision</parameter> examples</title>
+    <programlisting role="php">
+<![CDATA[
+<?php
+echo 'Using RoundingMode::HalfAwayFromZero with 1 decimal digit precision' . PHP_EOL;
+var_dump(bcround( 1.55, 1, RoundingMode::HalfAwayFromZero));
+var_dump(bcround(-1.55, 1, RoundingMode::HalfAwayFromZero));
+
+echo PHP_EOL;
+echo 'Using RoundingMode::HalfTowardsZero with 1 decimal digit precision' . PHP_EOL;
+var_dump(bcround( 1.55, 1, RoundingMode::HalfTowardsZero));
+var_dump(bcround(-1.55, 1, RoundingMode::HalfTowardsZero));
+
+echo PHP_EOL;
+echo 'Using RoundingMode::HalfEven with 1 decimal digit precision' . PHP_EOL;
+var_dump(bcround( 1.55, 1, RoundingMode::HalfEven));
+var_dump(bcround(-1.55, 1, RoundingMode::HalfEven));
+
+echo PHP_EOL;
+echo 'Using RoundingMode::HalfOdd with 1 decimal digit precision' . PHP_EOL;
+var_dump(bcround( 1.55, 1, RoundingMode::HalfOdd));
+var_dump(bcround(-1.55, 1, RoundingMode::HalfOdd));
+
+echo PHP_EOL;
+echo 'Using RoundingMode::TowardsZero with 1 decimal digit precision' . PHP_EOL;
+var_dump(bcround( 1.55, 1, RoundingMode::TowardsZero));
+var_dump(bcround(-1.55, 1, RoundingMode::TowardsZero));
+
+echo PHP_EOL;
+echo 'Using RoundingMode::AwayFromZero with 1 decimal digit precision' . PHP_EOL;
+var_dump(bcround( 1.55, 1, RoundingMode::AwayFromZero));
+var_dump(bcround(-1.55, 1, RoundingMode::AwayFromZero));
+
+echo PHP_EOL;
+echo 'Using RoundingMode::NegativeInfinity with 1 decimal digit precision' . PHP_EOL;
+var_dump(bcround( 1.55, 1, RoundingMode::NegativeInfinity));
+var_dump(bcround(-1.55, 1, RoundingMode::NegativeInfinity));
+
+echo PHP_EOL;
+echo 'Using RoundingMode::PositiveInfinity with 1 decimal digit precision' . PHP_EOL;
+var_dump(bcround( 1.55, 1, RoundingMode::PositiveInfinity));
+var_dump(bcround(-1.55, 1, RoundingMode::PositiveInfinity));
+?>
+]]>
+    </programlisting>
+    &example.outputs;
+    <screen role="php">
+<![CDATA[
+Using RoundingMode::HalfAwayFromZero with 1 decimal digit precision
+string(3) "1.6"
+string(4) "-1.6"
+
+Using RoundingMode::HalfTowardsZero with 1 decimal digit precision
+string(3) "1.5"
+string(4) "-1.5"
+
+Using RoundingMode::HalfEven with 1 decimal digit precision
+string(3) "1.6"
+string(4) "-1.6"
+
+Using RoundingMode::HalfOdd with 1 decimal digit precision
+string(3) "1.5"
+string(4) "-1.5"
+
+Using RoundingMode::TowardsZero with 1 decimal digit precision
+string(3) "1.5"
+string(4) "-1.5"
+
+Using RoundingMode::AwayFromZero with 1 decimal digit precision
+string(3) "1.6"
+string(4) "-1.6"
+
+Using RoundingMode::NegativeInfinity with 1 decimal digit precision
+string(3) "1.5"
+string(4) "-1.6"
+
+Using RoundingMode::PositiveInfinity with 1 decimal digit precision
+string(3) "1.6"
+string(4) "-1.5"
+]]>
+    </screen>
+   </example>
+  </para>
+ </refsect1>
+
+ <refsect1 role="seealso">
+  &reftitle.seealso;
+  <para>
+   <simplelist>
+    <member><function>bcceil</function></member>
+    <member><function>bcfloor</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
+-->
diff --git a/reference/bc/versions.xml b/reference/bc/versions.xml
index 2a8865130fd4..5a85d801a5e6 100644
--- a/reference/bc/versions.xml
+++ b/reference/bc/versions.xml
@@ -5,12 +5,16 @@
 -->
 <versions> 
  <function name="bcadd" from="PHP 4, PHP 5, PHP 7, PHP 8"/>
+ <function name="bcceil" from="PHP 8 &gt;= 8.4.0"/>
  <function name="bccomp" from="PHP 4, PHP 5, PHP 7, PHP 8"/>
  <function name="bcdiv" from="PHP 4, PHP 5, PHP 7, PHP 8"/>
+ <function name="bcdivmod" from="PHP 8 &gt;= 8.4.0"/>
+ <function name="bcfloor" from="PHP 8 &gt;= 8.4.0"/>
  <function name="bcmod" from="PHP 4, PHP 5, PHP 7, PHP 8"/>
  <function name="bcmul" from="PHP 4, PHP 5, PHP 7, PHP 8"/>
  <function name="bcpow" from="PHP 4, PHP 5, PHP 7, PHP 8"/>
  <function name="bcpowmod" from="PHP 5, PHP 7, PHP 8"/>
+ <function name="bcround" from="PHP 8 &gt;= 8.4.0"/>
  <function name="bcscale" from="PHP 4, PHP 5, PHP 7, PHP 8"/>
  <function name="bcsqrt" from="PHP 4, PHP 5, PHP 7, PHP 8"/>
  <function name="bcsub" from="PHP 4, PHP 5, PHP 7, PHP 8"/>

From 2e7b63addf8bec367d57c237bd744434f336d6c2 Mon Sep 17 00:00:00 2001
From: Saki Takamachi <saki@php.net>
Date: Sat, 23 Nov 2024 19:29:16 +0900
Subject: [PATCH 02/12] Remove unnecessary para and use exceptionname

---
 reference/bc/functions/bcdivmod.xml | 44 ++++++++++++++---------------
 1 file changed, 21 insertions(+), 23 deletions(-)

diff --git a/reference/bc/functions/bcdivmod.xml b/reference/bc/functions/bcdivmod.xml
index 95831fd14ae1..58671c3d71a3 100644
--- a/reference/bc/functions/bcdivmod.xml
+++ b/reference/bc/functions/bcdivmod.xml
@@ -22,27 +22,25 @@
 
  <refsect1 role="parameters">
   &reftitle.parameters;
-  <para>
-   <variablelist>
-    <varlistentry>
-     <term><parameter>num1</parameter></term>
-     <listitem>
-      <para>
-       The dividend, as a string.
-      </para>
-     </listitem>
-    </varlistentry>
-    <varlistentry>
-     <term><parameter>num2</parameter></term>
-     <listitem>
-      <para>
-       The divisor, as a string.
-      </para>
-     </listitem>
-    </varlistentry>
-    &bc.scale.description;
-   </variablelist>
-  </para>
+  <variablelist>
+   <varlistentry>
+    <term><parameter>num1</parameter></term>
+    <listitem>
+     <para>
+      The dividend, as a string.
+     </para>
+    </listitem>
+   </varlistentry>
+   <varlistentry>
+    <term><parameter>num2</parameter></term>
+    <listitem>
+     <para>
+      The divisor, as a string.
+     </para>
+    </listitem>
+   </varlistentry>
+   &bc.scale.description;
+  </variablelist>
  </refsect1>
 
  <refsect1 role="returnvalues">
@@ -56,14 +54,14 @@
  <refsect1 role="errors">
   &reftitle.errors;
   <para>
-   This function throws a <classname>ValueError</classname> in the following cases:
+   This function throws a <exceptionname>ValueError</exceptionname> in the following cases:
    <simplelist>
     <member><parameter>num1</parameter> or <parameter>num2</parameter> is not a well-formed BCMath numeric string</member>
     <member><parameter>scale</parameter> is outside the valid range</member>
    </simplelist>
   </para>
   <para>
-   This function throws a <classname>DivisionByZeroError</classname> exception if <parameter>num2</parameter>
+   This function throws a <exceptionname>DivisionByZeroError</exceptionname> exception if <parameter>num2</parameter>
    is <literal>0</literal>.
   </para>
  </refsect1>

From 1d6867287ee08f49dee21c88f3f1eae65ea09769 Mon Sep 17 00:00:00 2001
From: Saki Takamachi <saki@php.net>
Date: Sat, 23 Nov 2024 21:13:26 +0900
Subject: [PATCH 03/12] Address comments

---
 reference/bc/functions/bcceil.xml   |  44 ++++----
 reference/bc/functions/bcdivmod.xml |  14 ++-
 reference/bc/functions/bcfloor.xml  |  44 ++++----
 reference/bc/functions/bcround.xml  | 156 +++++++++++++---------------
 4 files changed, 116 insertions(+), 142 deletions(-)

diff --git a/reference/bc/functions/bcceil.xml b/reference/bc/functions/bcceil.xml
index d95b07847740..ca2084426b7a 100644
--- a/reference/bc/functions/bcceil.xml
+++ b/reference/bc/functions/bcceil.xml
@@ -20,18 +20,16 @@
 
  <refsect1 role="parameters">
   &reftitle.parameters;
-  <para>
-   <variablelist>
-    <varlistentry>
-     <term><parameter>num</parameter></term>
-     <listitem>
-      <para>
-       The value to round.
-      </para>
-     </listitem>
-    </varlistentry>
-   </variablelist>
-  </para>
+  <variablelist>
+   <varlistentry>
+    <term><parameter>num</parameter></term>
+    <listitem>
+     <para>
+      The value to round.
+     </para>
+    </listitem>
+   </varlistentry>
+  </variablelist>
  </refsect1>
 
  <refsect1 role="returnvalues">
@@ -43,10 +41,9 @@
 
  <refsect1 role="examples">
   &reftitle.examples;
-  <para>
-   <example>
-    <title><function>ceil</function> example</title>
-    <programlisting role="php">
+  <example>
+   <title><function>ceil</function> example</title>
+   <programlisting role="php">
 <![CDATA[
 <?php
 echo bcceil('4.3');    // '5'
@@ -54,19 +51,16 @@ echo bcceil('9.999');  // '10'
 echo bcceil('-3.14');  // '-3'
 ?>
 ]]>
-    </programlisting>
-   </example>
-  </para>
+   </programlisting>
+  </example>
  </refsect1>
 
  <refsect1 role="seealso">
   &reftitle.seealso;
-  <para>
-   <simplelist>
-    <member><function>bcfloor</function></member>
-    <member><function>bcround</function></member>
-   </simplelist>
-  </para>
+  <simplelist>
+   <member><function>bcfloor</function></member>
+   <member><function>bcround</function></member>
+  </simplelist>
  </refsect1>
 </refentry>
 <!-- Keep this comment at the end of the file
diff --git a/reference/bc/functions/bcdivmod.xml b/reference/bc/functions/bcdivmod.xml
index 58671c3d71a3..cdceb61ab4c5 100644
--- a/reference/bc/functions/bcdivmod.xml
+++ b/reference/bc/functions/bcdivmod.xml
@@ -60,10 +60,10 @@
     <member><parameter>scale</parameter> is outside the valid range</member>
    </simplelist>
   </para>
-  <para>
+  <simpara>
    This function throws a <exceptionname>DivisionByZeroError</exceptionname> exception if <parameter>num2</parameter>
    is <literal>0</literal>.
-  </para>
+  </simpara>
  </refsect1>
 
  <refsect1 role="examples">
@@ -110,12 +110,10 @@ echo $rem;  // 0.5
 
  <refsect1 role="seealso">
   &reftitle.seealso;
-  <para>
-   <simplelist>
-    <member><function>bcdiv</function></member>
-    <member><function>bcmod</function></member>
-   </simplelist>
-  </para>
+  <simplelist>
+   <member><function>bcdiv</function></member>
+   <member><function>bcmod</function></member>
+  </simplelist>
  </refsect1>
 </refentry>
 <!-- Keep this comment at the end of the file
diff --git a/reference/bc/functions/bcfloor.xml b/reference/bc/functions/bcfloor.xml
index 068f0ef2cba3..9a0dfe7481f3 100644
--- a/reference/bc/functions/bcfloor.xml
+++ b/reference/bc/functions/bcfloor.xml
@@ -20,18 +20,16 @@
 
  <refsect1 role="parameters">
   &reftitle.parameters;
-  <para>
-   <variablelist>
-    <varlistentry>
-     <term><parameter>num</parameter></term>
-     <listitem>
-      <para>
-       The value to round.
-      </para>
-     </listitem>
-    </varlistentry>
-   </variablelist>
-  </para>
+  <variablelist>
+   <varlistentry>
+    <term><parameter>num</parameter></term>
+    <listitem>
+     <para>
+      The value to round.
+     </para>
+    </listitem>
+   </varlistentry>
+  </variablelist>
  </refsect1>
 
  <refsect1 role="returnvalues">
@@ -43,10 +41,9 @@
 
  <refsect1 role="examples">
   &reftitle.examples;
-  <para>
-   <example>
-    <title><function>ceil</function> example</title>
-    <programlisting role="php">
+  <example>
+   <title><function>ceil</function> example</title>
+   <programlisting role="php">
 <![CDATA[
 <?php
 echo bcfloor('4.3');    // '4'
@@ -54,19 +51,16 @@ echo bcfloor('9.999');  // '9'
 echo bcfloor('-3.14');  // '-4'
 ?>
 ]]>
-    </programlisting>
-   </example>
-  </para>
+   </programlisting>
+  </example>
  </refsect1>
 
  <refsect1 role="seealso">
   &reftitle.seealso;
-  <para>
-   <simplelist>
-    <member><function>bcceil</function></member>
-    <member><function>bcround</function></member>
-   </simplelist>
-  </para>
+  <simplelist>
+   <member><function>bcceil</function></member>
+   <member><function>bcround</function></member>
+  </simplelist>
  </refsect1>
 </refentry>
 <!-- Keep this comment at the end of the file
diff --git a/reference/bc/functions/bcround.xml b/reference/bc/functions/bcround.xml
index ce55db84f5c5..fafe324ee8a3 100644
--- a/reference/bc/functions/bcround.xml
+++ b/reference/bc/functions/bcround.xml
@@ -24,45 +24,43 @@
 
  <refsect1 role="parameters">
   &reftitle.parameters;
-  <para>
-   <variablelist>
-    <varlistentry>
-     <term><parameter>num</parameter></term>
-     <listitem>
-      <para>
-       The value to round.
-      </para>
-     </listitem>
-    </varlistentry>
-    <varlistentry>
-     <term><parameter>precision</parameter></term>
-     <listitem>
-      <para>
-       The optional number of decimal digits to round to.
-      </para>
-      <para>
-       If the <parameter>precision</parameter> is positive, <parameter>num</parameter> is
-       rounded to <parameter>precision</parameter> significant digits after the decimal point.
-      </para>
-      <para>
-       If the <parameter>precision</parameter> is negative, <parameter>num</parameter> is
-       rounded to <parameter>precision</parameter> significant digits before the decimal point,
-       i.e. to the nearest multiple of <code>pow(10, -$precision)</code>, e.g. for a
-       <parameter>precision</parameter> of -1 <parameter>num</parameter> is rounded to tens,
-       for a <parameter>precision</parameter> of -2 to hundreds, etc.
-      </para>
-     </listitem>
-    </varlistentry>
-    <varlistentry>
-     <term><parameter>mode</parameter></term>
-     <listitem>
-      <para>
-       Specifies the rounding mode.
-      </para>
-     </listitem>
-    </varlistentry>
-   </variablelist>
-  </para>
+  <variablelist>
+   <varlistentry>
+    <term><parameter>num</parameter></term>
+    <listitem>
+     <para>
+      The value to round.
+     </para>
+    </listitem>
+   </varlistentry>
+   <varlistentry>
+    <term><parameter>precision</parameter></term>
+    <listitem>
+     <para>
+      The optional number of decimal digits to round to.
+     </para>
+     <para>
+      If the <parameter>precision</parameter> is positive, <parameter>num</parameter> is
+      rounded to <parameter>precision</parameter> significant digits after the decimal point.
+     </para>
+     <para>
+      If the <parameter>precision</parameter> is negative, <parameter>num</parameter> is
+      rounded to <parameter>precision</parameter> significant digits before the decimal point,
+      i.e. to the nearest multiple of <code>pow(10, -$precision)</code>, e.g. for a
+      <parameter>precision</parameter> of -1 <parameter>num</parameter> is rounded to tens,
+      for a <parameter>precision</parameter> of -2 to hundreds, etc.
+     </para>
+    </listitem>
+   </varlistentry>
+   <varlistentry>
+    <term><parameter>mode</parameter></term>
+    <listitem>
+     <para>
+      Specifies the rounding mode.
+     </para>
+    </listitem>
+   </varlistentry>
+  </variablelist>
  </refsect1>
 
  <refsect1 role="returnvalues">
@@ -74,10 +72,9 @@
 
  <refsect1 role="examples">
   &reftitle.examples;
-  <para>
    <example>
-    <title><function>bcround</function> examples</title>
-    <programlisting role="php">
+   <title><function>bcround</function> examples</title>
+   <programlisting role="php">
 <![CDATA[
 <?php
 var_dump(bcround('3.4'));
@@ -92,9 +89,9 @@ var_dump(bcround('678', -2));
 var_dump(bcround('678', -3));
 ?>
 ]]>
-    </programlisting>
-    &example.outputs;
-    <screen role="php">
+   </programlisting>
+   &example.outputs;
+   <screen role="php">
 <![CDATA[
 string(1) "3"
 string(1) "4"
@@ -107,13 +104,11 @@ string(1) "0"
 string(3) "700"
 string(4) "1000"
 ]]>
-    </screen>
-   </example>
-  </para>
-  <para>
-   <example>
-    <title><parameter>precision</parameter> examples</title>
-    <programlisting role="php">
+   </screen>
+  </example>
+  <example>
+   <title><parameter>precision</parameter> examples</title>
+   <programlisting role="php">
 <![CDATA[
 <?php
 $number = '123.45';
@@ -127,9 +122,9 @@ var_dump(bcround($number, -2));
 var_dump(bcround($number, -3));
 ?>
 ]]>
-    </programlisting>
-    &example.outputs;
-    <screen role="php">
+   </programlisting>
+   &example.outputs;
+   <screen role="php">
 <![CDATA[
 string(7) "123.450"
 string(6) "123.45"
@@ -139,13 +134,11 @@ string(3) "120"
 string(3) "100"
 string(1) "0"
 ]]>
-    </screen>
-   </example>
-  </para>
-  <para>
-   <example>
-    <title><parameter>mode</parameter> examples</title>
-    <programlisting role="php">
+   </screen>
+  </example>
+  <example>
+   <title><parameter>mode</parameter> examples</title>
+   <programlisting role="php">
 <![CDATA[
 <?php
 echo 'Rounding modes with 9.5' . PHP_EOL;
@@ -170,9 +163,9 @@ var_dump(bcround('8.5', 0, RoundingMode::NegativeInfinity));
 var_dump(bcround('8.5', 0, RoundingMode::PositiveInfinity));
 ?>
 ]]>
-    </programlisting>
-    &example.outputs;
-    <screen role="php">
+   </programlisting>
+   &example.outputs;
+   <screen role="php">
 <![CDATA[
 Rounding modes with 9.5
 string(2) "10"
@@ -194,13 +187,11 @@ string(1) "9"
 string(1) "8"
 string(1) "9"
 ]]>
-    </screen>
-   </example>
-  </para>
-  <para>
-   <example>
-    <title><parameter>mode</parameter> with <parameter>precision</parameter> examples</title>
-    <programlisting role="php">
+   </screen>
+  </example>
+  <example>
+   <title><parameter>mode</parameter> with <parameter>precision</parameter> examples</title>
+   <programlisting role="php">
 <![CDATA[
 <?php
 echo 'Using RoundingMode::HalfAwayFromZero with 1 decimal digit precision' . PHP_EOL;
@@ -243,9 +234,9 @@ var_dump(bcround( 1.55, 1, RoundingMode::PositiveInfinity));
 var_dump(bcround(-1.55, 1, RoundingMode::PositiveInfinity));
 ?>
 ]]>
-    </programlisting>
-    &example.outputs;
-    <screen role="php">
+   </programlisting>
+   &example.outputs;
+   <screen role="php">
 <![CDATA[
 Using RoundingMode::HalfAwayFromZero with 1 decimal digit precision
 string(3) "1.6"
@@ -279,19 +270,16 @@ Using RoundingMode::PositiveInfinity with 1 decimal digit precision
 string(3) "1.6"
 string(4) "-1.5"
 ]]>
-    </screen>
-   </example>
-  </para>
+   </screen>
+  </example>
  </refsect1>
 
  <refsect1 role="seealso">
   &reftitle.seealso;
-  <para>
-   <simplelist>
-    <member><function>bcceil</function></member>
-    <member><function>bcfloor</function></member>
-   </simplelist>
-  </para>
+  <simplelist>
+   <member><function>bcceil</function></member>
+   <member><function>bcfloor</function></member>
+  </simplelist>
  </refsect1>
 </refentry>
 <!-- Keep this comment at the end of the file

From 459f55e7aaf19c4992b8c88b45cbbb1e8d7bc3e7 Mon Sep 17 00:00:00 2001
From: Saki Takamachi <34942839+SakiTakamachi@users.noreply.github.com>
Date: Sun, 24 Nov 2024 14:53:25 +0900
Subject: [PATCH 04/12] address a comment

Co-authored-by: Gina Peter Banyard <girgias@php.net>
---
 reference/bc/functions/bcceil.xml | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/reference/bc/functions/bcceil.xml b/reference/bc/functions/bcceil.xml
index ca2084426b7a..e24f4c675829 100644
--- a/reference/bc/functions/bcceil.xml
+++ b/reference/bc/functions/bcceil.xml
@@ -34,9 +34,9 @@
 
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
-  <para>
-   num rounded up to the next highest number as a string.
-  </para>
+  <simpara>
+   Returns a BCMath string number representing <parameter>num</parameter> rounded up to the nearest integer.
+  </simpara>
  </refsect1>
 
  <refsect1 role="examples">

From 310a17c3caac518816e9bc98bf345f4ac9c84e0a Mon Sep 17 00:00:00 2001
From: Saki Takamachi <34942839+SakiTakamachi@users.noreply.github.com>
Date: Sun, 24 Nov 2024 15:49:25 +0900
Subject: [PATCH 05/12] address a comment

Co-authored-by: Gina Peter Banyard <girgias@php.net>
---
 reference/bc/functions/bcround.xml | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/reference/bc/functions/bcround.xml b/reference/bc/functions/bcround.xml
index fafe324ee8a3..cf462f4282db 100644
--- a/reference/bc/functions/bcround.xml
+++ b/reference/bc/functions/bcround.xml
@@ -107,7 +107,9 @@ string(4) "1000"
    </screen>
   </example>
   <example>
-   <title><parameter>precision</parameter> examples</title>
+   <title>
+    Example of using <function>bcround</function> with different <parameter>precision</parameter> values
+   </title>
    <programlisting role="php">
 <![CDATA[
 <?php

From 6044026f6cd054864497877825c5c5311fe15994 Mon Sep 17 00:00:00 2001
From: Saki Takamachi <saki@php.net>
Date: Sun, 24 Nov 2024 17:24:34 +0900
Subject: [PATCH 06/12] Address comments

---
 reference/bc/functions/bcceil.xml   | 10 +++---
 reference/bc/functions/bcdivmod.xml | 20 +++++------
 reference/bc/functions/bcfloor.xml  | 16 ++++-----
 reference/bc/functions/bcround.xml  | 54 +++++++++--------------------
 4 files changed, 40 insertions(+), 60 deletions(-)

diff --git a/reference/bc/functions/bcceil.xml b/reference/bc/functions/bcceil.xml
index e24f4c675829..1a70e4002e72 100644
--- a/reference/bc/functions/bcceil.xml
+++ b/reference/bc/functions/bcceil.xml
@@ -12,10 +12,10 @@
    <type>string</type><methodname>bcceil</methodname>
    <methodparam><type>string</type><parameter>num</parameter></methodparam>
   </methodsynopsis>
-  <para>
+  <simpara>
    Returns the next highest integer value by rounding up
    <parameter>num</parameter> if necessary.
-  </para>
+  </simpara>
  </refsect1>
 
  <refsect1 role="parameters">
@@ -24,9 +24,9 @@
    <varlistentry>
     <term><parameter>num</parameter></term>
     <listitem>
-     <para>
+     <simpara>
       The value to round.
-     </para>
+     </simpara>
     </listitem>
    </varlistentry>
   </variablelist>
@@ -42,7 +42,7 @@
  <refsect1 role="examples">
   &reftitle.examples;
   <example>
-   <title><function>ceil</function> example</title>
+   <title><function>bcceil</function> example</title>
    <programlisting role="php">
 <![CDATA[
 <?php
diff --git a/reference/bc/functions/bcdivmod.xml b/reference/bc/functions/bcdivmod.xml
index cdceb61ab4c5..76cd7c2b7684 100644
--- a/reference/bc/functions/bcdivmod.xml
+++ b/reference/bc/functions/bcdivmod.xml
@@ -14,10 +14,10 @@
    <methodparam><type>string</type><parameter>num2</parameter></methodparam>
    <methodparam choice="opt"><type class="union"><type>int</type><type>null</type></type><parameter>scale</parameter><initializer>&null;</initializer></methodparam>
   </methodsynopsis>
-  <para>
+  <simpara>
    Get the quotient and remainder of dividing <parameter>num1</parameter> by
    <parameter>num2</parameter>.
-  </para>
+  </simpara>
  </refsect1>
 
  <refsect1 role="parameters">
@@ -26,17 +26,17 @@
    <varlistentry>
     <term><parameter>num1</parameter></term>
     <listitem>
-     <para>
+     <simpara>
       The dividend, as a string.
-     </para>
+     </simpara>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>num2</parameter></term>
     <listitem>
-     <para>
+     <simpara>
       The divisor, as a string.
-     </para>
+     </simpara>
     </listitem>
    </varlistentry>
    &bc.scale.description;
@@ -45,10 +45,10 @@
 
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
-  <para>
-   Returns an array, the first element is the quotient as a string and the second
-   element is the remainder as a string.
-  </para>
+  <simpara>
+   Returns an indexed <type>array</type> where the first element is the quotient as a <type>string</type>
+   and the second element is the remainder as a <type>string</type>.
+  </simpara>
  </refsect1>
 
  <refsect1 role="errors">
diff --git a/reference/bc/functions/bcfloor.xml b/reference/bc/functions/bcfloor.xml
index 9a0dfe7481f3..37f6bab4d3b7 100644
--- a/reference/bc/functions/bcfloor.xml
+++ b/reference/bc/functions/bcfloor.xml
@@ -12,10 +12,10 @@
    <type>string</type><methodname>bcfloor</methodname>
    <methodparam><type>string</type><parameter>num</parameter></methodparam>
   </methodsynopsis>
-  <para>
+  <simpara>
    Returns the next lowest integer value by rounding down
    <parameter>num</parameter> if necessary.
-  </para>
+  </simpara>
  </refsect1>
 
  <refsect1 role="parameters">
@@ -24,9 +24,9 @@
    <varlistentry>
     <term><parameter>num</parameter></term>
     <listitem>
-     <para>
+     <simpara>
       The value to round.
-     </para>
+     </simpara>
     </listitem>
    </varlistentry>
   </variablelist>
@@ -34,15 +34,15 @@
 
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
-  <para>
-   num rounded down to the next lowest number as a string.
-  </para>
+  <simpara>
+   Returns a BCMath string number representing <parameter>num</parameter> rounded down to the nearest integer.
+  </simpara>
  </refsect1>
 
  <refsect1 role="examples">
   &reftitle.examples;
   <example>
-   <title><function>ceil</function> example</title>
+   <title><function>bcfloor</function> example</title>
    <programlisting role="php">
 <![CDATA[
 <?php
diff --git a/reference/bc/functions/bcround.xml b/reference/bc/functions/bcround.xml
index cf462f4282db..c4f0e9698f61 100644
--- a/reference/bc/functions/bcround.xml
+++ b/reference/bc/functions/bcround.xml
@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="utf-8"?>
 <!-- $Revision$ -->
-<refentry xml:id="function.bcround" xmlns="http://docbook.org/ns/docbook">
+<refentry xml:id="function.bcround" xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude">
  <refnamediv>
   <refname>bcround</refname>
   <refpurpose>Rounds a arbitrary precision number</refpurpose>
@@ -14,50 +14,25 @@
    <methodparam choice="opt"><type>int</type><parameter>precision</parameter><initializer>0</initializer></methodparam>
    <methodparam choice="opt"><type>RoundingMode</type><parameter>mode</parameter><initializer>RoundingMode::HalfAwayFromZero</initializer></methodparam>
   </methodsynopsis>
-  <para>
+  <simpara>
    Returns the rounded value of <parameter>num</parameter> to
    specified <parameter>precision</parameter>
    (number of digits after the decimal point).
    <parameter>precision</parameter> can also be negative or zero (default).
-  </para>
+  </simpara>
  </refsect1>
 
  <refsect1 role="parameters">
   &reftitle.parameters;
   <variablelist>
-   <varlistentry>
-    <term><parameter>num</parameter></term>
-    <listitem>
-     <para>
-      The value to round.
-     </para>
-    </listitem>
-   </varlistentry>
-   <varlistentry>
-    <term><parameter>precision</parameter></term>
-    <listitem>
-     <para>
-      The optional number of decimal digits to round to.
-     </para>
-     <para>
-      If the <parameter>precision</parameter> is positive, <parameter>num</parameter> is
-      rounded to <parameter>precision</parameter> significant digits after the decimal point.
-     </para>
-     <para>
-      If the <parameter>precision</parameter> is negative, <parameter>num</parameter> is
-      rounded to <parameter>precision</parameter> significant digits before the decimal point,
-      i.e. to the nearest multiple of <code>pow(10, -$precision)</code>, e.g. for a
-      <parameter>precision</parameter> of -1 <parameter>num</parameter> is rounded to tens,
-      for a <parameter>precision</parameter> of -2 to hundreds, etc.
-     </para>
-    </listitem>
-   </varlistentry>
+   <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>
-     <para>
+     <simpara>
       Specifies the rounding mode.
-     </para>
+     </simpara>
     </listitem>
    </varlistentry>
   </variablelist>
@@ -65,9 +40,9 @@
 
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
-  <para>
-   The value rounded to the given precision, as a string.
-  </para>
+  <simpara>
+   Returns a BCMath string number representing <parameter>num</parameter> rounded to the given precision.
+  </simpara>
  </refsect1>
 
  <refsect1 role="examples">
@@ -139,7 +114,9 @@ string(1) "0"
    </screen>
   </example>
   <example>
-   <title><parameter>mode</parameter> examples</title>
+   <title>
+    Example of using <function>bcround</function> with different <parameter>mode</parameter> values
+   </title>
    <programlisting role="php">
 <![CDATA[
 <?php
@@ -192,7 +169,10 @@ string(1) "9"
    </screen>
   </example>
   <example>
-   <title><parameter>mode</parameter> with <parameter>precision</parameter> examples</title>
+   <title>
+    Example of using <function>bcround</function> with different <parameter>mode</parameter> values
+    when specifying <parameter>precision</parameter>
+   </title>
    <programlisting role="php">
 <![CDATA[
 <?php

From 1a647cc111f818c730c78cfafc33db92475950f8 Mon Sep 17 00:00:00 2001
From: Saki Takamachi <34942839+SakiTakamachi@users.noreply.github.com>
Date: Sun, 24 Nov 2024 22:29:38 +0900
Subject: [PATCH 07/12] address a comment

Co-authored-by: Niels Dossche <7771979+nielsdos@users.noreply.github.com>
---
 reference/bc/functions/bcceil.xml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/reference/bc/functions/bcceil.xml b/reference/bc/functions/bcceil.xml
index 1a70e4002e72..46faf08938e7 100644
--- a/reference/bc/functions/bcceil.xml
+++ b/reference/bc/functions/bcceil.xml
@@ -35,7 +35,7 @@
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
   <simpara>
-   Returns a BCMath string number representing <parameter>num</parameter> rounded up to the nearest integer.
+   Returns a numeric string representing <parameter>num</parameter> rounded up to the nearest integer.
   </simpara>
  </refsect1>
 

From 11c77a940118bad9ff7183b49546f1d76c16653e Mon Sep 17 00:00:00 2001
From: Saki Takamachi <34942839+SakiTakamachi@users.noreply.github.com>
Date: Sun, 24 Nov 2024 22:29:46 +0900
Subject: [PATCH 08/12] address a comment

Co-authored-by: Niels Dossche <7771979+nielsdos@users.noreply.github.com>
---
 reference/bc/functions/bcfloor.xml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/reference/bc/functions/bcfloor.xml b/reference/bc/functions/bcfloor.xml
index 37f6bab4d3b7..bcf02fe45d3e 100644
--- a/reference/bc/functions/bcfloor.xml
+++ b/reference/bc/functions/bcfloor.xml
@@ -35,7 +35,7 @@
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
   <simpara>
-   Returns a BCMath string number representing <parameter>num</parameter> rounded down to the nearest integer.
+   Returns a numeric string representing <parameter>num</parameter> rounded down to the nearest integer.
   </simpara>
  </refsect1>
 

From 77df1ae502ed6eda95f7587769c610ae49be41c8 Mon Sep 17 00:00:00 2001
From: Saki Takamachi <34942839+SakiTakamachi@users.noreply.github.com>
Date: Sun, 24 Nov 2024 22:29:55 +0900
Subject: [PATCH 09/12] address a comment

Co-authored-by: Niels Dossche <7771979+nielsdos@users.noreply.github.com>
---
 reference/bc/functions/bcround.xml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/reference/bc/functions/bcround.xml b/reference/bc/functions/bcround.xml
index c4f0e9698f61..34b55048e6a5 100644
--- a/reference/bc/functions/bcround.xml
+++ b/reference/bc/functions/bcround.xml
@@ -41,7 +41,7 @@
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
   <simpara>
-   Returns a BCMath string number representing <parameter>num</parameter> rounded to the given precision.
+   Returns a numeric string representing <parameter>num</parameter> rounded to the given precision.
   </simpara>
  </refsect1>
 

From 3d93dcec28151eef20a31520d45cefdb92d68703 Mon Sep 17 00:00:00 2001
From: Saki Takamachi <saki@php.net>
Date: Sun, 24 Nov 2024 23:27:44 +0900
Subject: [PATCH 10/12] Address comments

---
 reference/bc/functions/bcceil.xml  | 2 +-
 reference/bc/functions/bcfloor.xml | 2 +-
 reference/bc/functions/bcround.xml | 2 +-
 3 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/reference/bc/functions/bcceil.xml b/reference/bc/functions/bcceil.xml
index 46faf08938e7..e88bd7d5ec06 100644
--- a/reference/bc/functions/bcceil.xml
+++ b/reference/bc/functions/bcceil.xml
@@ -3,7 +3,7 @@
 <refentry xml:id="function.bcceil" xmlns="http://docbook.org/ns/docbook">
  <refnamediv>
   <refname>bcceil</refname>
-  <refpurpose>Round arbitrary precision number fractions up</refpurpose>
+  <refpurpose>Round up arbitrary precision number</refpurpose>
  </refnamediv>
 
  <refsect1 role="description">
diff --git a/reference/bc/functions/bcfloor.xml b/reference/bc/functions/bcfloor.xml
index bcf02fe45d3e..9235507e17ed 100644
--- a/reference/bc/functions/bcfloor.xml
+++ b/reference/bc/functions/bcfloor.xml
@@ -3,7 +3,7 @@
 <refentry xml:id="function.bcfloor" xmlns="http://docbook.org/ns/docbook">
  <refnamediv>
   <refname>bcfloor</refname>
-  <refpurpose>Round arbitrary precision number fractions down</refpurpose>
+  <refpurpose>Round down arbitrary precision number</refpurpose>
  </refnamediv>
 
  <refsect1 role="description">
diff --git a/reference/bc/functions/bcround.xml b/reference/bc/functions/bcround.xml
index 34b55048e6a5..a5ffa6acaa3e 100644
--- a/reference/bc/functions/bcround.xml
+++ b/reference/bc/functions/bcround.xml
@@ -3,7 +3,7 @@
 <refentry xml:id="function.bcround" xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude">
  <refnamediv>
   <refname>bcround</refname>
-  <refpurpose>Rounds a arbitrary precision number</refpurpose>
+  <refpurpose>Round arbitrary precision number</refpurpose>
  </refnamediv>
 
  <refsect1 role="description">

From 501f4d9f7eb50509c19a4e979addf73670778916 Mon Sep 17 00:00:00 2001
From: Saki Takamachi <saki@php.net>
Date: Mon, 25 Nov 2024 08:09:29 +0900
Subject: [PATCH 11/12] use vardump() for example

---
 reference/bc/functions/bcceil.xml  | 14 +++++++++++---
 reference/bc/functions/bcfloor.xml | 14 +++++++++++---
 2 files changed, 22 insertions(+), 6 deletions(-)

diff --git a/reference/bc/functions/bcceil.xml b/reference/bc/functions/bcceil.xml
index e88bd7d5ec06..d2e9be85e986 100644
--- a/reference/bc/functions/bcceil.xml
+++ b/reference/bc/functions/bcceil.xml
@@ -46,12 +46,20 @@
    <programlisting role="php">
 <![CDATA[
 <?php
-echo bcceil('4.3');    // '5'
-echo bcceil('9.999');  // '10'
-echo bcceil('-3.14');  // '-3'
+var_dump(bcceil('4.3'));
+var_dump(bcceil('9.999'));
+var_dump(bcceil('-3.14'));
 ?>
 ]]>
    </programlisting>
+   &example.outputs;
+   <screen role="php">
+<![CDATA[
+string(1) "5"
+string(2) "10"
+string(2) "-3"
+]]>
+   </screen>
   </example>
  </refsect1>
 
diff --git a/reference/bc/functions/bcfloor.xml b/reference/bc/functions/bcfloor.xml
index 9235507e17ed..8ed28a46e60b 100644
--- a/reference/bc/functions/bcfloor.xml
+++ b/reference/bc/functions/bcfloor.xml
@@ -46,12 +46,20 @@
    <programlisting role="php">
 <![CDATA[
 <?php
-echo bcfloor('4.3');    // '4'
-echo bcfloor('9.999');  // '9'
-echo bcfloor('-3.14');  // '-4'
+var_dump(bcfloor('4.3'));
+var_dump(bcfloor('9.999'));
+var_dump(bcfloor('-3.14'));
 ?>
 ]]>
    </programlisting>
+   &example.outputs;
+   <screen role="php">
+<![CDATA[
+string(1) "4"
+string(1) "9"
+string(2) "-4"
+]]>
+   </screen>
   </example>
  </refsect1>
 

From 5ff4071e1a6f0370fb8c10711e711e88dd3bd8d0 Mon Sep 17 00:00:00 2001
From: Saki Takamachi <saki@php.net>
Date: Mon, 25 Nov 2024 08:16:18 +0900
Subject: [PATCH 12/12] Added bcdivmod in bcdiv's seealso

---
 reference/bc/functions/bcdiv.xml | 1 +
 1 file changed, 1 insertion(+)

diff --git a/reference/bc/functions/bcdiv.xml b/reference/bc/functions/bcdiv.xml
index 685dc5e437fe..b3fb36be4282 100644
--- a/reference/bc/functions/bcdiv.xml
+++ b/reference/bc/functions/bcdiv.xml
@@ -95,6 +95,7 @@ echo bcdiv('105', '6.55957', 3);  // 16.007
   &reftitle.seealso;
   <para>
    <simplelist>
+    <member><function>bcdivmod</function></member>
     <member><function>bcmod</function></member>
     <member><function>bcmul</function></member>
    </simplelist>