Newsgroups: php.internals
Path: news.php.net
Xref: news.php.net php.internals:123068
Feedback-ID: id5114917:Fastmail
Content-Type: multipart/alternative;
 boundary="------------tvwiJpQj0Jir0JeTAfYr811P"
Message-ID: <6628b5e3-5f4b-4c9c-a940-56f72a645af1@rwec.co.uk>
Date: Tue, 9 Apr 2024 20:27:11 +0100
Precedence: bulk
MIME-Version: 1.0
User-Agent: Mozilla Thunderbird
Subject: Re: [PHP-DEV] [RFC] [Discussion] Support object type in BCMath
To: internals@lists.php.net
References: <4F094EDA-5058-407D-AF39-06FD934FDE1F@sakiot.com>
Content-Language: en-GB
In-Reply-To: <4F094EDA-5058-407D-AF39-06FD934FDE1F@sakiot.com>
From: imsop.php@rwec.co.uk ("Rowan Tommins [IMSoP]")

This is a multi-part message in MIME format.
--------------tvwiJpQj0Jir0JeTAfYr811P
Content-Type: text/plain; charset=UTF-8; format=flowed
Content-Transfer-Encoding: 7bit

On 24/03/2024 13:13, Saki Takamachi wrote:
> https://wiki.php.net/rfc/support_object_type_in_bcmath


Based on the various discussions we've been having, I'd like to propose 
a simplified handling of "scale".

I think there are two groups of users we are trying to help:

a) Users who want an "infinite" scale, and will round manually when 
absolutely necessary, e.g. for display. The scale can't actually be 
infinite in the case of calculations like 1/3, so they need some safe 
cut-off.

b) Users who want to perform operations on a fixed scale, with 
configurable rounding, e.g. for e-commerce pricing. They are not 
interested in any larger scale, except possibly in some intermediate 
calculations, when they want the same as group (a).

I propose:

- The constructor accepts string|int $num only.

- All operations accept an optional scale and rounding mode.

- If no rounding mode is provided, the default behaviour is to truncate. 
This means that (new BCMath\Number('20'))->div(3, 5) has the same result 
as bcdiv('20', '3', 5) which is 6.66666

- If a rounding mode is provided, the object transparently calculates 
one extra digit of scale, then rounds according to the specified mode.

- If no scale is provided, most operations will automatically calculate 
the required scale, e.g. add will use the larger of the two scales. This 
is the same as the current RFC.

- If no scale is provided to div(), sqrt(), or pow(-$x), the result will 
be calculated to the scale of the left-hand operand, plus 10. This is 
the default behaviour in the current RFC.

- Operator overloads behave the same as not specifying a scale or 
rounding mode to the corresponding method. Therefore (new 
BCMath\Number('20')) / (new BCMath\Number('3')) will result in 
6.6666666666 - an automatic scale of 10, and truncation of further digits.

Compared to the current RFC, that means:

- Remove the ability to customise "max expansion scale". For most users, 
this is a technical detail which is more confusing than useful. Users in 
group (b) will never encounter it, because they will specify scale 
manually; advanced users in group (a) may want to customise the logic in 
different ways anyway.

- Remove the ability for a Number value to carry around its own default 
rounding mode. Users in group (a) will never use it. Users in group (b) 
are likely to want the same rounding in the whole application, but 
providing it on every call to new Number() is no easier than providing 
it on each fixed-scale calculation.

- Remove the $maxExpansionScale and $roundingMode properties and 
constructor parameters.

- Remove withMaxExpansionScale and withRoundMode.

- Remove all the logic around propagating rounding mode and expansion 
scale between objects.

I've also noticed that the round method is currently defined as:

- public function round(int $precision = 0, int $mode = 
PHP_ROUND_HALF_UP): Number {}

Presumably $precision here is actually the desired scale of the result? 
If so, it should probably be named $scale, as in the rest of the interface.

I realise it's called $precision in the global round() function; that's 
presumably a mistake which is now hard to fix due to named parameters.

Ideally, it would be nice to have both roundToPrecision() and 
roundToScale(), but as Jordan explained, an implementation which 
actually calculated precision could be difficult and slow.

Regards,

-- 
Rowan Tommins
[IMSoP]

--------------tvwiJpQj0Jir0JeTAfYr811P
Content-Type: text/html; charset=UTF-8
Content-Transfer-Encoding: 7bit

<!DOCTYPE html>
<html>
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
  </head>
  <body>
    <div class="moz-cite-prefix">On 24/03/2024 13:13, Saki Takamachi
      wrote:<br>
    </div>
    <blockquote type="cite"
      cite="mid:4F094EDA-5058-407D-AF39-06FD934FDE1F@sakiot.com">
      <pre class="moz-quote-pre" wrap="">
<a class="moz-txt-link-freetext" href="https://wiki.php.net/rfc/support_object_type_in_bcmath">https://wiki.php.net/rfc/support_object_type_in_bcmath</a></pre>
    </blockquote>
    <p><br>
    </p>
    <p><span style="white-space: pre-wrap">Based on the various discussions we've been having, I'd like to propose a simplified handling of "scale".</span></p>
    <p><span style="white-space: pre-wrap">
</span></p>
    <p><span style="white-space: pre-wrap">I think there are two groups of users we are trying to help:</span></p>
    <p><span style="white-space: pre-wrap">a) Users who want an "infinite" scale, and will round manually when absolutely necessary, e.g. for display. The scale can't actually be infinite in the case of calculations like 1/3, so they need some safe cut-off.</span></p>
    <p><span style="white-space: pre-wrap">b) Users who want to perform operations on a fixed scale, with configurable rounding, e.g. for e-commerce pricing. They are not interested in any larger scale, except possibly in some intermediate calculations, when they want the same as group (a).</span></p>
    <p><span style="white-space: pre-wrap">
</span></p>
    <p><span style="white-space: pre-wrap">I propose:</span></p>
    <p><span style="white-space: pre-wrap">- The constructor accepts string|int $num only.</span></p>
    <p><span style="white-space: pre-wrap">- All operations accept an optional scale and rounding mode.</span></p>
    <p><span style="white-space: pre-wrap">- If no rounding mode is provided, the default behaviour is to truncate. This means that (new BCMath\Number('20'))-&gt;div(3, 5) has the same result as bcdiv('20', '3', 5) which is </span>6.66666</p>
    <p>- If a rounding mode is provided, the object transparently
      calculates one extra digit of scale, then rounds according to the
      specified mode.</p>
    <p>- If no scale is provided, most operations will automatically
      calculate the required scale, e.g. add will use the larger of the
      two scales. This is the same as the current RFC.<br>
    </p>
    <p>- If no scale is provided to div(), sqrt(), or pow(-$x), the
      result will be calculated to the scale of the left-hand operand,
      plus 10. This is the default behaviour in the current RFC.</p>
    <p>- Operator overloads behave the same as not specifying a scale or
      rounding mode to the corresponding method. Therefore <span
      style="white-space: pre-wrap">(new BCMath\Number('20')) / (new BCMath\Number('3')) will result in 6.6666666666 - an automatic scale of 10, and truncation of further digits.</span></p>
    <p><span style="white-space: pre-wrap">
</span></p>
    <p><span style="white-space: pre-wrap">Compared to the current RFC, that means:
</span></p>
    <p><span style="white-space: pre-wrap">- Remove the ability to customise "max expansion scale". For most users, this is a technical detail which is more confusing than useful. Users in group (b) will never encounter it, because they will specify scale manually; advanced users in group (a) may want to customise the logic in different ways anyway.</span></p>
    <p><span style="white-space: pre-wrap">- Remove the ability for a Number value to carry around its own default rounding mode. Users in group (a) will never use it. Users in group (b) are likely to want the same rounding in the whole application, but providing it on every call to new Number() is no easier than providing it on each fixed-scale calculation.</span></p>
    <p><span style="white-space: pre-wrap">- Remove the $maxExpansionScale and $roundingMode properties and constructor parameters.
</span></p>
    <p><span style="white-space: pre-wrap">- Remove withMaxExpansionScale and withRoundMode.
</span></p>
    <p><span style="white-space: pre-wrap">- Remove all the logic around propagating rounding mode and expansion scale between objects.
</span></p>
    <p><span style="white-space: pre-wrap">
</span></p>
    <p><span style="white-space: pre-wrap">I've also noticed that the round method is currently defined as:</span></p>
    <p><span style="white-space: pre-wrap">- public function round(int $precision = 0, int $mode = PHP_ROUND_HALF_UP): Number {}</span></p>
    <p><span style="white-space: pre-wrap">Presumably $precision here is actually the desired scale of the result? If so, it should probably be named $scale, as in the rest of the interface. </span></p>
    <p><span style="white-space: pre-wrap">I realise it's called $precision in the global round() function; that's presumably a mistake which is now hard to fix due to named parameters.</span></p>
    <p><span style="white-space: pre-wrap">Ideally, it would be nice to have both roundToPrecision() and roundToScale(), but as Jordan explained, an implementation which actually calculated precision could be difficult and slow.
</span></p>
    <p><span style="white-space: pre-wrap">
</span></p>
    <p>Regards,</p>
    <pre class="moz-signature" cols="72">-- 
Rowan Tommins
[IMSoP]</pre>
  </body>
</html>

--------------tvwiJpQj0Jir0JeTAfYr811P--