Tracking issue for float_extras stabilization

[aturon]

There are a number of floating point methods that are reexported from cmath, without a strong naming convention on the Rust side, or a clear rationale for which methods are included and which are not.

Ideally, someone who works with floating point, and these methods in particular, could offer advice/an RFC laying out a good vision for these methods.

[pyfisch]

For a CBOR serializer crate I used the f32::ldexp method, I hope to push this discussion forward so my crate will eventually work on stable in the future 😁

The unstable methods of f64 are:

• fn integer_decode(self) -> (u64, i16, i8)
• fn ldexp(x: f64, exp: isize) -> f64
• fn frexp(self) -> (f64, isize)
• fn next_after(self, other: f64) -> f64

The unstable methods of f32 are:

• fn integer_decode(self) -> (u64, i16, i8)
• fn to_degrees(self) -> f32
• fn to_radians(self) -> f32
• fn ldexp(x: f32, exp: isize) -> f32
• fn frexp(self) -> (f32, isize)
• fn next_after(self, other: f32) -> f32

I wonder why to_degrees() and to_radians() are stable for f64 but not for f32 since both implement the same trigonometric functions so they are equally usefull on both types.

The ldexp function should use i32 instead of isize since it does not deal with memory locations. In C ldexp is defined as double ldexp (double x, int exp); so it also uses only four bytes. Since it carries the exponent the value will always be much smaller than i32::MAX. #22098 is a discussion about if ldexp should become a method or stay a function. Since all other operations for floats take self as the first argument I would change ldexp to a method.

frexp is the counterpart of ldexp and should use the same types.

I don't know what should happen with integer_decode. C does not have a corresponding function and I also do not know what the use case for this function is. Can somebody please give me a hint? It looks like a port of an integer-decode-float function from Lisp.

next_after is a rust port of the nextafter C function. I am unsure if it should be stabilized now.

[hanna-kruppe]

ldexp and frexp are C-isms. I suspect these functions are the way they are not because it's the best design but because the C standard doesn't guarantee anything about the implementation of float and double. Therefore they did the next best thing, providing a supposedly purely arithmetic operation that matches the implementation details IEEE-like binary floating point extremely well. Take my opinion with a grain of salt, I never had to use those functions in Rust nor in C.But most people that I've heard talk about those functions, they pitch it as a way to manipulate the mantissa and the exponent directly. If that is indeed the primary use case, then I believe it is better served with something closer to integer_decode.

@pyfisch Could you elaborate what you're using ldexp for?

[pyfisch]

@rkruppe: I use them to decode half floats to f32: https://github.com/pyfisch/cbor/blob/master/src/de.rs#L173

[hanna-kruppe]

Oh, so you're also using it in lieu of a proper API for disassembling and reassembling IEEE 754 floats. As I said before, I think integer_decode (after a substantial overhaul) and a hypothetical inverse integer_encode is superior for that use case. I am not wedded to the names and the tuple return type (a proper struct may be better), but in any case it should be explicit about what it does.

[haudan]

Personally, I haven't written a single program, in which I wouldn't have needed the radian / degree conversion methods. Seeing the f32 versions being stabilized would be a bliss.

[aturon]

@Lisoph D'oh! That seems to just be an oversight; the ones on f64 are stable. Are you interested in writing a stabilization PR? If not, I can do it.

[haudan]

@aturon I submitted an issue, was that the right thing to do? I'm new to Rust's RFC culture so I'm wondering.

[aturon]

@Lisoph That's fine -- if you'd like, you can also submit a PR to stabilize it. If not, I or someone else from the libs team will take care of it soon!

[brson]

+1 to any resolution to these. Don't care much at this point about the naming question or the exact functionality. Let's just decide.

[hanna-kruppe]

If the choice is between stabilizing or deprecating now, I would plead for deprecation. The current interface is sub-par, designing a good one is hard, this functionality is relatively niche and really doesn't need to be in std — it can easily be implemented with transmute and equivalent operations are already implemented in the ieee754 crate.

[alexcrichton]

🔔 This issue is now entering its final comment period 🔔

The libs team was unfortunately a little late on stabilizations this cycle, but we're thinking of probably doing a backport of stabilizations partway through the beta cycle. We were somewhat ambivalent if I remember correctly on whether to stabilize or deprecate these functions. The functionality is likely needed by someone, but the names are unfortunately sub-par wrt the rest of the module.

[pyfisch]

I think they should be deprecated since they are not used often enough. Maybe some will be reintroduced in the future with better names.

[alexcrichton]

The libs team discussed this issue during triage yesterday and the decision was to deprecate. We realize that the FCP for this issue was pretty short, however, so please comment with any objections you might have! We're very willing to backport an un-deprecate for the few APIs we have this cycle.

[jethrogb]

I was integer_decode to compute an integer's next-highest power of 2. I have now benchmarked it and the shifting version is significantly faster.

[lilith]

next_after is extremely useful for unit testing with floats...