Re: [RFC] Add clamp function

2025-08-22 at 18:09, Larry Garfield <larry@garfieldtech.com> wrote: > On Fri, Aug 22, 2025, at 3:01 AM, Kyle Katarn wrote: > > 2025-08-20 at 14:28, Christoph M. Becker <cmbecker69@gmx.de> wrote : > >> On 20.08.2025 at 09:29, Kyle Katarn wrote: > >> > >> > 2025-08-19 14:59, Tim Düsterhus <tim@bastelstu.be> wrote :>>> > >> > > https://wiki.php.net/rfc/howto#external_resources#rfcs_belong_to_a_single_author > < > > https://wiki.php.net/rfc/howto#external_resources%23rfcs_belong_to_a_single_author > > > >> >> (the "RFCs 'belong' to a single author") section. The > >> >> existing RFC > may > >> >> only be adjusted with the original author’s consent. It might be > easiest > >> >> for you to create a “clamp function v2” RFC instead.. > >> > > >> > Thanks, when I go to > >> > https://wiki.php.net/RFC/clamp-v2 and click > "Edit the > >> > page", it says: > >> > "Sorry, you don't have enough rights to continue." > >> > > >> > Can you grant me this permission? Thanks. > >> > >> I've granted RFC karma to the kylekatarnls account; there is also a > >> kylek account, though? Can that be removed? > >> > >> Christoph > > > > Thanks, yes "kylek" account can be removed. > > > > I created https://wiki.php.net/rfc/clamp_v2 (re-using most > > of the info > > from https://wiki.php.net/rfc/clamp). > > > > Thanks for you > > The grammar in this one sentence is very clumsy: > > > clamp takes three arguments, a $num, $min and $max, checks if $num is > within the bounds of $min and $max, if in range, returns the value of $num, > otherwise, returns the nearest bound value, i.e. if $num > $max return > $max, if $num < $min return $min. > > Please break it up into multiple sentences so it's easier to follow. I > think I follow it, but it's clunky enough that I am not certain of it. :-) > > Also, the text says $num but the code example says $value. > > What determines comparability? What happens if you try to clamp values > that are not comparable? Eg: > > clamp(new Point(1, 2), new Point(0, 0), new Point(5, 5)); > > I assume that will fail somehow, but the failure should be described > explicitly. > > --Larry Garfield > Ah true, $num was v1 when it accepted only int|float, I switched to $value since it's now mixed. 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