[DOC-CVS] [doc-en] master: Add example demonstrating ROUNDING_MODE with ROUND_DOWN (#5235)

Author: David CARLIER (devnexen)
Committer: GitHub (web-flow)
Pusher: devnexen
Date: 2026-03-26T11:46:53Z

Commit: https://github.com/php/doc-en/commit/89b92b42cc3fcbd4481f454139beb20ba3328be2
Raw diff: https://github.com/php/doc-en/commit/89b92b42cc3fcbd4481f454139beb20ba3328be2.diff

Add example demonstrating ROUNDING_MODE with ROUND_DOWN (#5235)

Add a code example showing how to use NumberFormatter::ROUNDING_MODE
with NumberFormatter::ROUND_DOWN to truncate values to a specified
number of fraction digits without rounding.

This addresses user confusion about how to truncate rather than round
values when using FRACTION_DIGITS.

See: https://github.com/php/php-src/issues/21048

Co-authored-by: Claude Opus 4.5 <[email protected]>

Changed paths:
  M  reference/intl/numberformatter/set-attribute.xml


Diff:

diff --git a/reference/intl/numberformatter/set-attribute.xml b/reference/intl/numberformatter/set-attribute.xml
index dcc64e69d310..075f37aaa8f7 100644
--- a/reference/intl/numberformatter/set-attribute.xml
+++ b/reference/intl/numberformatter/set-attribute.xml
@@ -116,6 +116,45 @@ Digits: 2
 1.234.567,89
 ]]>
   </screen>
+  <example>
+   <title>Using <constant>NumberFormatter::ROUNDING_MODE</constant> to truncate values</title>
+   <simpara>
+    By default, <classname>NumberFormatter</classname> rounds values. Using
+    <constant>NumberFormatter::ROUND_DOWN</constant> as the
+    <constant>NumberFormatter::ROUNDING_MODE</constant> truncates
+    the value to the specified number of fraction digits without rounding.
+   </simpara>
+   <programlisting role="php">
+<![CDATA[
+<?php
+$fmt = new NumberFormatter('en_US', NumberFormatter::DECIMAL);
+$fmt->setAttribute(NumberFormatter::FRACTION_DIGITS, 2);
+
+echo "Default rounding mode:\n";
+echo $fmt->format(3.789), "\n"; // 3.79 (rounded up)
+echo $fmt->format(3.781), "\n"; // 3.78 (rounded down)
+
+$fmt->setAttribute(NumberFormatter::ROUNDING_MODE, NumberFormatter::ROUND_DOWN);
+
+echo "\nWith ROUND_DOWN (truncate):\n";
+echo $fmt->format(3.789), "\n"; // 3.78 (truncated)
+echo $fmt->format(3.781), "\n"; // 3.78 (truncated)
+?>
+]]>
+   </programlisting>
+   &example.outputs;
+   <screen>
+<![CDATA[
+Default rounding mode:
+3.79
+3.78
+
+With ROUND_DOWN (truncate):
+3.78
+3.78
+]]>
+   </screen>
+  </example>
  </refsect1>
 
  <refsect1 role="seealso">