Newsgroups: php.internals
Path: news.php.net
Xref: news.php.net php.internals:128543
Precedence: list
MIME-Version: 1.0
References: <CANBC5np5gFoG2vy572K_rV5df58qBJdQuKsmYdHiprA2mLPWUg@mail.gmail.com>
 <c9acda400885e3c78775e400cb492538@bastelstu.be> <CANBC5noypta7=YvVaAB6sPFhQKQCxJTFMQZ7fEShii2isya49A@mail.gmail.com>
 <0027ab13-89fb-40b4-991b-2f88a35c2f31@gmx.de> <CANBC5npgKA2T51t9=CD8LcqZsbLY-mW1GUepyGkZLPEGtVxoPA@mail.gmail.com>
 <272c241b-3145-4069-8a6a-9ea877f936c0@app.fastmail.com> <CANBC5npestDfHkGVd8LPZyz8Wxx4zuQApj5C-d=qp0Q=tvCVTQ@mail.gmail.com>
 <cbd359d2-c80a-4ae1-b9c3-16e2cbfc617a@app.fastmail.com> <bae5adb0-7b81-4178-915c-5d7c2633f1c0@app.fastmail.com>
In-Reply-To: <bae5adb0-7b81-4178-915c-5d7c2633f1c0@app.fastmail.com>
Date: Sun, 24 Aug 2025 16:41:52 +0200
Message-ID: <CANBC5nrdA3L_Ut+kZFmtACmdATjw0Xx1grEWjckPeDj14MF5WQ@mail.gmail.com>
Subject: Re: [PHP-DEV] [RFC] Add clamp function
To: Rob Landers <rob@bottled.codes>
Cc: internals@lists.php.net
Content-Type: multipart/alternative; boundary="00000000000031e897063d1d713d"
From: kylekatarnls@gmail.com (Kyle Katarn)

--00000000000031e897063d1d713d
Content-Type: text/plain; charset="UTF-8"
Content-Transfer-Encoding: quoted-printable

2025-08-23 at 12:06, Rob Landers <rob@bottled.codes> wrote:

>
> On Fri, Aug 22, 2025, at 22:09, Larry Garfield wrote:
>
> On Fri, Aug 22, 2025, at 12:45 PM, Kyle Katarn 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=E2=80=99t 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, returnin=
g
> the magnitude), it is simply ignored. As a weird side note: if you cast t=
he
> 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 =E2=80=9Cundefined=E2=80=9D and it isn=E2=80=99t documented. The=
re are examples that show
> how objects are compared, but they don=E2=80=99t 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 make=
s
> relying on it a bit risky.
>
> Adding operator overrides would help by making this behaviour explicit an=
d
> 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=E2=
=80=99ve
> never quite understood.
>
> =E2=80=94 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().

--00000000000031e897063d1d713d
Content-Type: text/html; charset="UTF-8"
Content-Transfer-Encoding: quoted-printable

<div dir=3D"ltr"><div dir=3D"ltr">2025-08-23 at 12:06, Rob Landers &lt;rob@=
bottled.codes&gt; wrote:</div><div class=3D"gmail_quote gmail_quote_contain=
er"><blockquote class=3D"gmail_quote" style=3D"margin:0px 0px 0px 0.8ex;bor=
der-left:1px solid rgb(204,204,204);padding-left:1ex"><div><div><br></div><=
div>On Fri, Aug 22, 2025, at 22:09, Larry Garfield wrote:</div><blockquote =
type=3D"cite" id=3D"m_-1982009145702621882qt"><div>On Fri, Aug 22, 2025, at=
 12:45 PM, Kyle Katarn wrote:</div><div><br></div><div>&gt; About &quot;Wha=
t determines comparability&quot;, it follows the usual rules of=C2=A0</div>=
<div>&gt; PHP:=C2=A0<a href=3D"https://www.php.net/manual/en/language.opera=
tors.comparison.php" target=3D"_blank">https://www.php.net/manual/en/langua=
ge.operators.comparison.php</a></div><div>&gt;</div><div>&gt; So it&#39;s e=
quivalent to ($value &lt; $min) ? $min : (($value &gt; $max) ? $max=C2=A0</=
div><div>&gt; : $value) and also equivalent to min($max, max($min, $value))=
</div><div>&gt;</div><div>&gt; About clamp(new Point(1, 2), new Point(0, 0)=
, new Point(5, 5));</div><div>&gt;</div><div>&gt; If Point is a comparable =
value (simple DTO for example), it should=C2=A0</div><div>&gt; return $valu=
e, like when doing ($value &lt; $min) ? $min : (($value &gt;=C2=A0</div><di=
v>&gt; $max) ? $max : $value) we could add a test for such case, but I thin=
k=C2=A0</div><div>&gt; that for consistency, whatever currently works in mi=
n() should work in=C2=A0</div><div>&gt; clamp()</div><div>&gt;</div><div>&g=
t; Following the link of the implementation, there is also a link to the=C2=
=A0</div><div>&gt; documentation where I already explained the comparison r=
ules following=C2=A0</div><div>&gt; the example of what was done in the doc=
umentation for min() and max():=C2=A0</div><div>&gt;=C2=A0<a href=3D"https:=
//github.com/php/doc-en/pull/4814" target=3D"_blank">https://github.com/php=
/doc-en/pull/4814</a></div><div><br></div><div>Please make sure the above i=
s captured in the RFC.</div><div><br></div><div>Though apparently what PHP =
currently does with Point comparisons in min/max is... weird.=C2=A0 I don&#=
39;t even know what the logic here is. :)</div><div><br></div><div><a href=
=3D"https://3v4l.org/pTmiV" target=3D"_blank">https://3v4l.org/pTmiV</a></d=
iv><div><br></div><div>(No need to change it in this RFC, just note explici=
tly that the expected behavior is identical to that min(max()) construct, r=
egardless of type.)</div><div><br></div><div>--Larry Garfield</div><div><br=
></div></blockquote><div><br></div><div>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 defau=
lt isn=E2=80=99t 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.</div><div><br></div><div>What is even trickier is th=
at this process completely ignores computed hooks. So, if you add a hook as=
 the first property (for example, returning the magnitude), it is simply ig=
nored. As a weird side note: if you cast the object to an array, the comput=
ed hook disappears, but if you use <code style=3D"border-width:1px;border-s=
tyle:solid;border-color:rgb(204,204,204);border-radius:3px;background-image=
:initial;background-size:initial;background-repeat:initial;background-origi=
n:initial;background-clip:initial;background-color:rgb(246,246,246);font-fa=
mily:menlo,consolas,monospace;font-size:90%;padding:1px 3px">json_encode()<=
/code>, the computed value is included.</div><div><br></div><div>To complic=
ate things further, the current behaviour for objects is actually =E2=80=9C=
undefined=E2=80=9D and it isn=E2=80=99t documented. There are examples that=
 show how objects are compared, but they don=E2=80=99t explicitly mention t=
hat the object is being cast to an array (see the above paragraph on why th=
at matters). Because this relies on implementation details rather than docu=
mented behaviour, it could change between PHP versions without an RFC. That=
 makes relying on it a bit risky.</div><div><br></div><div>Adding operator =
overrides would help by making this behaviour explicit and consistent acros=
s versions, or just defining it in general. But whenever someone tries to d=
efine this more clearly (as I started to do with Records), it tends to run =
into resistance on this list for reasons I=E2=80=99ve never quite understoo=
d.</div><div><br></div><div>=E2=80=94 Rob<br></div></div></blockquote><div>=
<br><div>I would not be against operator overrides, though it starts becomi=
ng 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 unexpecte=
d behavior, but this is probably out of scope, the same concerns apply to m=
in() and max() and that&#39;s why I added the same warning in the documenta=
tion: &quot;Be careful when passing arguments of different types because cl=
amp can produce unpredictable results.&quot; Adding a specific note about o=
bjects in the documentation could make sense. Then it would probably be nic=
e if it were also added to min() and max().</div></div></div></div>

--00000000000031e897063d1d713d--