Newsgroups: php.internals
Path: news.php.net
Xref: news.php.net php.internals:126094
Content-Type: text/plain;
	charset=us-ascii
Content-Transfer-Encoding: quoted-printable
Precedence: bulk
Mime-Version: 1.0 (Mac OS X Mail 16.0 \(3826.200.121\))
Subject: Re: [PHP-DEV] Inaccurate documentation on return values from native
 functions
Date: Mon, 2 Dec 2024 16:13:03 +0100
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>
To: internals@lists.php.net
In-Reply-To: <a6e191e6-d80c-4ec2-a6db-ce2d1f58cc14@rwec.co.uk>
Message-ID: <0FAE2A45-A1CE-4D2B-A6AC-82CF40CE8EAD@cschneid.com>
From: cschneid@cschneid.com (Christian Schneider)

Am 02.12.2024 um 13:31 schrieb Rowan Tommins [IMSoP] =
<imsop.php@rwec.co.uk>:
> On 01/12/2024 23:50, mickmackusa wrote:
>> 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 =3D false
>=20
>=20
> The functions are not attempting to return a meaningful "distance", =
this is just an optimisation: the intended use case is as a callback to =
functions like usort() which only care about <0, 0, >0, so no CPU time =
is spent normalising 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 =
people from relying on -1 and +1
c) We should consider changing it to -1 and +1 for consistency and =
something 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 =
and performance is not impacted negatively. I could turn it into a PR if =
wished.

Regards,
- Chris