PHP RFC: Adding bcround, bcfloor and bcceil to BCMath
- Version: 0.1.0
- Date: 2023-10-01
- Author: Saki Takamachi, firstname.lastname@example.org
- Status: Accepted
- First Published at: https://wiki.php.net/rfc/adding_bcround_bcfloor_bcceil_to_bcmath
As you know, BCMath is an arbitrary precision mathematical function that supports exact calculations. As of the writing of this RFC, nine calculation functions exist, but no equivalents exist for round, floor, and ceil. Considering the role of BCMath, supporting features like these is important.
This RFC proposes to introduce three new functions to BCMath: bcround(), bcfloor(), and bcceil(). It is assumed that the usage will be the same as round(), floor(), and ceil(), except that the value passed to the argument and the return value will be of string type.
var_dump(bcround('0.285', 2, PHP_ROUND_HALF_UP)); // string(4) "0.29" var_dump(bcfloor('13.0915')); // string(2) "13" var_dump(bcceil('24.00001')); // string(2) "25"
Since it is an arbitrary precision calculation, there is no need to consider the maximum value of int or double.
var_dump(bcround('0.12345678901234567890123456789', 28)); // string(30) "0.1234567890123456789012345679" var_dump(bcfloor('123456789012345678901234567890.5')); // string(30) "123456789012345678901234567890" var_dump(bcceil('123456789012345678901234567890.5')); // string(30) "123456789012345678901234567891"
Round mode constant
Similar to round(), we can specify how edge cases are handled using mode. I plan to use the constants for round() included in standard ext as they are. The reason for reusing standard ext constants is as follows.
- standard ext is installed by default
- It is not a constant that expresses a complex concept enough to prepare a new constant for BCMath
- Having multiple similar constants is unfriendly
- These constants do not change frequently, and reusing them does not impede maintenance
Ignore BCMath scale
BCMath allows you to specify the scale of calculation results. You can pass values to arguments on a per-function basis, or you can set default values for BCMath and omit arguments.
Due to their nature, there is no point in setting the scale of the three functions proposed this time. Therefore, these functions ignore scale settings both semantically and implementationally.
You might think that it can be used to specify the precision of round, but scale does not accept negative values. This cannot be used because precision must accept negative values.
Backward Incompatible Changes
These are new features and do not break existing functionality.
If I had to point out my concerns, I would say that code that satisfies the following conditions will cause an error to occur.
- A situation where the user has defined a function with the same name, such as bcround()
- And, the existence of the function is not checked in advance.
However, I do not think it is necessary to consider these matters.
Proposed PHP Version(s)
next PHP 8.x (Probably 8.4)
To Existing Extensions
Only BCMath is affected.
Unaffected PHP Functionality
There is no effect on anything other than BCMath.
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.
Patches and Tests
I am currently creating a prototype.
- 0.1.0: created rfc