Newsgroups: php.internals
Path: news.php.net
Xref: news.php.net php.internals:115056
MIME-Version: 1.0
References: <1014AE76-B3D5-48F7-A0F0-B8E3327123A2@gmail.com>
In-Reply-To: <1014AE76-B3D5-48F7-A0F0-B8E3327123A2@gmail.com>
Date: Wed, 23 Jun 2021 14:32:35 +0530
Message-ID: <CANLbj-rHvqhJ_WGQ1BbRMyXP+GUKPmhxSPUH8L7fnZXbHX2q1Q@mail.gmail.com>
To: Kim Hallberg <hallbergkim@gmail.com>
Cc: PHP internals <internals@lists.php.net>
Content-Type: text/plain; charset="UTF-8"
Content-Transfer-Encoding: quoted-printable
Subject: Re: [PHP-DEV] Proposal: clamp
From: ayesh@php.watch (Ayesh Karunaratne)

> 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 boun=
d.
> 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 statem=
ent.
> Another is to use the min and max math functions.
>
> max($min, min($max, $num));
>
> I don=E2=80=99t have any schpeel as to why this should be in core, only t=
hat I thought it already was.
> Considering it is part of other languages standard math library, and it i=
s a useful function.
>
> Can see this being useful in image manipulation, server-side rendering an=
d math just to name few.
>
> The proposed signature follows the convention of other math related funct=
ions.
>
> 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 fu=
nction declared,
> in which case PHP will throw a fatal error since the function cannot be r=
edeclared.
>
> 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/boo=
tstrap/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/poly=
fills.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.