[RFC] Add clamp function

ext/standard/basic_functions.stub.php

@@ -1044,6 +1044,8 @@ function mail(string $to, string $subject, string $message, array|string $additi
 
 function abs(int|float $num): int|float {}
 
+function clamp(int|float $num, int|float $min, int|float $max): int|float {}
+
 function ceil(int|float $num): float {}
 
 function floor(int|float $num): float {}

ext/standard/basic_functions_arginfo.h

@@ -1603,6 +1603,12 @@ ZEND_BEGIN_ARG_WITH_RETURN_TYPE_MASK_EX(arginfo_abs, 0, 1, MAY_BE_LONG|MAY_BE_DO
 	ZEND_ARG_TYPE_MASK(0, num, MAY_BE_LONG|MAY_BE_DOUBLE, NULL)
 ZEND_END_ARG_INFO()
 
+ZEND_BEGIN_ARG_WITH_RETURN_TYPE_MASK_EX(arginfo_clamp, 0, 3, MAY_BE_LONG|MAY_BE_DOUBLE)
+	ZEND_ARG_TYPE_MASK(0, num, MAY_BE_LONG|MAY_BE_DOUBLE, NULL)
+	ZEND_ARG_TYPE_MASK(0, min, MAY_BE_LONG|MAY_BE_DOUBLE, NULL)
+	ZEND_ARG_TYPE_MASK(0, max, MAY_BE_LONG|MAY_BE_DOUBLE, NULL)
+ZEND_END_ARG_INFO()
+
 ZEND_BEGIN_ARG_WITH_RETURN_TYPE_INFO_EX(arginfo_ceil, 0, 1, IS_DOUBLE, 0)
 	ZEND_ARG_TYPE_MASK(0, num, MAY_BE_LONG|MAY_BE_DOUBLE, NULL)
 ZEND_END_ARG_INFO()
@@ -2657,6 +2663,7 @@ ZEND_FUNCTION(link);
 #endif
 ZEND_FUNCTION(mail);
 ZEND_FUNCTION(abs);
+ZEND_FUNCTION(clamp);
 ZEND_FUNCTION(ceil);
 ZEND_FUNCTION(floor);
 ZEND_FUNCTION(round);
@@ -3298,6 +3305,7 @@ static const zend_function_entry ext_functions[] = {
 #endif
 	ZEND_FE(mail, arginfo_mail)
 	ZEND_FE(abs, arginfo_abs)
+	ZEND_FE(clamp, arginfo_clamp)
 	ZEND_FE(ceil, arginfo_ceil)
 	ZEND_FE(floor, arginfo_floor)
 	ZEND_FE(round, arginfo_round)

ext/standard/math.c

@@ -228,6 +228,48 @@ PHP_FUNCTION(abs)
 }
 /* }}} */
 
+/* {{{ Return the given value if in range of min and max */
+PHP_FUNCTION(clamp)
+{
+	zval *zvalue, *zmin, *zmax;
+
+	ZEND_PARSE_PARAMETERS_START(3, 3)
+		Z_PARAM_NUMBER(zvalue)
+		Z_PARAM_NUMBER(zmin)
+		Z_PARAM_NUMBER(zmax)
+	ZEND_PARSE_PARAMETERS_END();
+
+	if (Z_TYPE_P(zmin) == IS_DOUBLE) {
+		if (UNEXPECTED(zend_isnan(Z_DVAL_P(zmin)))) {
+			zend_argument_type_error(2, "cannot be of type NAN");
+			RETURN_THROWS();
+		}
+	} else if (Z_TYPE_P(zmax) == IS_DOUBLE) {
+		if (UNEXPECTED(zend_isnan(Z_DVAL_P(zmax)))) {
+			zend_argument_type_error(3, "cannot be of type NAN");
+			RETURN_THROWS();
+		}
+	} else if (Z_TYPE_P(zvalue) == IS_DOUBLE) {
+		if (UNEXPECTED(zend_isnan(Z_DVAL_P(zvalue)))) {
+			RETURN_COPY(zvalue);
+		}
+	}
+
+	if (zend_compare(zmax, zmin) == -1) {
+		zend_argument_value_error(2, "cannot be greater than Argument #3 ($max)");
+		RETURN_THROWS();
+	}
+
+	if (zend_compare(zmax, zvalue) == -1) {
+		RETURN_COPY(zmax);
+	} else if (zend_compare(zmin, zvalue) == -1) {
+		RETURN_COPY(zvalue);
+	} else {
+		RETURN_COPY(zmin);
+	}
+}
+/* }}} */
+
 /* {{{ Returns the next highest integer value of the number */
 PHP_FUNCTION(ceil)
 {

ext/standard/tests/math/clamp_basic1.phpt

@@ -0,0 +1,57 @@
+--TEST--
+Test clamp() function : basic functionality 01
+--FILE--
+<?php
+echo "*** Testing clamp() : basic functionality 01 ***\n";
+
+var_dump(clamp(0, 1, 2));
+var_dump(clamp(2, 1, 3));
+var_dump(clamp(3, 1, 4));
+var_dump(clamp(5, 1, 4));
+var_dump(clamp(5, 1, 5));
+var_dump(clamp(0.0, 1.0, 2.0));
+var_dump(clamp(1.5, 1.0, 2.0));
+var_dump(clamp(2.0, 1.0, 2.5));
+var_dump(clamp(3.0, 1.0, 2.5));
+var_dump(clamp(0, 3.0, 3.5));
+
+try {
+    var_dump(clamp(5, 5, 1));
+} catch (\ValueError $e) {
+    echo $e->getMessage(), "\n";
+}
+
+try {
+    var_dump(clamp(1, 3.5, 3.0));
+} catch (\ValueError $e) {
+    echo $e->getMessage(), "\n";
+}
+
+var_dump(clamp(0, null, 3.5));
+
+try {
+    var_dump(clamp(5, 1, null));
+} catch (\ValueError $e) {
+    echo $e->getMessage(), "\n";
+}
+?>
+--EXPECTF--
+*** Testing clamp() : basic functionality 01 ***
+int(1)
+int(2)
+int(3)
+int(4)
+int(5)
+float(1)
+float(1.5)
+float(2)
+float(2.5)
+float(3)
+clamp(): Argument #2 ($min) cannot be greater than Argument #3 ($max)
+clamp(): Argument #2 ($min) cannot be greater than Argument #3 ($max)
+
+Deprecated: clamp(): Passing null to parameter #2 ($min) of type int|float is deprecated in %s on line %d
+int(0)
+
+Deprecated: clamp(): Passing null to parameter #3 ($max) of type int|float is deprecated in %s on line %d
+clamp(): Argument #2 ($min) cannot be greater than Argument #3 ($max)

ext/standard/tests/math/clamp_basic2.phpt

@@ -0,0 +1,55 @@
+--TEST--
+Test clamp() function : basic functionality 02
+--FILE--
+<?php
+echo "*** Testing clamp() : basic functionality 02 ***\n";
+
+var_dump(clamp(0, 0.0, 2));
+var_dump(clamp(0.0, 0, 2));
+try {
+    var_dump(clamp(0.0, NAN, 2));
+} catch (\TypeError $e) {
+    echo $e->getMessage(), "\n";
+}
+try {
+    var_dump(clamp(INF, NAN, 2));
+} catch (\TypeError $e) {
+    echo $e->getMessage(), "\n";
+}
+var_dump(clamp(0x10, 0x01, 2));
+var_dump(clamp(10, "-2.345e1", 2.345e1));
+var_dump(clamp(24.0, 027, 25));
+var_dump(clamp(2.345e1, "-2.345e1", 2.345e1));
+var_dump(clamp(0.0, null, 2));
+var_dump(clamp(0.0, null, null));
+var_dump(clamp(0.0, null, false));
+try {
+    var_dump(clamp(INF, false, NAN));
+} catch (\TypeError $e) {
+    echo $e->getMessage(), "\n";
+}
+var_dump(clamp(NAN, 0, 2));
+?>
+--EXPECTF--
+*** Testing clamp() : basic functionality 02 ***
+float(0)
+int(0)
+clamp(): Argument #2 ($min) cannot be of type NAN
+clamp(): Argument #2 ($min) cannot be of type NAN
+int(2)
+int(10)
+float(24)
+float(23.45)
+
+Deprecated: clamp(): Passing null to parameter #2 ($min) of type int|float is deprecated in %s on line %d
+int(0)
+
+Deprecated: clamp(): Passing null to parameter #2 ($min) of type int|float is deprecated in %s on line %d
+
+Deprecated: clamp(): Passing null to parameter #3 ($max) of type int|float is deprecated in %s on line %d
+int(0)
+
+Deprecated: clamp(): Passing null to parameter #2 ($min) of type int|float is deprecated in %s on line %d
+int(0)
+clamp(): Argument #3 ($max) cannot be of type NAN
+float(NAN)