Newsgroups: php.internals
Path: news.php.net
Xref: news.php.net php.internals:124159
Message-ID: <8870a7d0-7b65-4ccf-b20c-e69a3c5fc7de@bastelstu.be>
Date: Mon, 1 Jul 2024 22:18:37 +0200
Precedence: bulk
MIME-Version: 1.0
Subject: Re: [PHP-DEV] [RFC] [discussion] Correctly name the rounding mode and
 make it an Enum
To: Claude Pache <claude.pache@gmail.com>
Cc: "Gina P. Banyard" <internals@gpb.moe>, Saki Takamachi <saki@sakiot.com>,
 Jorg Sowa <jorg.sowa@gmail.com>, php internals <internals@lists.php.net>
References: <9zUVZKaEYixjCLLhviQPYFQtSAEhsRMWL6xbKeogzAGsH-STebN9JqJxITAPVfdKTNu7gEs_m77OkIcOzaiscoajx8Hp8VWRKkhTTCPkGko=@gpb.moe>
 <6E690732-8BED-4A01-8385-648E7CEDFD9F@sakiot.com>
 <70f63dd2e0ba7959a9e3bb7fa68ce14a@bastelstu.be>
 <CJrCSLTp-erzdhSRTrFn2Ss0AoEpkkhqh7fnUrXgHyMfgNPkwXhpSeGsKdhV_ycUIqWhJWpWOxI0W8XGprR_O8iqSrVVWoBNiUUFMaZCNDY=@gpb.moe>
 <67d37d56-625f-4f80-805d-a5db2d3807bb@bastelstu.be>
 <0A9642EC-0FCC-4BC3-82C2-C6C968CD8D1C@gmail.com>
Content-Language: en-US
In-Reply-To: <0A9642EC-0FCC-4BC3-82C2-C6C968CD8D1C@gmail.com>
Content-Type: text/plain; charset=UTF-8; format=flowed
Content-Transfer-Encoding: 8bit
From: tim@bastelstu.be (=?UTF-8?Q?Tim_D=C3=BCsterhus?=)

Hi

please apologize the delay in getting back to you. I was absolutely 
swamped with mailing list mails, other work and I didn't want to give a 
reply that I did not give any thought.

On 6/19/24 21:14, Claude Pache wrote:
> Second, “TowardsPositiveInfinity” is just a mouthful synonym for “Up”. You could just name it:
> 
> Round::Up

Except that it isn't and both the RFC and the two fine folks who already 
replied explained why.

> At this point, you may invoke either Hamming or Levenshtein and compare it negatively with `Round::HalfUp`. Yes there is a risk a confusion (and I do think that such a name is suboptimal for this reason), but the confusion is not just caused by the short Levenshtein distance. That brings to the most important part of my review.

Please note that the comparison was not made against the corresponding 
“Half” mode, but rather that the term “Up” is needlessly ambiguous. As 
I've also replied to Jordan: The RFC intentionally does not use the Up 
terminology (except to refer to the existing constants, which 
unfortunately use that terminology).

> In my opinion, the most important criterion for a good name is:
> 
> The name must be clear for itself, not just when comparing it with other ones.
> 
> The problem with `Round::Up` (or `Round::[Towards]PositiveInfinity`), when you first encounter it, is that it is relatively easy to mistakingly assume that it is a “half-*” mode, and to erroneously  interpret it as `Round::HalfUp` (or, its synonym `Round::HalfTowardsPositiveInfinity`).

That is a fair concern. We shortly discussed splitting the enum into one 
"MidpointRoundingMode" and one other enum for the directed rounding 
modes, but we felt that it did not reliably solve this problem either. 
At least with a single enum all the 'Half' modes would appear in 
autocompletion.

> But that the converse is false: it is impossible to interpret `Round::HalfUp` as if it were `Round::Up` (or `Round::TowardsPositiveInfinity`), because of the distinctive “Half” token that immediately indicate the right interpretation.

Right.

> So, the best way to disambiguate `Round::Up` from `Round::HalfUp`, is not to replace “Up” with some creative synonym, but to add a distinctive token that plays the role of — and contrasts with — “Half”. I don’t know if the following suggestion makes sense for you, but it is the one I have found:
> 
> Round::FullUp

You might have misunderstood my email. The concerns were not that 
HalfTowardsZero is too similar to TowardsZero, but rather that 
HalfTowardsZero is too similar to HalfTowardsEven, because they share 
the same 11-character prefix.

> That said, I think that there is an even better option. I know you will not like it, but bear with me. I sincerely think that the best name is just:
> 
> Round::Ceiling
> 
> It is short, distinctive, and standard across the computing industry.
> 
> Yes, this name is idiosyncratic to English and not used in several other (natural) languages, and if you don’t know English, you will not grasp the metaphor and have to just learn it. However, whatever other name you invent, you *have* to learn “ceil” anyway, because you *will* encounter it sooner or later. Many common (programming) languages, including JavaScript, C++, Java, Python, have a `ceil` function. Even if you manage not to learn any of those and to code in PHP only, you are at risk to stumble on its built-in `ceil(...)` function, or its newly-introduced `bcceil(...)` variant.
> 
> Therefore, unless we find a name that is *really* good, I suggest to not fall into the NIH syndrome, and not to force users to learn another name *in addition to* “ceiling”.

There is precedent for an "infinity-based" naming in other programming 
languages. The most mainstream one is probably C#:

https://learn.microsoft.com/en-us/dotnet/api/system.midpointrounding?view=net-8.0

But there is also MATLAB:

https://de.mathworks.com/help/matlab/ref/round.html#mw_e51282fd-7461-4bab-9f38-6106551bb8b2

We can even find precedent in PHP itself. The GMP extension already has 
rounding mode constants GMP_ROUND_PLUSINF and GMP_ROUND_MINUSINF:

https://www.php.net/manual/en/gmp.constants.php

And to add some anecdata: Just a few days ago I fixed a bug where the 
floor() function was incorrectly used where rounding towards zero was 
desired, resulting in incorrect results for negative numbers.

The Ceiling / Floor / Up / Down naming is needlessly ambiguous, 
especially for non-native speakers.

> For the same reason, `Round::TowardsZero` (suboptimal, because confusable with `Round::HalfTowardsZero`) could be replaced with: `Round::Truncate`.
> 

While I think that Truncate is reasonably clear, breaking the mapping 
between the midpoint modes and the directed rounding modes just for this 
case does not appear useful.

Best regards
Tim Düsterhus