float types: document NaN bit pattern guarantees

[RalfJung]

Part of #128288: document the guarantees we make for NaN bit patterns.

Cc @tgross35

[rustbot]

r? @thomcc

rustbot has assigned @thomcc.
They will have a look at your PR within the next two weeks and either review your PR or reassign to another reviewer.

Use r? to explicitly pick a reviewer

[tgross35]

Cc @beetrees (more of a float expert than me)

[tgross35]

"Use self >= 0.0 ... with -0.0 being considered positive" is this accurate? It seems either the first part should be self > 0.0 or the second part should be "being considered nonnegative".

[RalfJung]

This function tests whether something is "positive". It considers +0.0 to be positive but -0.0 to not be positive. If you replace the function by self >= 0.0 to test for positivity, then -0.0 would also be considered positive.

I guess the difference is whether you consider "positive" to mean "strictly positive" or not, but given that 0.0.is_sign_positive() is true, I think the terminology here is already aligned towards non-strict positivity.

[beetrees]

Would it be better to suggest self.signum() == 1.0 as the fully portable alternative? Unlike self >= 0.0, self.signum() == 1.0 has the same behaviour as is_sign_positive() with regards to +0.0 and -0.0.

[tgross35]

Maybe this should mention the exponent part too?

[RalfJung]

What should it say there? The point of this section is to document the degrees of freedom of a NaN value, and the exponent is fixed.

[Pr0methean]

Right, but the "consists of" list isn't complete if it doesn't specify how the NaN is tagged as a NaN, which happens in the exponent bits (combined with at least one nonzero mantissa bit). Otherwise it's like describing Rust enums without mentioning the discriminator.

[RalfJung]

A Some value "consists of" the T that it carries in its field. Similarly, a NaN consists of the ingredients listed here. The discriminator is what decides whether an "Option" value is a "Some" value, and whether a float value is a NaN value, but it is not part of the Some/Option value.

[beetrees]

Would it be worth also updating the docs for copysign to say something about what happens when the sign argument is a NaN (similar to the addition to is_sign_{positive,negative} docs)? Currently the the copysign docs only discuss what happens when self is a NaN. The link in the copysign docs could also be updated to point to the new NaN bit patterns section.

[RalfJung]

Fair points, I think I took care of all of them. :)

[thomcc]

Looks fine to me. This is part of an approved RFC and is doc-only so I don't think it needs any FCP or anything.

@bors r+ rollup

[bors]

📌 Commit 0c7d6c4 has been approved by thomcc

It is now in the queue for this repository.

[beetrees]

I feel like this question could be asked of most of the generic floating-point docs currently attached to the f32 primitive type: it seems to have become the de-facto place for documentation that applies to all floating-point numbers, with all the other floating-point types pointing to it. This makes less sense now that f16 and f128 are being added, as f32 is no longer the smallest floating-point type. Unfortunately there isn't any float module to attach the documentation to; I guess the std::num module could hold it (in the same way that std::fmt has the documentation for format strings that are used by several macros), with the floating-point primitive types all linking to that module. If keeping the generic floating-point documentation attached to one of the primitive types is desired (or the least-bad option), I think it would make most sense to move it to f64: as the fallback floating point type used for literals where no type is specified, it's the most "default" floating-point type Rust has so feels like the best primitive type to have the documentation attached to.

(In summary, solving this can be left to a future PR.)

[beetrees]

Minor nit: would it be worth explicitly mentioning what self.copysign(some_nan_value) does? Copying the NaN's sign bit on to the (probably not a NaN) self may be suprising behaviour for the user, especially since almost all other floating-point operations return a NaN if any of their inputs are NaN.