Everything

php

Introducing 2 new modes to round function

php.internals

Joerg Sowa

3 years ago

Hello internals!

I would like to propose introducing two new modes to the function
`round()`: PHP_ROUND_DOWN and PHP_ROUND_UP.

Those modes are highly requested as you can see by the comments on round
documentation page. First comment mentioning about those modes has 309
votes as of today. Introducing those 2 modes would be complementing to the
rounding in this function.

Round documentation: https://www.php.net/manual/en/function.round.php
My implementation: https://github.com/php/php-src/pull/11741

I'm not sure if such minor improvement requires RFC, but as someone may
have some concerns I create this thread to get your feedback.

Kind regards,
Jorg

Marco Pivetta

3 years ago

Hey Jorg,

What is the reason for using this over these?

* https://www.php.net/manual/en/function.ceil.php
* https://www.php.net/manual/en/function.floor.php

On Fri, 21 Jul 2023, 21:26 Jorg Sowa, <jorg.sowa@gmail.com> wrote:

Dusk

3 years ago

On Jul 21, 2023, at 12:38, Marco Pivetta <ocramius@gmail.com> wrote:

> Hey Jorg,
>
> What is the reason for using this over these?
>
> * https://www.php.net/manual/en/function.ceil.php
> * https://www.php.net/manual/en/function.floor.php

floor() and ceil() don't have a $precision parameter.

What could be even more useful, however, would be to add modes which always round towards / away from zero. I suspect the commenter intending to use these modes in accounting would prefer these semantics over an implementation (like theirs) which always rounds to numerically higher / lower values.

It might also be appropriate to use more specific terminology for these modes, e.g. PHP_ROUND_FLOOR/_CEIL and PHP_ROUND_TO_ZERO/_AWAY_FROM_ZERO, rather than the ambiguous PHP_ROUND_DOWN.

Marco Pivetta

3 years ago

On Fri, 21 Jul 2023, 22:05 Dusk, <dusk@woofle.net> wrote:

> On Jul 21, 2023, at 12:38, Marco Pivetta <ocramius@gmail.com> wrote:
> > Hey Jorg,
> >
> > What is the reason for using this over these?
> >
> > * https://www.php.net/manual/en/function.ceil.php
> > * https://www.php.net/manual/en/function.floor.php
>
> floor() and ceil() don't have a $precision parameter.
>

Thanks for clarifying 👍

Joerg Sowa

3 years ago

Thank you for your suggestions. I added two remaining modes and I think
it's complete now.

I changed the names to `PHP_ROUND_CEILING` and `PHP_ROUND_FLOOR` to be
consisted with rounding modes in number_format() function. I'm not sure
about `PHP_TOWARD_ZERO` and 'PHP_AWAY_FROM_ZERO` as in there it's
`ROUND_DOWN` and `ROUND_UP`, which I also find too vague.

However, I could find names UP and DOWN in other documentations. And sadly
it refers to away from zero and toward zero, so there is big mismatch in
existing naming.

https://developer.apple.com/documentation/foundation/numberformatter/roundingmode/down
https://docs.oracle.com/en/java/javase/20/docs/api/java.base/java/math/RoundingMode.html

Kind regards,
Jorg
<https://developer.apple.com/documentation/foundation/numberformatter/roundingmode/down>

Jordan LeDoux

3 years ago

On Fri, Jul 21, 2023 at 3:48 PM Jorg Sowa <jorg.sowa@gmail.com> wrote:

> Thank you for your suggestions. I added two remaining modes and I think
> it's complete now.
>
> I changed the names to `PHP_ROUND_CEILING` and `PHP_ROUND_FLOOR` to be
> consisted with rounding modes in number_format() function. I'm not sure
> about `PHP_TOWARD_ZERO` and 'PHP_AWAY_FROM_ZERO` as in there it's
> `ROUND_DOWN` and `ROUND_UP`, which I also find too vague.
>
> However, I could find names UP and DOWN in other documentations. And sadly
> it refers to away from zero and toward zero, so there is big mismatch in
> existing naming.
>
>
> https://developer.apple.com/documentation/foundation/numberformatter/roundingmode/down
>
> https://docs.oracle.com/en/java/javase/20/docs/api/java.base/java/math/RoundingMode.html
>

I had to deal with this issue when I was doing the rounding modes for my
math library in PHP. I ended up providing the following rounding modes:

- Half Up (Positive Infinity)
- Half Down (Negative Infinity)
- Half Even
- Half Odd
- Half Zero
- Half Infinity (Closest)
- Half Random (50% chance of either direction)
- Half Alternating (Each subsequent call to round alternates rounding
direction)
- Stochastic (Chance of direction based on proximity... i.e. 1.7 rounds to
2 70% of the time, and rounds to 1 30% of the time)

The only reason I used "Half Up" and "Half Down" is because I also used
"Half Zero" and "Half Infinity" so it was more clear there were
differences. Stochastic is probably the one that sounds weirdest to most
people, but is insanely useful for applications like Machine Learning.

Jordan

Andreas Heigl

3 years ago

On 21 July 2023 21:38:03 CEST, Marco Pivetta <ocramius@gmail.com> wrote:

> Hey Jorg,
>
> What is the reason for using this over these?
>
>  * https://www.php.net/manual/en/function.ceil.php
>  * https://www.php.net/manual/en/function.floor.php
>
>

Hey Marco

floor and ceil convert a float to the next int.

round can also convert to the next decimal-,level.

round(16, -1) will round to 20 whereas round(12, -1) will be 10. And tuere's no way currently to make the first one 10 and the second one 20.

Cheers

Andreas

>
> On Fri, 21 Jul 2023, 21:26 Jorg Sowa, <jorg.sowa@gmail.com> wrote:
>
> > Hello internals!
> >
> > I would like to propose introducing two new modes to the function
> > `round()`: PHP_ROUND_DOWN and PHP_ROUND_UP.
> >
> > Those modes are highly requested as you can see by the comments on round
> > documentation page. First comment mentioning about those modes has 309
> > votes as of today. Introducing those 2 modes would be complementing to the
> > rounding in this function.
> >
> > Round documentation: https://www.php.net/manual/en/function.round.php
> > My implementation: https://github.com/php/php-src/pull/11741
> >
> > I'm not sure if such minor improvement requires RFC, but as someone may
> > have some concerns I create this thread to get your feedback.
> >
> > Kind regards,
> > Jorg
> >

--
Andreas Heigl

Mark Baker

3 years ago

Once upon a many years ago: https://github.com/php/php-src/pull/1658

It will be nice to see it finally get and implementation

On 21/07/2023 21:26, Jorg Sowa wrote:

> Hello internals!
>
> I would like to propose introducing two new modes to the function
> `round()`: PHP_ROUND_DOWN and PHP_ROUND_UP.
>
> Those modes are highly requested as you can see by the comments on round
> documentation page. First comment mentioning about those modes has 309
> votes as of today. Introducing those 2 modes would be complementing to the
> rounding in this function.
>
> Round documentation: https://www.php.net/manual/en/function.round.php
> My implementation: https://github.com/php/php-src/pull/11741
>
> I'm not sure if such minor improvement requires RFC, but as someone may
> have some concerns I create this thread to get your feedback.
>
> Kind regards,
> Jorg
>

--
Mark Baker

Joerg Sowa

3 years ago

I had no idea about your PR Mark. It's pity to see that many improvements
(even simple) like this eventually was not implemented, despite the effort
authors put into.

I have created PR with the change. https://github.com/php/php-src/pull/12056

If you think I should proceed with RFC please let me know. Of course it
will not be merged into the PHP 8.3, but the next version.

Kind regards,
Jorg

Joerg Sowa

3 years ago

Hello everyone,
As I am not sure what I should next I decided to follow the formal way and
I created the RFC for the change. I will start voting soon. Please let me
know if you have any suggestions.

RFC under discussion:
https://wiki.php.net/rfc/new_rounding_modes_to_round_function

Niels Dossche

3 years ago

On 8/31/23 01:16, Jorg Sowa wrote:

> Hello everyone,
> As I am not sure what I should next I decided to follow the formal way and
> I created the RFC for the change. I will start voting soon. Please let me
> know if you have any suggestions.
>
> RFC under discussion:
> https://wiki.php.net/rfc/new_rounding_modes_to_round_function
>

Hey Jorg

You should announce the start of the discussion in a new email thread instead of reusing your old one.
The subject should be something like "[RFC] [Discussion] Add 4 new rounding modes to round() function".
This is done for maximal visibility.

Also, I believe the link for "PHP_ROUND_CEILING" is wrong in your RFC.

Kind regards
Niels