Newsgroups: php.internals
Path: news.php.net
Xref: news.php.net php.internals:126093
Feedback-ID: id5114917:Fastmail
Content-Type: multipart/alternative;
 boundary="------------80sZSiRcaVkOIGvQDO0jlzUl"
Message-ID: <a6e191e6-d80c-4ec2-a6db-ce2d1f58cc14@rwec.co.uk>
Date: Mon, 2 Dec 2024 12:31:24 +0000
Precedence: bulk
MIME-Version: 1.0
User-Agent: Mozilla Thunderbird
Subject: Re: [PHP-DEV] Re: Inaccurate documentation on return values from
 native functions
To: internals@lists.php.net
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>
Content-Language: en-GB
In-Reply-To: <CAKVXxD9RDy+Pvhsf33Xx0cFNr-Af2y23faZeoadt9B9DTpYeTg@mail.gmail.com>
From: imsop.php@rwec.co.uk ("Rowan Tommins [IMSoP]")

This is a multi-part message in MIME format.
--------------80sZSiRcaVkOIGvQDO0jlzUl
Content-Type: text/plain; charset=UTF-8; format=flowed
Content-Transfer-Encoding: 8bit

On 01/12/2024 03:41, mickmackusa wrote:
> [image: image.png] 


Please avoid images of text; most of the reasons it's a bad idea on 
Stack Overflow apply here https://meta.stackoverflow.com/q/285551/157957 
plus a lot of mailing list archives and e-mail readers will not show 
HTML formatting at all, e.g. https://externals.io/message/126085

I had to read several replies to actually see what issue you were 
discussing.


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".

Regards,

-- 
Rowan Tommins
[IMSoP]

--------------80sZSiRcaVkOIGvQDO0jlzUl
Content-Type: text/html; charset=UTF-8
Content-Transfer-Encoding: 8bit

<!DOCTYPE html>
<html>
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
  </head>
  <body>
    <div class="moz-cite-prefix">On 01/12/2024 03:41, mickmackusa wrote:</div>
    <div class="moz-cite-prefix">
      <blockquote type="cite">[image: image.png] </blockquote>
    </div>
    <div class="moz-cite-prefix"><br>
    </div>
    <div class="moz-cite-prefix"><br>
    </div>
    <div class="moz-cite-prefix">Please avoid images of text; most of
      the reasons it's a bad idea on Stack Overflow apply here
      <a class="moz-txt-link-freetext" href="https://meta.stackoverflow.com/q/285551/157957">https://meta.stackoverflow.com/q/285551/157957</a> plus a lot of
      mailing list archives and e-mail readers will not show HTML
      formatting at all, e.g. <a class="moz-txt-link-freetext" href="https://externals.io/message/126085">https://externals.io/message/126085</a><br>
    </div>
    <div class="moz-cite-prefix"><br>
    </div>
    <div class="moz-cite-prefix">I had to read several replies to
      actually see what issue you were discussing.</div>
    <div class="moz-cite-prefix"><br>
    </div>
    <div class="moz-cite-prefix"><br>
    </div>
    <div class="moz-cite-prefix">On 01/12/2024 23:50, mickmackusa wrote:<br>
    </div>
    <blockquote type="cite"
cite="mid:CAKVXxD9RDy+Pvhsf33Xx0cFNr-Af2y23faZeoadt9B9DTpYeTg@mail.gmail.com">I
      can appreciate that.  Going forward, is there any benefit to
      preserving the behavior of returning integers beyond -1, 0, and 1?<br>
      Should these topically related functions receive a new last
      argument? <span style="background-color:rgb(153,153,153)">bool
        $distance = false</span></blockquote>
    <p><br>
    </p>
    <p>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
      &lt;0, 0, &gt;0, so no CPU time is spent normalising the result to
      specific values.<br>
    </p>
    <p>The documentation is simply mistaken in saying "-1" instead of "a
      value less than zero" and "1" instead of "a value more than zero".</p>
    <p>Regards,<br>
    </p>
    <pre class="moz-signature" cols="72">-- 
Rowan Tommins
[IMSoP]</pre>
  </body>
</html>

--------------80sZSiRcaVkOIGvQDO0jlzUl--