Newsgroups: php.internals
Path: news.php.net
Xref: news.php.net php.internals:126095
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> <CAKVXxD9RDy+Pvhsf33Xx0cFNr-Af2y23faZeoadt9B9DTpYeTg@mail.gmail.com>
 <a6e191e6-d80c-4ec2-a6db-ce2d1f58cc14@rwec.co.uk> <0FAE2A45-A1CE-4D2B-A6AC-82CF40CE8EAD@cschneid.com>
In-Reply-To: <0FAE2A45-A1CE-4D2B-A6AC-82CF40CE8EAD@cschneid.com>
Date: Mon, 2 Dec 2024 17:11:48 +0100
Message-ID: <CAJmy8YFm91KGmDmfUJS8n8yw5FiUujNUHk3VfQbJ==FDDStJgw@mail.gmail.com>
Subject: Re: [PHP-DEV] Inaccurate documentation on return values from native functions
To: Christian Schneider <cschneid@cschneid.com>
Cc: internals@lists.php.net
Content-Type: text/plain; charset="UTF-8"
Content-Transfer-Encoding: quoted-printable
From: divinity76@gmail.com (Hans Henrik Bergan)

On Mon, 2 Dec 2024 at 16:16, Christian Schneider <cschneid@cschneid.com> wr=
ote:
>
> Am 02.12.2024 um 13:31 schrieb Rowan Tommins [IMSoP] <imsop.php@rwec.co.u=
k>:
> > On 01/12/2024 23:50, mickmackusa wrote:
> >> I can appreciate that.  Going forward, is there any benefit to preserv=
ing the behavior of returning integers beyond -1, 0, and 1?
> >> Should these topically related functions receive a new last argument? =
bool $distance =3D false
> >
> >
> > The functions are not attempting to return a meaningful "distance", thi=
s is just an optimisation: the intended use case is as a callback to functi=
ons like usort() which only care about <0, 0, >0, so no CPU time is spent n=
ormalising the result to specific values.
> > The documentation is simply mistaken in saying "-1" instead of "a value=
 less than zero" and "1" instead of "a value more than zero".
>
> After following the discussion I am a bit unsure what the conclusion is:
> a) We should keep it as is (but change the docs) because of BC
> b) We should keep it as is (but change the docs) because it prevents peop=
le from relying on -1 and +1
> c) We should consider changing it to -1 and +1 for consistency and someth=
ing like 'switch/case' uses
>
> It looks like the general opinion seems to be a) or b) but I still wanted=
 to double-check.
>
> PS: I have a local branch with the necessary changes to code and tests an=
d performance is not impacted negatively. I could turn it into a PR if wish=
ed.
>
> Regards,
> - Chris

I vote A