Re: Inaccurate documentation on return values from native functions

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