-
Notifications
You must be signed in to change notification settings - Fork 13.3k
f32::MAX_EXP and f64::MAX_EXP are documented incorrectly, and other associated constant woes #88734
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Comments
I really love your points. Here's one point that one should consider: People coming from other languages and are used to the terms will search for them. If they don't find them, they get frustrated. So at least the doc should have an alias or state somewhere that this is the alternative to XXX. |
The C standard library follows the convention that floating-point numbers x × 2exp have 0.5 ≤ x < 1, while the IEEE 754 standard text uses the convention 1 ≤ x < 2. This convention in C is not just used for |
@tspiteri Thanks for the context, that does explain why those values are the way they are in C. That said, as far as I know Rust doesn't explicitly adopt that convention anywhere, and I don't believe that it should. Rust specifically chose IEEE 754 as the definition of its floating point type, so I believe we're best served to use their conventions and terminology where possible. |
@orlp would you consider opening an ACP with what you proposed here? I think the exact changes could probably be negotiated a bit, but the expectation vs. reality of these constants is probably something that we should address, if we even find them useful enough to keep around. (If you do this, mind suggesting the addition of Two others issues cover this problem, yours just seems to have the best way forward: |
fix MAX_EXP and MIN_EXP docs As pointed out in rust-lang#88734, the docs for these constants are wrong. r? `@tgross35`
fix MAX_EXP and MIN_EXP docs As pointed out in rust-lang#88734, the docs for these constants are wrong. r? ``@tgross35``
Rollup merge of rust-lang#140150 - RalfJung:MAX_EXP, r=tgross35 fix MAX_EXP and MIN_EXP docs As pointed out in rust-lang#88734, the docs for these constants are wrong. r? ``@tgross35``
fix MAX_EXP and MIN_EXP docs As pointed out in rust-lang/rust#88734, the docs for these constants are wrong. r? ``@tgross35``
f32::MAX_EXP
andf64::MAX_EXP
are documented asThis is straight up not true. They are respectively defined as
128
and1024
, which is actually one above the maximum possible exponent off32
andf64
. The doc comment needs to be changed.In general I feel the set of associated constants for the floating point types are questionable, and should be a candidate for deprecation and replacement by a better set of constants. It is painfully obvious that the constants were copied from C's
<float.h>
, with little regard of whether these constants are useful or well-named.I have no qualms with
MIN
,MAX
,NAN
,INFINITY
, andNEG_INFINITY
at all. They are sane and useful. However, the following set of constants are carbon copied from<float.h>
:Going over them one by one (
f64
is entirely analogous):f32::RADIX
is just plain useless. It's always 2, Rust has no support for non-binary floating point.f32::MIN_POSITIVE
is badly named, because it's actually the smallest positive normal number. This is a useful constant, but the name is unacceptable in my opinion.f32::EPSILON
is somewhat badly named (MACHINE_EPSILON
would be better), and slightly deceptive. However this is not necessarily the fault of the constant, but due to people misunderstanding what machine epsilon means. Should my RFC fornext_up
/next_down
get merged, this would make this constant unnecessary. Especially if we make aulp
method in the future.f32::DIGITS
is "the approximate number of significant digits in base 10". I don't know when you'd ever need this constant, or what 'approximate' here means at all. The constant is also deceptive, because one might interpret this as an upper bound on the number of digits needed to represent af32
.f32::MANTISSA_DIGITS
includes the implied 1. Thus it is off by one from the constant you almost always want when explicitly working with a mantissa in code: the number of bits that the mantissa is wide.f32::MIN_EXP
... I think the doc comment speaks for itself: "One greater than the minimum possible normal power of 2 exponent.". Not only is it off by one, it also ignores denormal floats.f32::MAX_EXP
, see start of this issue.f32::MIN_10_EXP
, also ignores denormal floats.f32::MAX_10_EXP
, sanely defined but also fairly useless since you can computef32::MAX.log10().floor()
ifyou really wanted to know this.
I honestly believe the best way forward is to deprecate all of the above constants and replace them with a couple fundamental, sane and conservative constants. For example for
f32
:The text was updated successfully, but these errors were encountered: