Add BigDecimal#round(digits, mode) overload

[Sija]

Fixes #5714

TBD:

• BigDecimal.rounding_mode
• BigDecimal.save_rounding_mode
• BigDecimal.with_rounding_mode
• Implementation review
• Specs
• Docs

[Sija]

Ready for review.

[Sija]

@RX14 @bcardiff @asterite would you mind a rrrreview?

[RX14]

This doesn't even attempt to be compatible with Number#round. It also seems completely unoptimized, have you looked at what other implementations do here?

[Sija]

This doesn't even attempt to be compatible with Number#round.

That's true, some goes for Float{32,64}#round and Int#round (they handle neither ndigits, nor base arguments) - it would be nice to sort 'em out, but not before having uniformly working mode argument - which would be better done in a separate PR.

Ruby has more uniform API in this regard, with #round([ndigits][, mode]) signature.

It also seems completely unoptimized, have you looked at what other implementations do here?

Unfortunately, that's quite likely, but you're free to post your optimization suggestions, let's treat it as yet another Advent of Code puzzle ;)

[RX14]

I don't want to merge this before we sort out a rounding API on Number and make Int and Float follow it. Then we can make this PR follow that API too.

[Sija]

That's true, some goes for Float{32,64}#round and Int#round (they handle neither ndigits, nor base arguments) - it would be nice to sort 'em out, but not before having uniformly working mode argument - which would be better done in a separate PR.

I'd like to correct my statement, since Float{32,64}#round and Int#round are more like optimizations of Number#round, with exception of missing handling base argument; btw, is it really needed? Aside of digits and sometimes mode, I haven't seen much of it in stdlibs of other languages.

Now, as for cleaning up the API, I'd suggest dropping base argument, would leave us with consistent API of Float, Int and Number.

Additional (named?) argument mode support would stay for BigDecimal only. Would be nice to have it working for Number#round, but to my (limited) understanding, that would mean loosing Float#round optimization when mode argument is used.

[Sija]

@RX14 any thoughts?

[RX14]

Same as before, we need to unify the API. We should keep base.

[Sija]

@RX14 yeah, you said it before, any (counter) suggestions how? and why in your opinion should we keep base?

[Sija]

Hi, what's the status of this PR?

@RX14 proposed unification of Number rounding API stating that:

[...] We should keep base.

I disagree, personally I've never had a need to specify base while rounding, neither I've seen it anywhere in the wild. Ruby, JavaScript, Python, PHP - they all have pretty consistent APIs regarding rounding numbers, in which base is nowhere to be seen.

In terms of Number#round API unification I'd rather vote for removal of before-mentioned base argument.

BigDecimal#round is especially useful for money-related shards, thus its absence hurts stdlib functionality and BigDecimal feature set.

I'd like to continue working on it once some course of action is settled.

[Sija]

Mornin' ☀️ !

I've force-pushed refactored implementation which, I believe should be a tad more performant, and so I'd like to revisit this PR if possible since this feature comes rrrly handy for these few occasions (think financial, especially crypto), thanks for the attention and have a great day there :) 🙏

Side note: Some of the GHA CI jobs (CircleCI is ✅ ) seem to use a stale cache or sth - the spec failures doesn't seem to cover for the actual code - that or... might a be a red herring since it's already just a bit l8 for me - or early for that matter 🙃

[Sija]

ping, could this get a review please? /cc @straight-shoota @asterite @waj

[asterite]

@Sija I don't think this has any pressure to get into 1.0. There are a bunch of more important things right now to make sure 1.0 is properly released, so please be patient until we get some time to review this and other PRs. Thank you!

[straight-shoota]

This can now be refactored on top of #10413.

[straight-shoota]

I don't think we should add the global rounding_mode property. Or at least, it should be a different discussion. This should focus on implementing the missing rounding methods for use with Number#round. That is (probably?) just round_away and round_even.

It might actually be best to close this and start with a fresh PR.

[Sija]

@straight-shoota rebased on top of the current master.

[straight-shoota]

Please exclude rounding_mode setting from this PR. This feature warrants a dedicated discussion. If at all, it should probably be global to Number and not specific to BigDecimal (see #10414 (comment) ff.).

Also BigDecimal is missing the basic rounding mode methods #round_away and #round_even.

[straight-shoota]

Misclicked on Approve

[straight-shoota]

@Sija Are you up to address the last review commment and remove rounding_mode, add missing methods?

[Sija]

@straight-shoota Will do, sadly I'm not sure I can give you any sensible timeframe for that.

[HertzDevil]

This addition is incorrect, since value is already the BigDecimal itself, not the mantissa:

BigDecimal.new("123.456789").round(2, mode: :ties_away) # => 124.45

[HertzDevil]

With #10798 merged and the part about BigDecimal.rounding_mode deferred, this PR can probably be closed.

[straight-shoota]

Thank you both, @Sija and @HertzDevil =)