round関係のenのupdateに追随 (#263)

Author: SakiTakamachi

reference/bc/bcmath/number/round.xml

@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="utf-8"?>
 <!-- $Revision$ -->
-<!-- EN-Revision: a414ee95eb79e2c62c80827a46e15da5d15af97e Maintainer: saki Status: ready -->
+<!-- EN-Revision: 15b93836d93f01ea6d90a68cacf04ce0d9fb8eff Maintainer: saki Status: ready -->
 
 <refentry xml:id="bcmath-number.round" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude">
  <refnamediv>
@@ -26,11 +26,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>
-      指定する丸めモード。
+      指定する丸めモード。詳しくは <enumname>RoundingMode</enumname> を参照してください。
      </simpara>
     </listitem>
    </varlistentry>

reference/bc/functions/bcround.xml

@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="utf-8"?>
 <!-- $Revision$ -->
-<!-- EN-Revision: a414ee95eb79e2c62c80827a46e15da5d15af97e Maintainer: saki Status: ready -->
+<!-- EN-Revision: 15b93836d93f01ea6d90a68cacf04ce0d9fb8eff Maintainer: saki Status: ready -->
 
 <refentry xml:id="function.bcround" xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude">
  <refnamediv>
@@ -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>
-      指定する丸めモード。
-     </simpara>
-    </listitem>
-   </varlistentry>
+   <xi:include xpointer="bcmath-number.round..parameters.mode" />
   </variablelist>
  </refsect1>
 

reference/math/functions/round.xml

@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="utf-8"?>
 <!-- $Revision$ -->
-<!-- EN-Revision: 6406cc6c50f8f66f7d55f550dc1ec2759e2eca0f Maintainer: hirokawa Status: ready -->
+<!-- EN-Revision: 15b93836d93f01ea6d90a68cacf04ce0d9fb8eff Maintainer: hirokawa Status: ready -->
 <!-- CREDITS: takagi,mumumu -->
 <refentry xml:id="function.round" xmlns="http://docbook.org/ns/docbook">
  <refnamediv>
@@ -13,7 +13,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>
    <parameter>num</parameter> を、指定した
@@ -76,7 +76,7 @@
      <term><parameter>mode</parameter></term>
      <listitem>
       <para>
-       次の定数のいずれかを使って、丸めのモードを指定します。
+       <enumname>RoundingMode</enumname> もしくは次の定数のいずれかを使って、丸めのモードを指定します。
        <informaltable>
         <tgroup cols="2">
          <thead>
@@ -121,6 +121,7 @@
          </tbody>
         </tgroup>
        </informaltable>
+       ただし、新規に追加されたいくつかのモードは <enumname>RoundingMode</enumname> にのみ存在します。
       </para>
      </listitem>
     </varlistentry>
@@ -134,6 +135,14 @@
   </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>
@@ -145,6 +154,18 @@
      </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>
@@ -314,6 +335,61 @@ 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>