From da622bb6770f58d0d026245eb81f09c20a68ce87 Mon Sep 17 00:00:00 2001
From: David Carlier <devnexen@gmail.com>
Date: Sat, 31 Jan 2026 21:07:33 +0000
Subject: [PATCH] Add example demonstrating ROUNDING_MODE with ROUND_DOWN

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 <noreply@anthropic.com>
---
 .../intl/numberformatter/set-attribute.xml    | 39 +++++++++++++++++++
 1 file changed, 39 insertions(+)

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">