Newsgroups: php.internals
Path: news.php.net
Xref: news.php.net php.internals:123130
Date: Sun, 14 Apr 2024 17:42:26 +0100
To: internals@lists.php.net, Saki Takamachi <saki@sakiot.com>,
 "Gina P. Banyard" <internals@gpb.moe>
CC: PHP internals <internals@lists.php.net>,
 =?ISO-8859-1?Q?Tim_D=FCsterhus?= <tim@bastelstu.be>
Subject: =?US-ASCII?Q?Re=3A_=5BPHP-DEV=5D_Incorrect_terminology?=
 =?US-ASCII?Q?_usage_for_rounding_modes_of_round=28=29?=
User-Agent: K-9 Mail for Android
In-Reply-To: <690BDBA4-4D17-4BE7-BF76-D75F85403A0E@sakiot.com>
References: <KOnrDbR12WyDnAayphg_Avxa0gkLH_tfd7DCtkMPbG1FjMSUVXIB1uKJTgboiVao3RCwNMHYP5_G5ixEudQxMRmIJ-PnYG3-RwJJ03qRh7Y=@gpb.moe> <690BDBA4-4D17-4BE7-BF76-D75F85403A0E@sakiot.com>
Message-ID: <E7485766-385F-43EA-A93B-87F6AADBCA2A@php.net>
Precedence: bulk
MIME-Version: 1.0
Content-Type: text/plain;
 charset=utf-8
Content-Transfer-Encoding: quoted-printable
From: derick@php.net (Derick Rethans)

On 14 April 2024 16:55:43 BST, Saki Takamachi <saki@sakiot=2Ecom> wrote:
>Hi Gina,
>
>> Hello internals,
>>=20
>> While reviewing the PR for the "Adding bcround, bcfloor and bcceil to B=
CMath" RFC [1] with the different rounding modes,
>> I was made aware of the unfortunate wrong terminology usage of PHP_ROUN=
D_HALF_UP and PHP_ROUND_HALF_DOWN=2E
>>=20
>> Indeed, PHP_ROUND_HALF_UP is implemented as "rounding half away from ze=
ro" and not "rounding half up" (which is also called rounding toward positi=
ve infinity)=2E
>> The behaviour for positive numbers is the same, however for negative nu=
mbers the rounding *is* different=2E
>> In the same vein, PHP_ROUND_HALD_DOWN is implemented as "rounding half =
toward zero" and not "rounding half down" (/round half toward negative infi=
nity)=2E
>>=20
>> Taking -1=2E5 as our number:
>> - Rounding half-up: -1
>> - Rounding half away from zero: -2
>> - Rounding half-down: -2
>> - Rounding half towards zero: -1
>>=20
>> For a detailed explanation about rounding, the Wikipedia page is of gre=
at use=2E [2]
>> And the following rounding calculator on Calculator Soup is useful to c=
heck the differences and behaviour of different rounding modes=2E [3]
>>=20
>> It should be noted that PHP is in good company about being wrong about =
those two rounding modes, Java, Python, and Ruby (and probably others) are =
also wrong in this regard=2E
>>=20
>> Considering that PHP 8=2E4 is also adding new rounding modes via the "A=
dd 4 new rounding modes to round() function" RFC [4] attempting to solve th=
is issue in this next version of PHP seems like a good idea=2E
>> In my discussions with Saki about this issue, it seems that her and Tim=
 have thought about creating a new enum for rounding modes, looking somethi=
ng like this:
>>=20
>> enum RoundingMode {
>>    case HalfAwayFromZero;
>>    case HalfTowardsZero;
>>    case HalfEven;
>>    case HalfOdd;
>>    case TowardsZero;
>>    case AwayFromZero;
>>    case NegativeInfinity; // or case Floor;
>>    case PositiveInfinity; // or case Ceiling;
>> }
>>=20
>> and change the signature of round from:
>> round(int|float $num, int $precision =3D 0, int $mode =3D PHP_ROUND_HAL=
F_UP): float
>> to
>> round(int|float $num, int $precision =3D 0, RoundingMode $mode =3D Roun=
dingMode::HalfAwayFromZero): float
>>=20
>> and changing the definition of the existing constants to effectively be=
:
>> define('PHP_ROUND_HALF_UP', RoundingMode::HalfAwayFromZero);
>> define('PHP_ROUND_HALF_DOWN', RoundingMode::HalfTowardsZero);
>> define('PHP_ROUND_HALF_EVEN', RoundingMode::HalfEven);
>> define('PHP_ROUND_HALF_ODD', RoundingMode::HalfOdd);
>>=20
>> This should not cause any BC breaks, while allowing us to potentially i=
mplement the half up/down rounding modes properly, and deprecate the existi=
ng rounding constants in the future to get rid of the confusing names=2E
>>=20
>> I wanted to know if anyone has any object to introducing this new enum =
and signature change=2E
>> The only thing I could think of is if this enum should be in a new Math=
s (or Math or just Mathematics to not need to deal with regional difference=
 in the short spelling of "Mathematics") namespace=2E
>>=20
>> Best regards,
>>=20
>> Gina P=2E Banyard
>>=20
>> [1] https://wiki=2Ephp=2Enet/rfc/adding_bcround_bcfloor_bcceil_to_bcmat=
h
>> [2] https://en=2Ewikipedia=2Eorg/wiki/Rounding
>> [3] https://www=2Ecalculatorsoup=2Ecom/calculators/math/rounding-method=
s-calculator=2Ephp
>> [4] https://wiki=2Ephp=2Enet/rfc/new_rounding_modes_to_round_function
>
>In my discussions with Tim, I want to make it clear that all ideas derive=
d are Tim's=2E :)
>
>Now, of course I agree with this, and agree with using namespaces=2E Howe=
ver, if didn't use namespaces, that's fine by me=2E For reference, we found=
 approximately 100 pieces of code using the namespace `Math` on Github Code=
 Search=2E There are only a few cases for `Maths` and 0 for `Mathematics`=
=2E
>
>Regards,
>
>Saki

Math is American English spelling, Maths/Mathematics the British English o=
ne=2E

As we also have color (and not the "correct" colour), going with the Ameri=
can spelling seems better=2E=20

But I would query whether we actually need it in a namespace=2E=20

cheers
Derick