rfc:fix_up_bcmath_number_class

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Next revision		Previous revision
rfc:fix_up_bcmath_number_class [2024/06/30 14:57] – created sakirfc:fix_up_bcmath_number_class [2024/09/04 02:15] (current) – saki
Line 3: Line 3:
   * Date: 2024-06-30   * Date: 2024-06-30
   * Author: Saki Takamachi (saki@php.net)   * Author: Saki Takamachi (saki@php.net)
-  * Status: Under Discussion+  * Status: Implemented
   * First Published at: https://wiki.php.net/rfc/fix_up_bcmath_number_class   * First Published at: https://wiki.php.net/rfc/fix_up_bcmath_number_class
  
Line 12: Line 12:
  
 ===== Proposal ===== ===== Proposal =====
-This RFC makes several corrections and changes to the <php>BCMath\Number</php> class and proposes to override the first RFC.+This RFC makes several corrections and changes to the <php>BcMath\Number</php> class and proposes to override the first RFC.
  
-Also proposes that when cast a GMP object to bool, change it so that <php>0</php> is <php>false</php> and everything else is <php>true</php>, like an int.+It also proposes that when a GMP object is cast to bool, change it so that <php>0</php> is <php>false</php> and everything else is <php>true</php>, like an int.
  
 Details of the proposal regarding BCMath are as follows: Details of the proposal regarding BCMath are as follows:
   - Casting a Number object to bool makes it <php>false</php> if it is <php>0</php> and <php>true</php> otherwise.   - Casting a Number object to bool makes it <php>false</php> if it is <php>0</php> and <php>true</php> otherwise.
-  - Of the six comparison methods <php>comp()</php>, <php>eq()</php>, <php>gt()</php>, <php>gte()</php>, <php>lt()</php>, <php>lte()</php>, remove five except <php>comp()</php>. +  - Of the six comparison methods <php>comp()</php>, <php>eq()</php>, <php>gt()</php>, <php>gte()</php>, <php>lt()</php>, <php>lte()</php>, remove all except <php>comp()</php>. Then rename the <php>comp()</php> method to <php>compare()</php>. 
-  - Remove format method.+  - Remove <php>format()</php> method. 
 +  - Remove rounding in calculations. 
 +  - Make it serializable.
   - Fixed typo in stub.   - Fixed typo in stub.
  
Line 29: Line 31:
  
 === More information about comparison methods === === More information about comparison methods ===
-In fact, only need the <php>comp()</php> method to fulfill the functionality of the other five methods.+In fact, only the <php>comp()</php> method is needed to fulfill the functionality of the other five methods.
  
-Adding methods later is easy, but removing them always involves a BC Break.  Providing 6 methods from the start is obviously overkill, so will only provide <php>comp()</php>.+Adding methods later is easy, but removing them always involves a BC Break.  Providing 6 methods from the start is obviously overkill, so we will only provide <php>comp()</php>.
  
-By the way, the reason <php>comp()</php> is needed, and why comparison operators are underpowered, is to specify the scale to use for the comparison. +By the way, the reason <php>comp()</php> is needed, and why comparison operators are underpowered, is to specify the scale to use for the comparison. 
 + 
 +Currently, there is no other expression for comparison in PHP called "comp". The expression "cmp" is mainly used for functions, and the expression "compare" is used for class methods. 
 + 
 +e.g. 
 +https://www.php.net/manual/ja/splpriorityqueue.compare.php 
 +https://www.php.net/manual/ja/collator.compare.php 
 + 
 +Therefore, follow these conventions and rename <php>comp()</php> to <php>compare()</php>. 
 + 
 +<PHP> 
 +public function compare(Number|string|int $num, ?int $scale = null): int {} 
 +</PHP>
  
 === Remove format method === === Remove format method ===
Line 40: Line 54:
  
 If released in a half-finished state, BC Break will become a problem later, so this feature will be removed. If this functionality is really needed for this class, we can always consider adding it again. If released in a half-finished state, BC Break will become a problem later, so this feature will be removed. If this functionality is really needed for this class, we can always consider adding it again.
 +
 +=== Remove rounding in calculations ===
 +
 +The current specification does not allow calculations with operators to be used by users who do not want rounding. I also found it very inconvenient to have to specify an optional argument every time I perform a calculation using this method if I don't want rounding.
 +
 +e.g.
 +<PHP>
 +$ret = $num->div($num2, null, PHP_ROUND_TOWARD_ZERO);
 +</PHP>
 +
 +If the default behavior is "no rounding", i.e., truncation behavior like the existing BCMath functions, if you want to perform rounding, you can simply use the round() method.
 +
 +<PHP>
 +$ret = $num->div($num2)->round(2);
 +</PHP>
 +
 +Based on the idea that we shouldn't provide an API that looks "rich" from the get-go, I suggest removing all of these roundings.
 +
 +In other words, the rounding mode during calculations will be fixed at truncation, and the user will not be able to change it. This applies to both operator and method calculations.
 +
 +If the user wants to do rounding, the <php>round()</php> method should be used.
 +
 +===  Make it serializable ===
 +
 +Being serializable is very important when using something like Redis, as this is expected to be used as a value object. This probably doesn't require an RFC on its own, but I mention it to keep things clear.
  
 === Fixed typo in stub ===  === Fixed typo in stub === 
Line 58: Line 97:
 BCMath: None. BCMath: None.
  
-GMP: Code like <php>if ($gmp) {}</php> will behave differently. However, due to the nature of GMP, such codes are likely to be quite rare.+GMP: Code like <php>if ($gmp) {}</php> will behave differently. However, due to the nature of GMP, such code is likely to be quite rare.
  
 ===== Proposed PHP Version(s) ===== ===== Proposed PHP Version(s) =====
Line 98: Line 137:
  
 These are not second-round votes, so each requires a two-thirds majority vote to pass. These are not second-round votes, so each requires a two-thirds majority vote to pass.
 +
 +Voting ends on 2024-07-30 00:00:00 UTC.
 +
 +<doodle title="Fix up BCMath Number Class" auth="Saki Takamachi" voteType="single" closed="false" closeon="2024-07-30T00:00:00Z">
 +   * Yes
 +   * No
 +</doodle>
 +----
 +<doodle title="Change GMP bool cast behavior" auth="Saki Takamachi" voteType="single" closed="false" closeon="2024-07-30T00:00:00Z">
 +   * Yes
 +   * No
 +</doodle>
  
 ===== Patches and Tests ===== ===== Patches and Tests =====
Line 103: Line 154:
  
 ===== Implementation ===== ===== Implementation =====
-None.+https://github.com/php/php-src/pull/13741 
 +https://github.com/php/php-src/pull/15151
  
 ===== References ===== ===== References =====
rfc/fix_up_bcmath_number_class.1719759477.txt.gz · Last modified: 2024/06/30 14:57 by saki

Page Tools