Tracking Issue for `float_next_up_down`

[yaahc]

Feature gate: #![feature(float_next_up_down)]

This is a tracking issue for two argumentless methods to f32/f64, next_up and next_down. These functions are specified in the IEEE 754 standard, and provide the capability to enumerate floating point values in order.

Public API

impl f32 {
    pub const fn next_up(self) -> Self;
    pub const fn next_down(self) -> Self;
}

impl f64 {
    pub const fn next_up(self) -> Self;
    pub const fn next_down(self) -> Self;
}

Steps / History

• [x] Implementation: https://github.com/rust-lang/rust/pull/100578
• [ ] Final comment period (FCP)
• [ ] Stabilization PR

Unresolved Questions

• [ ] Dealing with misbehaving platforms https://github.com/rust-lang/rust/issues/91399#issuecomment-1045989643

[orlp]

During merging of my implementation a new unresolved question popped up due to failed tests:

What should we do when the platform flushes denormals to zero and/or does not preserve NaN payloads?

I thought that my implementation would be immune to these issues since I call to_bits() at the start, from_bits() at the end and perform all logic with integers. Apparently not so.

For example, it appears that Rust on some x87 platforms flushes denormals and destroys NaN payloads on function boundaries. x.to_bits() == x.to_bits() can succeed, but identity(x).to_bits() == x.to_bits() can fail. Since next_up is a function boundary itself, it can not work as advertised for some inputs, even if the user does not perform any floating point operations with the resulting value. This also can form infinite loops when repeatedly calling next_up until an upper bound is reached, if the range crosses the denormals.

I don't know what the right way to handle this is. Maybe a careful look needs to be taken at when Rust stores data in floating point vs integer registers when to_bits and from_bits is involved on platforms where this has implications for the data. Or maybe the interface for next_up and next_down needs to be changed so that x.next_up() becomes f32::next_up(x.to_bits()).from_bits(), and loops can store their state in a u32 rather than f32.

Alternatively we add a disclaimer to the documentation for next_up/next_down that it may fail to uphold its contract on platforms that flush denormals and/or do not respect NaN payloads, or disable the function entirely. Neither of these makes me particularly happy.

[thomcc]

CC @workingjubilee who has recently been thinking some about platforms like x87 and such.

[cmpute]

What are the common usages for these two functions? I met a use case, that is to parse a float into a rational number with simpler form, which requires me to get the rounding interval. This can be done using these two functions.

This also can form infinite loops when repeatedly calling next_up until an upper bound is reached, if the range crosses the denormals

Is there anybody actually enumerating floats like this? In my case it's okay to document the behavior that the function will skip subnormals in certain platforms.

(Note: IEEE 754 doesn't have any explicit rule about executing nextUp and nextDown on subnormals)

[sharifhsn]

I can comment on my use case for this function. I'm doing research on high-performance floating-point operations that requires me to iterate through floating-point numbers in this way to determine intervals for an input. My current workaround is manually converting using to_bits and from_bits, but these have the disadvantage of being awkward and not necessarily complying with IEEE-754 recommendations.

In my work we already treat denormals as a special case, so it's fine if next_up and next_down cause unexpected behavior when crossing the denormal boundary; I avoid doing that already because it's so error-prone.

Thanks for the work on these new functions, they are a welcome ergonomic improvement for me! I hope that they are stabilized soon.

[workingjubilee]

(Note: IEEE 754 doesn't have any explicit rule about executing nextUp and nextDown on subnormals)

I am not sure what you mean by this, as implementations that do not implement subnormal numbers are nonconformant with IEEE754. I intend to address these concerns and more in a future project soon.

[cmpute]

I mean AFAIK IEEE 754 doesn't specify how subnormals are handled with nextUp and nextDown.

[peckpeck]

I would expect assert!(x.next_up() > x); ie assert!(-1_f64.next_up() > -1_f64);

But this is not the case, either the documentation is wrong or the implementation.

Either way, shouldn't there be a test?

About usage, this can be used to estimate rounding on operations.

[orlp]

@peckpeck Which platform are you testing on? I can not reproduce your problem.

[sharifhsn]

@peckpeck I believe you're running into the ambiguity described here. [Here](https://play.rust-lang.org/?version=nightly&mode=debug&edition=2021&code=%23!%5Bfeature(float_next_up_down)%5D%0A%0Afn%20main()%20%7B%0A%20%20%20%20assert!((-1.0f64).next_up()%20%3E%20-1.0f64)%3B%0A%7D) is a playground demonstration. The implementation is correct.

[orlp]

@peckpeck Ah, yes, -1_f64.next_up(), sadly, is parsed by Rust as -(1_f64.next_up()). This isn't anything related to next_up however, for example -1_f64.abs() also results in -1. You can avoid this pitfall by writing f64::next_up(-1.0).

[peckpeck]

Ah indeed, by bad. Sorry for the noise.

[schuelermine]

Why return NAN from NAN? Why not panic?

[sharifhsn]

Propagating NaN is a basic requirement of IEEE-754 floating point, and you'll find the same feature in basically every floating point library or function that exists. It is the caller's responsibility to handle a NaN result, and they can panic if they wish:

let x = 1f64;
let y = x.next_up();
if y.is_nan() {
     panic!("not a number");
}

or perhaps in a more Rust way,

let x = 1f64;
match x.next_up() {
    y if y.is_nan() => panic!("not a number"),
    y => {
        // do something with y
    }
}

[schuelermine]

OK

[zakarumych]

One possible use-case is to create smallest non-empty range if given range is x..=x. By replacing it with x.next_down()..=x.next_up()