[RFC] Add clamp function

2025-08-22 at 22:29, Morgan <Weedpacket@varteg.nz
mailto:Weedpacket@varteg.nz> wrote:

 >
 > Also from my point of view,  min($max, max($min, $value)) has a
counter-
 > intuitive reading when used to clamp a value.

Well, that's trivial to deal with:

min(max($min, $value), $max));

It's not just about the order of parameters, it's still not intuitive to
call max() with $min and min() with $max, you still have to think about
what it does step by step to make sense out of it, while clamp($value,
min: $min, $max) or clamp(min: $min, value: $value, max: $max) will
provide a syntax that immediately make sense for next reader.

Well, clamp(min,value,max) isn't that far from minmax(min,value,max) and
then chuck a couple more parentheses in there. Still,

Like the author of the RFC v1 also mentioned, min(max()) is inefficient
(see the inner complexity of those functions).

Yes, min/max are regarded as array functions, and doesn't special-case
the situation where two arguments are passed; no particular reason why
that couldn't be done as it seems to be a common use case. Otherwise,
the bulk of the complexity comes from type handling and that won't go
away in a robust implementation of clamp.

Note that I am not against introducing clamp(). It's certainly not going
to hurt to write clamp(min:$min, value:$value, max:$max) instead of
min(max($min, $value), $max). I'm going to have to remember to put the
parameter names in, because "$min <= $value <= $max" seems by far the
most natural ordering (and is how "this value lies between these two
extremes" is written in maths).

There is also the use case of returning something other than $min if
$value<$min (and other than $max if $value>$max), allowing clamp to
filter values that are within the range or too high or too low. That
would mean another one or two optional parameters.

For numeric values there's also the closely related rescale() function,
which is basically rescale($value, $min, $max) = ($value - $min) / ($max

• $min) (it maps the interval [0,1] to [$min,$max] and finds where
  $value gets carried to by the mapping). Again, a couple more parameters
  would allow specifying initial intervals other than [0,1].

2025-08-23 at 12:06, Rob Landers rob@bottled.codes wrote:

About "What determines comparability", it follows the usual rules of
PHP: https://www.php.net/manual/en/language.operators.comparison.php

So it's equivalent to ($value < $min) ? $min : (($value > $max) ? $max
: $value) and also equivalent to min($max, max($min, $value))

About clamp(new Point(1, 2), new Point(0, 0), new Point(5, 5));

If Point is a comparable value (simple DTO for example), it should
return $value, like when doing ($value < $min) ? $min : (($value >
$max) ? $max : $value) we could add a test for such case, but I think
that for consistency, whatever currently works in min() should work in
clamp()

Following the link of the implementation, there is also a link to the
documentation where I already explained the comparison rules following
the example of what was done in the documentation for min() and max():
https://github.com/php/doc-en/pull/4814

Please make sure the above is captured in the RFC.

Though apparently what PHP currently does with Point comparisons in
min/max is... weird. I don't even know what the logic here is. :)

https://3v4l.org/pTmiV

(No need to change it in this RFC, just note explicitly that the expected
behavior is identical to that min(max()) construct, regardless of type.)

--Larry Garfield

It only compares the first property, and if there is a conflict, it moves
on to the next property. That is why some of us have been advocating for
operator overrides: because this default isn’t always appropriate, as your
Point example illustrates. In some cases, you would want to compare
magnitude or something else entirely, not just the x value.

What is even trickier is that this process completely ignores computed
hooks. So, if you add a hook as the first property (for example, returning
the magnitude), it is simply ignored. As a weird side note: if you cast the
object to an array, the computed hook disappears, but if you use
json_encode(), the computed value is included.

To complicate things further, the current behaviour for objects is
actually “undefined” and it isn’t documented. There are examples that show
how objects are compared, but they don’t explicitly mention that the object
is being cast to an array (see the above paragraph on why that matters).
Because this relies on implementation details rather than documented
behaviour, it could change between PHP versions without an RFC. That makes
relying on it a bit risky.

Adding operator overrides would help by making this behaviour explicit and
consistent across versions, or just defining it in general. But whenever
someone tries to define this more clearly (as I started to do with
Records), it tends to run into resistance on this list for reasons I’ve
never quite understood.

— Rob

I would not be against operator overrides, though it starts becoming quite
complex when dealing with comparing 2 objects of different classes. Anyway
I will add a note on the RFC about objects to warn about unexpected
behavior, but this is probably out of scope, the same concerns apply to
min() and max() and that's why I added the same warning in the
documentation: "Be careful when passing arguments of different types
because clamp can produce unpredictable results." Adding a specific note
about objects in the documentation could make sense. Then it would probably
be nice if it were also added to min() and max().