# RFC: New 4 rounding modes to round() function - Status: Implemented (PHP 8.4) - Authors: Jorg Sowa jorg.sowa@gmail.com - Date: 2023-08-31 - Target: PHP 8.4 - Implementation: https://github.com/php/php-src/pull/12056 - Original: https://wiki.php.net/rfc/new_rounding_modes_to_round_function - Page: https://externals.io/rfc/new_rounding_modes_to_round_function - 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 ## Votes ### Implement 4 new rounding modes to `round()` function (closed) Yes: 19 · No: 0 Voters: ashnazg (Yes), bukka (Yes), crell (Yes), derick (Yes), galvao (Yes), girgias (Yes), joey (Yes), kalle (Yes), levim (Yes), mbeccati (Yes), nicolasgrekas (Yes), nielsdos (Yes), ocramius (Yes), petk (Yes), ramsey (Yes), santiagolizardo (Yes), sergey (Yes), theodorejb (Yes), timwolla (Yes) ### Create aliases for Intl extension constants ROUND_UP and ROUND_DOWN: ROUND_AWAY_FROM_ZERO and ROUND_TOWARD_ZERO (closed) Yes: 10 · No: 6 Voters: ashnazg (Yes), bukka (No), crell (Yes), derick (No), galvao (Yes), girgias (Yes), joey (Yes), kalle (No), levim (No), mbeccati (Yes), nicolasgrekas (Yes), ocramius (No), ramsey (Yes), santiagolizardo (No), sergey (Yes), theodorejb (Yes) ## Discussions on the mailing list - [\[RFC\] \[Discussion\] Add 4 new rounding modes to round() function](https://externals.io/message/120971.md) — started on 2023-09-02, 15 messages - [\[VOTE\] \[RFC\]](https://externals.io/message/121680.md) — started on 2023-11-15, 3 messages - [\[RFC\] \[VOTE\] Add 4 new rounding modes to round() function](https://externals.io/message/121689.md) — started on 2023-11-15, 10 messages - [Incorrect terminology usage for rounding modes of round()](https://externals.io/message/123126.md) — started on 2024-04-14, 6 messages --- ## Introduction The RFC proposes to add 4 new modes to the round() function. - [PHP\_ROUND\_CEILING](https://en.wikipedia.org/wiki/Rounding#Rounding_up), - [PHP\_ROUND\_FLOOR](https://en.wikipedia.org/wiki/Rounding#Rounding_down), - [PHP\_ROUND\_AWAY\_FROM\_ZERO](https://en.wikipedia.org/wiki/Rounding#Rounding_away_from_zero), - [PHP\_ROUND\_TOWARD\_ZERO](https://en.wikipedia.org/wiki/Rounding#Rounding_toward_zero). > **Note:** The aforementioned constants have been transformed into an enum in a [follow-up RFC](https://externals.io/rfc/correctly_name_the_rounding_mode_and_make_it_an_enum). Two first comments on the [documentation page of the round()](https://www.php.net/manual/en/function.round.php) function are related to the missing modes of rounding. The first comment has an outstanding number of 309 votes. Moreover, the [NumberFormatter](https://www.php.net/manual/en/class.numberformatter.php) already implements 4 new proposed modes known as ROUND\_CEILING, ROUND\_FLOOR, ROUND\_DOWN, ROUND\_UP. ## Proposal Adding 4 new constants for the rounding modes of function round(): - PHP\_ROUND\_CEILING - rounds num to the nearest integer bigger than num, - PHP\_ROUND\_FLOOR - rounds num to the nearest integer lower than num, - PHP\_ROUND\_AWAY\_FROM\_ZERO - rounds num away from zero, - PHP\_ROUND\_TOWARD\_ZERO - rounds num towards zero. Creating two aliases of constants from Intl extension to have consistent naming for rounding modes: - ROUND\_TOWARD\_ZERO (equivalent of PHP\_ROUND\_TOWARD\_ZERO) alias of [ROUND\_DOWN](https://www.php.net/manual/en/class.numberformatter.php#numberformatter.constants.round-down) - ROUND\_AWAY\_FROM\_ZERO (equivalent of PHP\_ROUND\_AWAY\_FROM\_ZERO) alias of [ROUND\_UP](https://www.php.net/manual/en/class.numberformatter.php#numberformatter.constants.round-up) ## Backward Incompatible Changes None ## Proposed PHP Versions 8.4 ## Questions ### Why not use functions ceil() and floor()? The functions ceil() and floor() round numbers to the full integer, while the function round() rounds the number by given precision. Implementing new rounding modes we get equivalent of those functions using round() with 0 as precision. ```php ceil($number) === round($number, 0, PHP_ROUND_CEILING); //true floor($number) === round($number, 0, PHP_ROUND_FLOOR); //true ``` ### Why not the names PHP\_ROUND\_UP and PHP\_ROUND\_DOWN? Such constants already exist in the [NumberFormatter](https://www.php.net/manual/en/class.numberformatter.php) and represent rounding modes 'away from zero' and 'toward zero'. However the names rounding up and down are ambiguous. They may be easily confused with the rounding ceiling/floor, while the terms away from/toward zero are distinct. Those constants would be deprecated and replaced with their corresponding aliases: ROUND\_TOWARD\_ZERO and ROUND\_AWAY\_FROM\_ZERO. ### Why not the enum implementation for the rounding modes? As this is extension of the existing modes we should add complementary modes to the existing constants instead implementing new Enum. This way enum is an addition to the new constants and is not included into this RFC. ## Proposed Voting Choices As per the voting RFC a yes/no vote with a 2/3 majority is needed for this proposal to be accepted. Voting started on 2023-11-15 and will end on 2023-11-30 00:00 GMT. **Vote: Implement 4 new rounding modes to `round()` function** — Yes: 19 · No: 0 (closed) --- If the first voting is not accepted the result of the second voting will be ignored. **Vote: Create aliases for Intl extension constants ROUND\_UP and ROUND\_DOWN: ROUND\_AWAY\_FROM\_ZERO and ROUND\_TOWARD\_ZERO** — Yes: 10 · No: 6 (closed) ## Implementation GitHub pull request: ## References Links to external references, discussions or RFCs ## Rejected Features Keep this updated with features that were discussed on the mail lists.