Re: Inaccurate documentation on return values from native functions

On Mon, 2 Dec 2024 at 16:16, Christian Schneider <cschneid@cschneid.com> wrote: > > 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 = > >> 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 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 I vote A