RFC: Add 4 new rounding modes to round() function (#12056)

https://wiki.php.net/rfc/new_rounding_modes_to_round_function

Co-authored-by: Tim Düsterhus <[email protected]>

Author: jorgsowa

NEWS

@@ -30,6 +30,8 @@ Intl:
   . Added IntlDateFormatter::PATTERN constant. (David Carlier)
   . Fixed Numberformatter::__construct when the locale is invalid, now
     throws an exception. (David Carlier)
+  . Added NumberFormatter::ROUND_TOWARD_ZERO and ::ROUND_AWAY_FROM_ZERO as
+    aliases for ::ROUND_DOWN and ::ROUND_UP. (Jorg Sowa)
 
 MBString:
   . Added mb_trim, mb_ltrim and mb_rtrim. (Yuya Hamada)
@@ -106,7 +108,8 @@ Standard:
     (nielsdos)
   . Removed the deprecated inet_ntoa call support. (David Carlier)
   . Cast large floats that are within int range to int in number_format so
-    the precision is not lost. (Marc Bennewitz) 
+    the precision is not lost. (Marc Bennewitz)
+  . Add support for 4 new rounding modes to the round() function. (Jorg Sowa)
 
 XML:
   . Added XML_OPTION_PARSE_HUGE parser option. (nielsdos)

UPGRADING

@@ -216,6 +216,11 @@ PHP 8.4 UPGRADE NOTES
 - Intl:
   . IntlDateFormatter::__construct() throws a ValueError if the locale is invalid.
   . NumberFormatter::__construct() throws a ValueError if the locale is invalid.
+  . NumberFormatter::ROUND_TOWARD_ZERO and NumberFormatter::ROUND_AWAY_FROM_ZERO
+    have been added as aliases for NumberFormatter::ROUND_DOWN and
+    NumberFormatter::ROUND_UP to be consistent with the new PHP_ROUND_* modes.
+
+    RFC: https://wiki.php.net/rfc/new_rounding_modes_to_round_function
 
 - MBString:
   . The behavior of mb_strcut is more consistent now on invalid UTF-8 and UTF-16
@@ -252,6 +257,10 @@ PHP 8.4 UPGRADE NOTES
     has been increased from '10' to '12'.
 
     RFC: https://wiki.php.net/rfc/bcrypt_cost_2023
+  . Four new modes have been added to the round() function: PHP_ROUND_CEILING,
+    PHP_ROUND_FLOOR, PHP_ROUND_TOWARD_ZERO, PHP_ROUND_AWAY_FROM_ZERO.
+
+    RFC: https://wiki.php.net/rfc/new_rounding_modes_to_round_function
 
 ========================================
 6. New Functions

ext/intl/formatter/formatter.stub.php

@@ -44,6 +44,10 @@ class NumberFormatter
     public const int ROUND_DOWN = UNKNOWN;
     /** @cvalue UNUM_ROUND_UP */
     public const int ROUND_UP = UNKNOWN;
+    /** @cvalue UNUM_ROUND_DOWN */
+    public const int ROUND_TOWARD_ZERO = UNKNOWN;
+    /** @cvalue UNUM_ROUND_UP */
+    public const int ROUND_AWAY_FROM_ZERO = UNKNOWN;
     /** @cvalue UNUM_ROUND_HALFEVEN */
     public const int ROUND_HALFEVEN = UNKNOWN;
     /** @cvalue UNUM_ROUND_HALFDOWN */

ext/intl/formatter/formatter_arginfo.h

@@ -0,0 +1,33 @@
+--TEST--
+NumberFormatter: rounding modes
+--EXTENSIONS--
+intl
+--FILE--
+<?php
+ini_set("intl.error_level", E_WARNING);
+
+var_dump(NumberFormatter::ROUND_CEILING);
+var_dump(NumberFormatter::ROUND_FLOOR);
+var_dump(NumberFormatter::ROUND_DOWN);
+var_dump(NumberFormatter::ROUND_TOWARD_ZERO);
+var_dump(NumberFormatter::ROUND_UP);
+var_dump(NumberFormatter::ROUND_AWAY_FROM_ZERO);
+var_dump(NumberFormatter::ROUND_HALFEVEN);
+var_dump(NumberFormatter::ROUND_HALFDOWN);
+var_dump(NumberFormatter::ROUND_HALFUP);
+
+var_dump(NumberFormatter::ROUND_DOWN === NumberFormatter::ROUND_TOWARD_ZERO);
+var_dump(NumberFormatter::ROUND_UP === NumberFormatter::ROUND_AWAY_FROM_ZERO);
+?>
+--EXPECTF--
+int(0)
+int(1)
+int(2)
+int(2)
+int(3)
+int(3)
+int(4)
+int(5)
+int(6)
+bool(true)
+bool(true)

ext/intl/tests/formatter/rounding_modes.phpt

@@ -375,6 +375,26 @@
  * @cvalue PHP_ROUND_HALF_ODD
  */
 const PHP_ROUND_HALF_ODD = UNKNOWN;
+/**
+ * @var int
+ * @cvalue PHP_ROUND_CEILING
+ */
+const PHP_ROUND_CEILING = UNKNOWN;
+/**
+ * @var int
+ * @cvalue PHP_ROUND_FLOOR
+ */
+const PHP_ROUND_FLOOR = UNKNOWN;
+/**
+ * @var int
+ * @cvalue PHP_ROUND_TOWARD_ZERO
+ */
+const PHP_ROUND_TOWARD_ZERO = UNKNOWN;
+/**
+ * @var int
+ * @cvalue PHP_ROUND_AWAY_FROM_ZERO
+ */
+const PHP_ROUND_AWAY_FROM_ZERO = UNKNOWN;
 
 /* crypt.c */
 

ext/standard/basic_functions.stub.php

@@ -126,6 +126,30 @@ static inline double php_round_helper(double value, int mode) {
 
 			return integral;
 
+		case PHP_ROUND_CEILING:
+			if (value > 0.0 && fractional > 0.0) {
+				return integral + 1.0;
+			}
+
+			return integral;
+
+		case PHP_ROUND_FLOOR:
+			if (value < 0.0 && fractional > 0.0) {
+				return integral - 1.0;
+			}
+
+			return integral;
+
+		case PHP_ROUND_TOWARD_ZERO:
+			return integral;
+
+		case PHP_ROUND_AWAY_FROM_ZERO:
+			if (fractional > 0.0) {
+				return integral + copysign(1.0, integral);
+			}
+
+			return integral;
+
 		case PHP_ROUND_HALF_EVEN:
 			if (fractional > 0.5) {
 				return integral + copysign(1.0, integral);
@@ -143,6 +167,7 @@ static inline double php_round_helper(double value, int mode) {
 			}
 
 			return integral;
+
 		case PHP_ROUND_HALF_ODD:
 			if (fractional > 0.5) {
 				return integral + copysign(1.0, integral);
@@ -157,6 +182,7 @@ static inline double php_round_helper(double value, int mode) {
 			}
 
 			return integral;
+
 		EMPTY_SWITCH_DEFAULT_CASE();
 	}
 	// FIXME: GCC bug, branch is considered reachable.
@@ -340,6 +366,10 @@ PHP_FUNCTION(round)
 		case PHP_ROUND_HALF_DOWN:
 		case PHP_ROUND_HALF_EVEN:
 		case PHP_ROUND_HALF_ODD:
+		case PHP_ROUND_AWAY_FROM_ZERO:
+		case PHP_ROUND_TOWARD_ZERO:
+		case PHP_ROUND_CEILING:
+		case PHP_ROUND_FLOOR:
 			break;
 		default:
 			zend_argument_value_error(3, "must be a valid rounding mode (PHP_ROUND_*)");

ext/standard/basic_functions_arginfo.h

@@ -103,7 +103,7 @@ PHPAPI zend_string * _php_math_zvaltobase(zval *arg, int base);
 #endif
 
 #ifndef PHP_ROUND_HALF_DOWN
-#define PHP_ROUND_HALF_DOWN      0x02    /* Down == towards zero */
+#define PHP_ROUND_HALF_DOWN      0x02    /* Arithmetic rounding, down == towards zero */
 #endif
 
 #ifndef PHP_ROUND_HALF_EVEN
@@ -114,4 +114,20 @@ PHPAPI zend_string * _php_math_zvaltobase(zval *arg, int base);
 #define PHP_ROUND_HALF_ODD       0x04
 #endif
 
+#ifndef PHP_ROUND_CEILING
+#define PHP_ROUND_CEILING        0x05
+#endif
+
+#ifndef PHP_ROUND_FLOOR
+#define PHP_ROUND_FLOOR          0x06
+#endif
+
+#ifndef PHP_ROUND_TOWARD_ZERO
+#define PHP_ROUND_TOWARD_ZERO    0x07
+#endif
+
+#ifndef PHP_ROUND_AWAY_FROM_ZERO
+#define PHP_ROUND_AWAY_FROM_ZERO 0x08
+#endif
+
 #endif /* PHP_MATH_H */