Newsgroups: php.internals
Path: news.php.net
Xref: news.php.net php.internals:123077
Content-Type: multipart/alternative; boundary=Apple-Mail-61C39246-93D5-47AE-AF20-34A19094A130
Content-Transfer-Encoding: 7bit
Precedence: bulk
Mime-Version: 1.0 (1.0)
Subject: Re: [PHP-DEV] [RFC] [Discussion] Support object type in BCMath
Date: Wed, 10 Apr 2024 08:36:21 +0900
Message-ID: <E7B8397C-4A45-45C8-A0FD-7DF581801861@sakiot.com>
References: <6628b5e3-5f4b-4c9c-a940-56f72a645af1@rwec.co.uk>
Cc: internals@lists.php.net
In-Reply-To: <6628b5e3-5f4b-4c9c-a940-56f72a645af1@rwec.co.uk>
To: "Rowan Tommins [IMSoP]" <imsop.php@rwec.co.uk>
From: saki@sakiot.com (Saki Takamachi)


--Apple-Mail-61C39246-93D5-47AE-AF20-34A19094A130
Content-Type: text/plain;
	charset=us-ascii
Content-Transfer-Encoding: quoted-printable

Hi Rowan,
a).
> I propose:
>=20
> - The constructor accepts string|int $num only.
>=20
> - All operations accept an optional scale and rounding mode.
>=20
> - If no rounding mode is provided, the default behaviour is to truncate. T=
his means that (new BCMath\Number('20'))->div(3, 5) has the same result as b=
cdiv('20', '3', 5) which is 6.66666
>=20
> - If a rounding mode is provided, the object transparently calculates one e=
xtra digit of scale, then rounds according to the specified mode.
>=20
> - If no scale is provided, most operations will automatically calculate th=
e required scale, e.g. add will use the larger of the two scales. This is th=
e same as the current RFC.
>=20
> - If no scale is provided to div(), sqrt(), or pow(-$x), the result will b=
e calculated to the scale of the left-hand operand, plus 10. This is the def=
ault behaviour in the current RFC.
>=20
> - Operator overloads behave the same as not specifying a scale or rounding=
 mode to the corresponding method. Therefore (new BCMath\Number('20')) / (ne=
w BCMath\Number('3')) will result in 6.6666666666 - an automatic scale of 10=
, and truncation of further digits.
>=20
>=20
>=20
> Compared to the current RFC, that means:
>=20
> - Remove the ability to customise "max expansion scale". For most users, t=
his is a technical detail which is more confusing than useful. Users in grou=
p (b) will never encounter it, because they will specify scale manually; adv=
anced users in group (a) may want to customise the logic in different ways a=
nyway.
>=20
> - Remove the ability for a Number value to carry around its own default ro=
unding mode. Users in group (a) will never use it. Users in group (b) are li=
kely 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-sca=
le calculation.
>=20
> - Remove the $maxExpansionScale and $roundingMode properties and construct=
or parameters.
>=20
> - Remove withMaxExpansionScale and withRoundMode.
>=20
> - Remove all the logic around propagating rounding mode and expansion scal=
e between objects.
>=20

I have two questions.
- The scale and rounding mode are not required for example in add, since the=
 scale of the result will never be infinite and we can automatically calcula=
te the scale needed to fit the result. Does adding those two options to all c=
alculations mean adding them to calculations like add as well?
- As Tim mentioned, it may be confusing to have an initial value separate fr=
om the mode of the `round()` method. Would it make sense to have an initial v=
alue of HALF_UP?

> I've also noticed that the round method is currently defined as:
>=20
> - public function round(int $precision =3D 0, int $mode =3D PHP_ROUND_HALF_=
UP): Number {}
>=20
> 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.=20=

>=20
> I realise it's called $precision in the global round() function; that's pr=
esumably a mistake which is now hard to fix due to named parameters.
>=20
> Ideally, it would be nice to have both roundToPrecision() and roundToScale=
(), but as Jordan explained, an implementation which actually calculated pre=
cision could be difficult and slow.
>=20
There is good news about this. The RFC for `bcround` does not specify the ar=
gument names, and the implementer (me) has decided on the argument names.
And it's a change that hasn't even been merged into master yet, so I can cha=
nge the argument name without any BC break.

Regards.

Saki=

--Apple-Mail-61C39246-93D5-47AE-AF20-34A19094A130
Content-Type: text/html;
	charset=utf-8
Content-Transfer-Encoding: 7bit

<html><head><meta http-equiv="content-type" content="text/html; charset=utf-8"></head><body dir="auto"><div dir="ltr"></div><div dir="ltr">Hi Rowan,</div><div dir="ltr"><span style="white-space: pre-wrap;">a).</span></div><blockquote type="cite"><div dir="ltr">
    <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></div></blockquote><div><br></div><div>I have two questions.</div><div>- The scale and rounding mode are not required for example in add, since the scale of the result will never be infinite and we can automatically calculate the scale needed to fit the result. Does adding those two options to all calculations mean adding them to calculations like add as well?</div><div>- As Tim mentioned, it may be confusing to have an initial value separate from the mode of the `round()` method. Would it make sense to have an initial value of HALF_UP?</div><div><br></div><blockquote type="cite"><div dir="ltr">
    <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>
  

</div></blockquote><div>There is good news about this. The RFC for `bcround` does not specify the argument names, and the implementer (me) has decided on the argument names.</div><div>And it's a change that hasn't even been merged into master yet, so I can change the argument name without any BC break.</div><div><br></div><div>Regards.</div><div><br></div><div>Saki</div></body></html>
--Apple-Mail-61C39246-93D5-47AE-AF20-34A19094A130--