From 1b1ac7b4e0b92f7affdf0394ce02c28de65e8f67 Mon Sep 17 00:00:00 2001 From: kylekatarnls Date: Sun, 10 Aug 2025 18:31:27 +0200 Subject: [PATCH] Document clamp function --- appendices/migration86/new-functions.xml | 34 +++++ reference/array/versions.xml | 1 + reference/math/functions/clamp.xml | 151 +++++++++++++++++++++++ 3 files changed, 186 insertions(+) create mode 100644 appendices/migration86/new-functions.xml create mode 100644 reference/math/functions/clamp.xml diff --git a/appendices/migration86/new-functions.xml b/appendices/migration86/new-functions.xml new file mode 100644 index 000000000000..b25832bec694 --- /dev/null +++ b/appendices/migration86/new-functions.xml @@ -0,0 +1,34 @@ + + + New Functions + + + Core + + + + clamp + + + + + diff --git a/reference/array/versions.xml b/reference/array/versions.xml index 8017e8852e16..984f70c874f4 100644 --- a/reference/array/versions.xml +++ b/reference/array/versions.xml @@ -66,6 +66,7 @@ + diff --git a/reference/math/functions/clamp.xml b/reference/math/functions/clamp.xml new file mode 100644 index 000000000000..111670f5e0de --- /dev/null +++ b/reference/math/functions/clamp.xml @@ -0,0 +1,151 @@ + + + + + clamp + Return the given value if in range, else return the nearest bound + + + &reftitle.description; + + mixedclamp + mixedvalue + mixedmin + mixedmax + + + Return the given value if in range of min and max. + Else if it's lower than min, return min. + Else return max. + + + + Values of different types will be compared using the + standard comparison rules. For instance, a non-numeric string will be + compared to an int as though it were 0, but multiple non-numeric + string values will be compared alphanumerically. The actual value returned will be of the + original type with no conversion applied. + + + + + Be careful when passing arguments of different types because + clamp can produce unpredictable results. + + + + + &reftitle.parameters; + + + + value + + + Any comparable + value to be clamped between min and max. + + + + + min + + + A comparable minimum to limit + the value to. + + + + + max + + + A comparable maximum to limit + the value to. + + + + + + + + &reftitle.returnvalues; + + clamp returns the parameter value if + considered "between" min and max according to standard + comparisons. + + + If value is NAN, then the returned value will also be + NAN. + + + + + &reftitle.errors; + + If min is greater than max, + clamp throws a ValueError. + + + If min or max is NAN, + clamp throws a ValueError. + + + + + &reftitle.examples; + + + Example uses of <function>clamp</function> + +format('Y-m-d'), PHP_EOL; // 2025-08-15 +?> +]]> + + + + + + + &reftitle.seealso; + + + min + max + + + + +