Newsgroups: php.internals
Path: news.php.net
Xref: news.php.net php.internals:126092
Precedence: bulk
MIME-Version: 1.0
References: <CAKVXxD-9=cv5M7DHs0FLZdLMy9Xe5+AcXYtd6iSEmY=9u1g4AQ@mail.gmail.com>
 <CAKVXxD9QX1DODPboY9=36Cb23t36hLAF-Fa_NAeN3xoWDXycPg@mail.gmail.com>
 <Re44EoZ2A4IxjpFiUp0ZFd0ybwLNe923wDGbJo2TfZ4UPQcAQHxX2XE-RB-IWtZFkK_rrPT6JQvss265WxXuf3RvMqjzd8pH1G_7DhiM1NQ=@gpb.moe>
 <CAKVXxD_yd6sUgM=mjYEPJ1jK6O760nr8pGwyEfFG8tYttsBN6A@mail.gmail.com> <f702b9b5-c414-43ba-9c23-7a5a04b7b0e3@gmx.de>
In-Reply-To: <f702b9b5-c414-43ba-9c23-7a5a04b7b0e3@gmx.de>
Date: Mon, 2 Dec 2024 09:50:22 +1000
Message-ID: <CAKVXxD9RDy+Pvhsf33Xx0cFNr-Af2y23faZeoadt9B9DTpYeTg@mail.gmail.com>
Subject: Re: [PHP-DEV] Re: Inaccurate documentation on return values from
 native functions
Cc: internals <internals@lists.php.net>
Content-Type: multipart/alternative; boundary="0000000000000db93f06283e196a"
From: mickmackusa@gmail.com (mickmackusa)

--0000000000000db93f06283e196a
Content-Type: text/plain; charset="UTF-8"

> > I am not sure that this is purely a problem with the documentation.
> > It seems possible to me that someone updated the documentation to
> reflect a
> > new intention for these functions.
> > Will it not be that these functions will be altered in the core to do
> what
> > the documentation says?
>
> If the docs are not correct, we cannot simply change the source to
> conform for BC reasons.
>
> In this case, see <https://github.com/php/doc-en/issues/3629>.
>

I can appreciate that.  Going forward, is there any benefit to preserving
the behavior of returning integers beyond -1, 0, and 1?
Should these topically related functions receive a new last argument? bool
$distance = false
I don't know if there is already an established naming convention for such
a value in a function signature.
This way codebases that rely on the historic behavior can set $distance as
true, otherwise omit the parameter.
Or is there absolutely no reason to return the calculated distance because
a 3-way return is all that is ever needed?

mickmackusa

--0000000000000db93f06283e196a
Content-Type: text/html; charset="UTF-8"
Content-Transfer-Encoding: quoted-printable

<div dir=3D"ltr"><div dir=3D"ltr"><br></div><div class=3D"gmail_quote"><blo=
ckquote class=3D"gmail_quote" style=3D"margin:0px 0px 0px 0.8ex;border-left=
:1px solid rgb(204,204,204);padding-left:1ex">&gt; I am not sure that this =
is purely a problem with the documentation.<br>
&gt; It seems possible to me that someone updated the documentation to refl=
ect a<br>
&gt; new intention for these functions.<br>
&gt; Will it not be that these functions will be altered in the core to do =
what<br>
&gt; the documentation says?<br>
<br>
If the docs are not correct, we cannot simply change the source to<br>
conform for BC reasons.<br>
<br>
In this case, see &lt;<a href=3D"https://github.com/php/doc-en/issues/3629"=
 rel=3D"noreferrer" target=3D"_blank">https://github.com/php/doc-en/issues/=
3629</a>&gt;.<br></blockquote><div><br></div><div>I can appreciate that.=C2=
=A0 Going forward, is there any benefit to preserving the behavior of retur=
ning integers beyond -1, 0, and 1?<br>Should these topically related functi=
ons receive a new last argument? <span style=3D"background-color:rgb(153,15=
3,153)">bool $distance =3D false</span><br>I don&#39;t know if there is alr=
eady an established naming convention for such a value in a function signat=
ure.</div><div>This way codebases that rely on the historic behavior can se=
t $distance as true, otherwise omit the parameter.</div><div>Or is there ab=
solutely no reason to return the calculated distance because a 3-way return=
 is all that is ever needed?</div><div><br></div><div>mickmackusa</div></di=
v></div>

--0000000000000db93f06283e196a--