Specify rounding mode in CORE

[tony-o]

add HALF-[UP|DOWN|EVEN|ODD] | [TO|FROM]-ZERO...

Rounding method was something requested (because of IEEE standards), discussion should be continued here from see:rakudo/rakudo#2831. I don't take issue with this being merged though some say it should be in a Stats module (I don't take issue with that, either) but that door swings both ways and perhaps all rounding should be done in a stats module? The line is blurry.

Anyway, discussion should continue here. If I don't hear much back in the way of arguments against then I will make the assumption that it is ok to push the merge.

Notifying @coke @ugexe @AlexDaniel (because you participated in the original thread).

[jnthn]

I don't see any references to exactly what standards call for this, though in principle if they are widespread and basic standards then providing the math in CORE.setting required to implement them seems fairly reasonable. Some thoughts:

• I see the proposed patch only adds them to Rational, but I'd expect they apply to Num also?
• I'd prefer a design where we pass an enum value to define the rounding mode, since it makes no sense to use them in combination. The Rakudo PR comments it "ignores everything after the first", and I'm not sure whether it means "it only considers the first named argument" (not true) or "it considers only the first candidate whose where clause matches" (true). To really nail down the behavior, we'd thus have to specify the order of the candidates. That feels odd. A single mode argument side-steps that.
• We today have 123.45.round(0.1) also, and should specify how - or indeed if - this feature interacts with it.

[alabamenhu]

I don't see any references to exactly what standards call for this, though in principle if they are widespread and basic standards then providing the math in CORE.setting required to implement them seems fairly reasonable.

IEEE 754 specifies half-even as the default (and Java, Haskell, and Python use that). FWIW, Raku follows C/C++ with away-from-zero, and JavaScript uniquely goes with half-up. Modern Fortran lets you set it (with the appropriately named function ieee_set_rounding_mode), but defaults are left implementation specific.

• I'd prefer a design where we pass an enum value to define the rounding mode, since it makes no sense to use them in combination.

That makes sense. If it could pass a string that would be interpreted as an enum, that would be fairly clean enough: .round(10, :mode<half-up>)

• We today have 123.45.round(0.1) also, and should specify how - or indeed if - this feature interacts with it.

So technically the rounding modes in IEEE aren't based on *.5, but rather as a tie breaker when the values are exactly halfway between the round candidates. In quick illustrative code:

method round(\num: \interval = 1, :$mode = 'away-from-zero') {
  my \div  = floor(num / interval)
  my \low  =  interval *  div;
  my \high = interval * (div + 1);
  my \mid  = (floor + high ) / 2;

  do given (low + high) / 2 {
    when * > mid { high }
    when * < mid { low  }
    
    #| Apply tie break conditions here.
    default { 
      do given round-mode {
        when 'away-from-zero' { high }  # Raku default
        when 'toward-zero'    { low  } 
        when 'half-even'      { div %% 2 ?? low  !! high } # IEEE default
        when 'half-odd'       { div %% 2 ?? high !! low  }
        when 'half-up'        { mid  > 0 ?? high !! low  }
        when 'half-down'      { mid  > 0 ?? low  !! high }
       }
    }
}

Note that the above isn't 100% accurate, as the half-even's definition is based on the least significant bit (which might not be clear with Rat?):

IEEE Std. 758-2019 § 4.3.1 (p. 27)
roundTiesToEven, the floating-point number nearest to the infinitely precise result shall be
delivered; if the two nearest floating-point numbers bracketing an unrepresentable infinitely
precise result are equally near, the one with an even least significant digit shall be delivered; if
that is not possible, the one larger in magnitude shall be delivered (this can happen for one-digit
precision, possible with convertToDecimalCharacter for example, as when rounding 9.5 to one
digit in which case both 9 and 1×10¹ have odd significands)

[AlexDaniel]

So technically the rounding modes in IEEE aren't based on *.5, but rather as a tie breaker when the values are exactly halfway between the round candidates. In quick illustrative code:

So what kind of rounding are we talking about exactly? Especially considering that you can call .round on Num and Rat.

[alabamenhu]

*So technically the rounding modes in IEEE aren't based on .5, but rather as a tie breaker when the values are exactly halfway between the round candidates. In quick illustrative code:

So what kind of rounding are we talking about exactly? Especially considering that you can call .round on Num and Rat.

The rounding modes in IEEE are defined for floating point, but the concept applies equally as well for other types of numbers. You can .round(100) on an Int or Rat .round by default calls .round(1), @jnthn was asking about the implications for when the rounding is on a radix that is different from 1 (e.g. rounding to the nearest tenth). The same issue is present.

[alabamenhu]

Actually, in trying to illustrate an example, I realized that we actually do half up, it's just not intuitive because -1.5.round is interpolated as (-((1.5).round)), rather than ((-(1.5)).round). The only other programming language I can think of that does half up is JavaScript.

[alabamenhu]

But in digging up more information, I found the following from our ye olde Perl 6 Syponses:

round (S32-num/rounders.t lines 8–315)
multi method round ( Real $x: $scale = 1 --> Real ) is export
With no arguments, returns the nearest integer to $x. If $scale is given, rounds $x to the nearest multiple of $scale. The algorithm is:
floor($x / $scale + 0.5) * $scale
(Other rounding algorithms will be given extended names beginning with "round".)

So the intent from the beginning was always to have different rounding modes available in core. My reading is that the original intent was to have round-down, round-even, round-odd, round-away, round-towards or similar be the "extended names", but I think the easier route today is a :mode<up>, :mode<down>, :mode<to-zero>, and possibly even:mode<alternate>, :mode<random> :mode<stomachastic>(or at least leaving it as a multi so stats modules could handle them, although having basic stats stuff in core wouldn't be a bad thing).