Newsgroups: php.internals
Path: news.php.net
Xref: news.php.net php.internals:123131
Message-ID: <c7d2adb0-0035-482a-a124-11bf30d10212@bastelstu.be>
Date: Sun, 14 Apr 2024 18:49:42 +0200
Precedence: bulk
MIME-Version: 1.0
Subject: Re: [PHP-DEV] Incorrect terminology usage for rounding modes of
 round()
To: "Gina P. Banyard" <internals@gpb.moe>,
 PHP internals <internals@lists.php.net>
References: <KOnrDbR12WyDnAayphg_Avxa0gkLH_tfd7DCtkMPbG1FjMSUVXIB1uKJTgboiVao3RCwNMHYP5_G5ixEudQxMRmIJ-PnYG3-RwJJ03qRh7Y=@gpb.moe>
Content-Language: en-US
In-Reply-To: <KOnrDbR12WyDnAayphg_Avxa0gkLH_tfd7DCtkMPbG1FjMSUVXIB1uKJTgboiVao3RCwNMHYP5_G5ixEudQxMRmIJ-PnYG3-RwJJ03qRh7Y=@gpb.moe>
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

On 4/14/24 16:33, Gina P. Banyard wrote:
> 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:
> 
> enum RoundingMode {
>      case HalfAwayFromZero;
>      case HalfTowardsZero;
>      case HalfEven;
>      case HalfOdd;
>      case TowardsZero;
>      case AwayFromZero;
>      case NegativeInfinity; // or case Floor;
>      case PositiveInfinity; // or case Ceiling;
> }

Indeed.

> and change the signature of round from:
> round(int|float $num, int $precision = 0, int $mode = PHP_ROUND_HALF_UP): float
> to
> round(int|float $num, int $precision = 0, RoundingMode $mode = RoundingMode::HalfAwayFromZero): float
> 
> 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);
> 
> 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.

For PHP 8.4, I'd first make it `int|RoundingMode` to keep the constant 
values the same (in case the constants are re-used by a userland 
library). Narrowing it down to just RoundingMode and updating the 
constants can happen in a later version.

> 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.

I don't think it should be in a namespace. The name is sufficiently 
unique and clear. Without a broader concept for the namespace, we 
probably should not introduce one.

Best regards
Tim Düsterhus