Everything
php
Learn Community Releases The PHP Project
Home » Project » Newsgroups » php.internals » Proposal: clamp »

Proposal: clamp

php.internals

Kim Hallberg

5 years ago
Greetings internals, I present to you a proposal for a new basic math function: clamp. The main goal of this function is to contain a number inside a given bound. And return the number if it is inside of that bound, and if not, and the number is outside of the given bound, the nearest bound is returned. Now, does this need an RFC? The behaviour can be implemented in userland in a number of ways, one of which is to compare the values in a if statement. Another is to use the min and max math functions. max($min, min($max, $num)); I don’t have any schpeel as to why this should be in core, only that I thought it already was. Considering it is part of other languages standard math library, and it is a useful function. Can see this being useful in image manipulation, server-side rendering and math just to name few. The proposed signature follows the convention of other math related functions. function clamp(int|float $num, int|float $min, int|float $max): int|float {} This function is very easy to implement, has no side effects or backward compatibility issues, unless a userland implementation already has the function declared, in which case PHP will throw a fatal error since the function cannot be redeclared. I've implemented this feature a few months ago already. - Link: https://github.com/thinkverse/php-src/pull/1 <https://github.com/thinkverse/php-src/pull/1> What are your opinions on this function? Regards, Kim Hallberg.

Marco Pivetta

5 years ago
Hey Kim On Wed, Jun 23, 2021, 02:25 Kim Hallberg <hallbergkim@gmail.com> wrote:
> This function is very easy to implement, has no side effects or backward > compatibility issues, unless a userland implementation already has the > function declared, >
I like the function, the name, and its simplicity. The problem is exactly the fact that it is trivial to implement in userland: why not do it there instead?

Lynn

5 years ago
On Wed, Jun 23, 2021 at 3:07 AM Marco Pivetta <ocramius@gmail.com> wrote:
> The problem is exactly the fact that it is trivial to implement in > userland: why not do it there instead? >
My 2cents: because people won't use it when the barrier is too high to get it. There are a ton of great libraries that have functionality like clamp, and some more elaborate, like an array replacement. In the end -based on my experience- people go to the php documentation and look for functions that they can use, or they use their IDE autocomplete functionality to see what's hinted at. Having these functions spread through the ecosystem means discoverability is low. I've needed the "clamp" function in the past and didn't even consider looking for a library to do this for me. Why would I even install a library to have a single function anyway? It feels like a massive overhead. I've seen coworkers use funky SPL functionality I didn't even know existed to avoid using external dependencies that have already solved their problem in a neat way, which were in fact already installed through composer. They found the solution through google and ended up in the official php documentation. I'd love to see these small additions in the core, they make the language feel more complete. The fact that they are easy to implement in userland means that we can have great forward compatibility through polyfills and already start using them in codebases that haven't been upgraded yet to the latest PHP version. I've been very happy to have been able to use str_starts_with, str_ends_with, and str_contains in 7.3, as they came in with a generic php polyfill. With a "see also: clamp" in the min/max function documentation, this would be easy to find as well.

Pierre

5 years ago
Le 23/06/2021 à 10:28, Lynn a écrit :
> On Wed, Jun 23, 2021 at 3:07 AM Marco Pivetta <ocramius@gmail.com> wrote: > >> The problem is exactly the fact that it is trivial to implement in >> userland: why not do it there instead? >> > My 2cents: because people won't use it when the barrier is too high to get > it. There are a ton of great libraries that have functionality like clamp, > and some more elaborate, like an array replacement. In the end -based on my > experience- people go to the php documentation and look for functions that > they can use, or they use their IDE autocomplete functionality to see > what's hinted at. Having these functions spread through the ecosystem means > discoverability is low. I've needed the "clamp" function in the past and > didn't even consider looking for a library to do this for me. Why would I > even install a library to have a single function anyway? It feels like a > massive overhead. I've seen coworkers use funky SPL functionality I didn't > even know existed to avoid using external dependencies that have already > solved their problem in a neat way, which were in fact already installed > through composer. They found the solution through google and ended up in > the official php documentation. > > I'd love to see these small additions in the core, they make the language > feel more complete. The fact that they are easy to implement in userland > means that we can have great forward compatibility through polyfills and > already start using them in codebases that haven't been upgraded yet to the > latest PHP version. I've been very happy to have been able to use > str_starts_with, str_ends_with, and str_contains in 7.3, as they came in > with a generic php polyfill. > > With a "see also: clamp" in the min/max function documentation, this would > be easy to find as well. >
+1 for this, I often use the min/max pattern to achieve the same result, having a single method would be much more readable. Regards,
-- Pierre

Ilija Tovilo

5 years ago
Hi Kim
> I present to you a proposal for a new basic math function: clamp. > ... > What are your opinions on this function?
I for one think this is a good candidate for PHPs standard library. It's simple, unopinionated and standardized in other languages. Even though it's simple to implement in userland (as many other internal functions would be) there's no good reason to require users to implement it themselves or require a package for simple functions. +1 from me. Ilija

Ayesh - PHP.Watch

5 years ago
> Greetings internals, > > I present to you a proposal for a new basic math function: clamp. > > The main goal of this function is to contain a number inside a given bound. > And return the number if it is inside of that bound, and if not, and the > number is outside of the given bound, the nearest bound is returned. > > Now, does this need an RFC? The behaviour can be implemented in userland > in a number of ways, one of which is to compare the values in a if statement. > Another is to use the min and max math functions. > > max($min, min($max, $num)); > > I don’t have any schpeel as to why this should be in core, only that I thought it already was. > Considering it is part of other languages standard math library, and it is a useful function. > > Can see this being useful in image manipulation, server-side rendering and math just to name few. > > The proposed signature follows the convention of other math related functions. > > function clamp(int|float $num, int|float $min, int|float $max): int|float {} > > This function is very easy to implement, has no side effects or backward > compatibility issues, unless a userland implementation already has the function declared, > in which case PHP will throw a fatal error since the function cannot be redeclared. > > I've implemented this feature a few months ago already. > - Link: https://github.com/thinkverse/php-src/pull/1 <https://github.com/thinkverse/php-src/pull/1> > > What are your opinions on this function? > > Regards, > Kim Hallberg.
+1 from me as well. We recently added `str_contains`/`starts_with`/`ends_with`, which were welcome additions. I think `clamp` would be a nice addition too. I found three user-land `clamp` function declarations on a search on GitHub public repos. - [doubleleft/hook](https://github.com/doubleleft/hook/blob/master/src/bootstrap/helpers.php#L129) - 764 stars, Last activity in 2016. - [GetSimpleCMS/GetSimpleCMS](https://github.com/GetSimpleCMS/GetSimpleCMS/blob/master/admin/inc/basic.php#L2489) - 336 stars, Has recent activity. - [shish/shimmie2](https://github.com/shish/shimmie2/blob/master/core/polyfills.php#L477) - 267 stars, Has recent activity. I think it's safe to say that these libraries will be updated to accommodate the `clamp` function in PHP core; I'd even happily send pull requests to them. `doubleleft/hook` probably wouldn't be updated because it doesn't show recent activity, but that's an acceptable BC impact for a nice addition IMO. Thank you, --- Ayesh.

Kim Hallberg

5 years ago
> On 23 Jun 2021, at 2:25 AM, Kim Hallberg <hallbergkim@gmail.com> wrote: > > Greetings internals, > > I present to you a proposal for a new basic math function: clamp. > > function clamp(int|float $num, int|float $min, int|float $max): int|float {}
Instead of answering each response individually I’ll post a reply here instead. Since the majority seems to have a pretty positive position on this proposal. I am moving ahead with an RFC for this, and am now requesting RFC karma. If anyone would like to grant me the privilege to create this RFC you can grant me karma for the username: thinkverse on the wiki. A pull request into source will be submitted right after RFC has been written. Thank you, Kim.