# Incorrect terminology usage for rounding modes of round()

- Thread: https://externals.io/message/123126
- Original archive: https://news-web.php.net/php.internals/123126
- Started by Gina P. Banyard on 2024-04-14T14:33:10+00:00
- Messages: 6
- RFC: Correctly name the rounding mode and make it an Enum (Implemented (PHP 8.4)) — https://externals.io/rfc/correctly_name_the_rounding_mode_and_make_it_an_enum.md
- RFC: Adding bcround, bcfloor and bcceil to BCMath (Implemented (PHP 8.4)) — https://externals.io/rfc/adding_bcround_bcfloor_bcceil_to_bcmath.md
- RFC: New 4 rounding modes to round() function (Implemented (PHP 8.4)) — https://externals.io/rfc/new_rounding_modes_to_round_function.md
- Reply by email to internals@lists.php.net
- More for agents: search with https://externals.io/search.md?q={query} · RFCs at https://externals.io/rfc.md · JSON API at https://externals.io/api · documentation at https://externals.io/llms.txt

---

## #123126 — Gina P. Banyard — 2024-04-14T14:33:10+00:00

URL: https://externals.io/message/123126#123126

Hello internals,

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.

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).

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

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]

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.

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;
}

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.

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.

Best regards,

Gina P. Banyard

[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-calculator.php
[4] https://wiki.php.net/rfc/new_rounding_modes_to_round_function

---

## #123129 — Saki Takamachi — 2024-04-14T15:55:43+00:00

URL: https://externals.io/message/123126#123129 · In reply to: #123126

Hi Gina,

> Hello internals,
> 
> 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.
> 
> 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).
> 
> 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
> 
> 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]
> 
> 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.
> 
> 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;
> }
> 
> 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.
> 
> 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.
> 
> Best regards,
> 
> Gina P. Banyard
> 
> [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-calculator.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

---

## #123130 — Derick Rethans — 2024-04-14T16:42:26+00:00

URL: https://externals.io/message/123126#123130 · In reply to: #123129

>Hi Gina,
>
> > […]
>
>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

Math is American English spelling, Maths/Mathematics the British English one.

As we also have color (and not the "correct" colour), going with the American spelling seems better. 

But I would query whether we actually need it in a namespace. 

cheers
Derick

---

## #123131 — tim@bastelstu.be — 2024-04-14T16:49:42+00:00

URL: https://externals.io/message/123126#123131 · In reply to: #123126

Hi


> 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

---

## #123132 — Jordan LeDoux — 2024-04-14T18:16:31+00:00

URL: https://externals.io/message/123126#123132 · In reply to: #123131

>
> 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.
>
>
+1

For this, I don't think a namespace is necessary. Though I will note that
"Mathematics" is absolutely an American English term as well as British
English, even though "Maths" is not.

This will also make it easier for me to do one of the smaller improvements
I've been pondering proposing: adding some brand new rounding modes:

- Half Alternating
- Half Random
- Stochastic

Jordan

---

## #123133 — Larry Garfield — 2024-04-14T18:25:03+00:00

URL: https://externals.io/message/123126#123133 · In reply to: #123131

> Hi
>
> 
> > […]

> 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 support this change.  While I don't know who would be using the rounding mode constants for other purposes, I'm not opposed to taking a more gradual approach if that's the consensus.  At least a version would allow people time to realize, oops, I should not use someone else's constants. :-)

I also don't have a strong opinion between making it global vs a Math namespace.  (But as Derick notes, not Maths, for consistency.)

--Larry Garfield
