Newsgroups: php.internals
Path: news.php.net
Xref: news.php.net php.internals:126096
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>
In-Reply-To: <a6e191e6-d80c-4ec2-a6db-ce2d1f58cc14@rwec.co.uk>
Date: Mon, 2 Dec 2024 17:29:29 +0100
Message-ID: <CAPyj-LBThOT1V+OvjDj_wksi5nvtTJLp-gu+Qu88LVnr2kbhPg@mail.gmail.com>
Subject: Re: [PHP-DEV] Re: Inaccurate documentation on return values from
 native functions
To: PHP internals <internals@lists.php.net>
Content-Type: text/plain; charset="UTF-8"
Content-Transfer-Encoding: quoted-printable
From: tovilo.ilija@gmail.com (Ilija Tovilo)

On Mon, Dec 2, 2024 at 1:31=E2=80=AFPM Rowan Tommins [IMSoP]
<imsop.php@rwec.co.uk> wrote:
>
> On 01/12/2024 03:41, 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? boo=
l $distance =3D false
>
> The functions are not attempting to return a meaningful "distance", this =
is just an optimisation: the intended use case is as a callback to function=
s like usort() which only care about <0, 0, >0, so no CPU time is spent nor=
malising the result to specific values.
>
> The documentation is simply mistaken in saying "-1" instead of "a value l=
ess than zero" and "1" instead of "a value more than zero".

This is exactly it. This was already fixed in the upgrading guide a while a=
go:

https://github.com/php/doc-en/pull/3450

> The strcmp, ... functions, using binary safe string comparison is no long=
er
> guaranteed to return strlen($string1) - strlen($string2) when string leng=
ths are
> not equal, but may now return -1 or 1 instead. Instead of depending on an=
y
> concrete value, the return value should be compared to 0.

The reason for this change is not to unify the output, but rather to
avoid a bug on platforms where sizeof(size_t) > sizeof(int). When the
length of the string exceeds what int can hold, the difference in
string sizes can potentially not be represented by int. The data
truncation may potentially lead to incorrect results. See this comment
for details:

https://github.com/php/php-src/pull/8220#issuecomment-1073337678

Ilija