Tracking Issue for `round_ties_even`

[Jules-Bertholet]

Feature gate: #![feature(round_ties_even)]

This is a tracking issue for the round_ties_even feature, which adds a new method to f32 and f64 for rounding to the nearest integer, with ties rounded to the nearest even number.

Public API

impl f32 {
    fn round_ties_even(self) -> f32;
}

impl f64 {
    fn round_ties_even(self) -> f64;
}

Steps / History

• Implementation: Add round_ties_even to f32 and f64 #95317
• Final comment period (FCP)
• Stabilization PR

Unresolved Questions

• Naming: round_ties_even, round_even, round_to_even, round_banker... many ways to paint this bikeshed
• Should the behavior of the round function be changed to this?
• Is it okay to use rint in the implementaton? (see Add round_ties_even to f32 and f64 #95317 (comment))

[Miksel12]

I think round should be changed to round ties to even, both x86 and ARM use it as the default rounding mode and IEEE 754 states it should be the default. It is also the mode with the least amount of bias.
As for round ties away from zero, which is the current mode used for round, it is actually not required by IEEE 754 for binary representation and is thus not implemented by ARM and x86. Which makes the current round pretty slow: #55107.
I don't know why round ties away from zero was chosen but it is pretty clear it is the wrong default.
If round was to be changed to ties to even, then the four rounding modes (round, ceil, floor and trunc) would match the required IEEE rounding modes and the rounding implemented by x86 and ARM (and probably most other ISA's, though RISC-V supports round ties away from zero).

[ajtribick]

From the perspective of maintaining a crate that implements a custom floating point type that tries to provide a similar API to the built-in f32/f64, I'd be somewhat against changing round from its documented behavior at this point (although I'd agree it isn't ideal as a choice for the default round function). It might also be worth getting some opinion from the num folks on this as they have also implemented round on their rational number types as rounding ties away from zero, similarly the documentation of round on the Float/FloatCore in num_traits.

My suspicion for why away-from-zero was chosen is that it matches how round is specified to operate in C (and similarly std::round in C++), e.g. N1570 section 7.12.9.6:

The round functions round their argument to the nearest integer value in floating-point format, rounding halfway cases away from zero, regardless of the current rounding direction.

I definitely think having a function with the round ties to even mode should be available though. My preference would be round_ties_even over round_even (because to me the latter sounds more like rounding to an even number), but it's not a particularly strong preference there.

[tgross35]

Could this do something like use roundeven when available but fallback to rint when it isn't?

[tjallingt]

I hope this is appropriate/helpful, I would like this feature stabilized so I will attempt a stabilization report.
I can also make a stabilization PR but it seems FCP should happen before that.

Request for Stabilization

I think the round_ties_even methods should be stabilized in version 1.77.0 (beta on 2 February, stable on 21 March).

Implementation history

These methods have been added in #95317 (merged 7 March, 2023) which corresponds to the 1.70 timeframe (branched on 14 April, 2023).

API Summary

The round_ties_even feature will be stabilized wich adds the following methods to std:

impl f32 {
    fn round_ties_even(self) -> f32;
}

impl f64 {
    fn round_ties_even(self) -> f64;
}

Experience reports

These methods are used in several projects:

• https://github.com/gopher64/gopher64/blob/981a8e8f050a78334b6e48a633cb3df7a13228b6/src/device/fpu_instructions.rs#L115
• https://github.com/eliasyaoyc/risingwave/blob/5cf94c934698a906711a1f421ef5a785c5e1b377/src/expr/src/vector_op/round.rs#L62
• https://github.com/zkonduit/ezkl/blob/9e68cb80c6e371e862968dc5e8824ac0c39a7e66/src/tensor/ops.rs#L2822

There are also references to this feature/tracking issue on manual implementations of round_ties_even which are waiting for this to be stabilized:

• https://github.com/wasmfx/wasmfxtime/blob/1d9e21aca2dd1169f92a96c123492f0cfd25b8fd/crates/runtime/src/libcalls.rs#L676
• https://github.com/robertknight/rten/blob/2d70ee89cfc385310213c43156c0f8a32f7986d9/src/ops/unary_elementwise.rs#L499
• https://github.com/imeka/ndarray-ndimage/blob/8b14b4d6ecfbc96a8a052f802e342a7049c68d8f/src/lib.rs#L98

Documentation

Both methods have been documented in the std rustdoc

• https://doc.rust-lang.org/std/primitive.f32.html#method.round_ties_even
• https://doc.rust-lang.org/std/primitive.f64.html#method.round_ties_even

Unresolved questions

The following questions are still unresolved:

1. Naming: round_ties_even, round_even, round_to_even, round_banker... many ways to paint this bikeshed
2. Should the behavior of the round function be changed to this?
3. Is it okay to use rint in the implementaton? (see Add round_ties_even to f32 and f64 #95317 (comment))

I will try to answer these questions

1. Naming

No further comments have been made about the naming of these method. round_ties_even seems to be a clear, descriptive name for this functionality. This name also places it close to round in the docs to ensure it will be discoverable.

2. Changing round

While the default behaviour of round is not ideal it seems to be consistent with C and C++. Changing the behaviour of round would likely be a difficult and lengthy process and would involve adding round_ties_zero methods (I believe). This could be done as a followup to stabilizing round_ties_even if desired but, in my opinion, should not block the stabilization of this feature given that this rounding mode is currently not available in Rusts standard library.

3. Use rint

Not only does Rust assume the default rounding mode, so do the LLVM floating-point intrinsics that back it.

source

As you said though, Rust already assumes the default rounding mode, so it doesn't matter too much. I think roundeven is the "more correct" choice to use but it's not well supported so it's OK to just use rint for now. Ideally we should support both in libm.

source

From these comments it appears that using rint poses no immediate problems. Rust already assumes the default rounding mode is used. It seems safe to extend that assumption to round_ties_even.

There does seem to be agreement that roundeven should be preferred once it is well supported.
I don't have enough knowledge to say for sure but; it seems likely that chaning from using rint to roundeven should be backwards compatible and therefore should not block the stabilization of this feature.

[tjallingt]

I'm not sure the previous post will be seen by anyone without a ping/mention.
I hope it is okay to mention you @m-ou-se I hope I'm following the right process 😅