From ae148826a6830492a51e47f21e1ad4f80373f2a6 Mon Sep 17 00:00:00 2001
From: Jim Winstead <jimw@trainedmonkey.com>
Date: Sun, 1 Dec 2024 11:38:35 -0800
Subject: [PATCH] Document number_format() handling of negative $decimals
 (closes #4200) (#4201)

Co-authored-by: Gina Peter Banyard <girgias@php.net>
---
 reference/strings/functions/number-format.xml | 37 +++++++++++++++++++
 1 file changed, 37 insertions(+)

diff --git a/reference/strings/functions/number-format.xml b/reference/strings/functions/number-format.xml
index ee6c19be0eab..5220842b2ca2 100644
--- a/reference/strings/functions/number-format.xml
+++ b/reference/strings/functions/number-format.xml
@@ -39,6 +39,11 @@
        Sets the number of decimal digits.
        If <literal>0</literal>, the <parameter>decimal_separator</parameter> is
        omitted from the return value.
+       As of PHP 8.3.0, when the value is negative, <parameter>num</parameter>
+       is rounded to <parameter>decimals</parameter> significant digits before
+       the decimal point.
+       Prior to PHP 8.3.0, negative values were ignored and handled the
+       same as <literal>0</literal>.
       </para>
      </listitem>
     </varlistentry>
@@ -81,6 +86,12 @@
       </row>
      </thead>
      <tbody>
+      <row>
+       <entry>8.3.0</entry>
+       <entry>
+        Added handling of negative values for <parameter>decimals</parameter>.
+       </entry>
+      </row>
       <row>
        <entry>8.0.0</entry>
        <entry>
@@ -137,6 +148,32 @@ $english_format_number = number_format($number, 2, '.', '');
     </programlisting>
    </example>
   </para>
+  <example>
+   <title>A negative value for <parameter>decimals</parameter></title>
+   <simpara>
+    As of PHP 8.3.0, a negative value for <parameter>decimals</parameter>
+    is used to round the number of significant digits before the decimal
+    point.
+   </simpara>
+   <programlisting role="php">
+<![CDATA[
+<?php
+$number = "1234.5678";
+var_dump(number_format($number, -1));
+var_dump(number_format($number, -2));
+var_dump(number_format($number, -3));
+?>
+]]>
+   </programlisting>
+   &example.outputs;
+   <screen>
+<![CDATA[
+string(5) "1,230"
+string(5) "1,200"
+string(5) "1,000"
+]]>
+   </screen>
+  </example>
  </refsect1>
  
  <refsect1 role="seealso">