Newsgroups: php.internals
Path: news.php.net
Xref: news.php.net php.internals:123129
Content-Type: text/plain;
	charset=us-ascii
Precedence: bulk
Mime-Version: 1.0 (Mac OS X Mail 16.0 \(3731.700.6.1.1\))
Subject: Re: [PHP-DEV] Incorrect terminology usage for rounding modes of
 round()
In-Reply-To: <KOnrDbR12WyDnAayphg_Avxa0gkLH_tfd7DCtkMPbG1FjMSUVXIB1uKJTgboiVao3RCwNMHYP5_G5ixEudQxMRmIJ-PnYG3-RwJJ03qRh7Y=@gpb.moe>
Date: Mon, 15 Apr 2024 00:55:43 +0900
Cc: PHP internals <internals@lists.php.net>,
 =?utf-8?Q?Tim_D=C3=BCsterhus?= <tim@bastelstu.be>
Content-Transfer-Encoding: quoted-printable
Message-ID: <690BDBA4-4D17-4BE7-BF76-D75F85403A0E@sakiot.com>
References: <KOnrDbR12WyDnAayphg_Avxa0gkLH_tfd7DCtkMPbG1FjMSUVXIB1uKJTgboiVao3RCwNMHYP5_G5ixEudQxMRmIJ-PnYG3-RwJJ03qRh7Y=@gpb.moe>
To: "Gina P. Banyard" <internals@gpb.moe>
From: saki@sakiot.com (Saki Takamachi)

Hi Gina,

> Hello internals,
>=20
> While reviewing the PR for the "Adding bcround, bcfloor and bcceil to =
BCMath" RFC [1] with the different rounding modes,
> I was made aware of the unfortunate wrong terminology usage of =
PHP_ROUND_HALF_UP and PHP_ROUND_HALF_DOWN.
>=20
> Indeed, PHP_ROUND_HALF_UP is implemented as "rounding half away from =
zero" and not "rounding half up" (which is also called rounding toward =
positive infinity).
> The behaviour for positive numbers is the same, however for negative =
numbers the rounding *is* different.
> In the same vein, PHP_ROUND_HALD_DOWN is implemented as "rounding half =
toward zero" and not "rounding half down" (/round half toward negative =
infinity).
>=20
> Taking -1.5 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 =
great use. [2]
> And the following rounding calculator on Calculator Soup is useful to =
check the differences and behaviour of different rounding modes. [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.
>=20
> Considering that PHP 8.4 is also adding new rounding modes via the =
"Add 4 new rounding modes to round() function" RFC [4] attempting to =
solve this issue in this next version of PHP seems like a good idea.
> 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 =
something 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_HALF_UP): float
> to
> round(int|float $num, int $precision =3D 0, RoundingMode $mode =3D =
RoundingMode::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 =
implement the half up/down rounding modes properly, and deprecate the =
existing rounding constants in the future to get rid of the confusing =
names.
>=20
> I wanted to know if anyone has any object to introducing this new enum =
and signature change.
> The only thing I could think of is if this enum should be in a new =
Maths (or Math or just Mathematics to not need to deal with regional =
difference in the short spelling of "Mathematics") namespace.
>=20
> Best regards,
>=20
> Gina P. Banyard
>=20
> [1] https://wiki.php.net/rfc/adding_bcround_bcfloor_bcceil_to_bcmath
> [2] https://en.wikipedia.org/wiki/Rounding
> [3] =
https://www.calculatorsoup.com/calculators/math/rounding-methods-calculato=
r.php
> [4] https://wiki.php.net/rfc/new_rounding_modes_to_round_function

In my discussions with Tim, I want to make it clear that all ideas =
derived are Tim's. :)

Now, of course I agree with this, and agree with using namespaces. =
However, if didn't use namespaces, that's fine by me. For reference, we =
found approximately 100 pieces of code using the namespace `Math` on =
Github Code Search. There are only a few cases for `Maths` and 0 for =
`Mathematics`.

Regards,

Saki