///

/// # NaN bit patterns

///

/// This section defines the possible NaN bit patterns returned by non-"bitwise" floating point

/// operations. The bitwise operations are unary `-`, `abs`, `copysign`; those are guaranteed to

/// exactly preserve the bit pattern of their input except for possibly changing the sign bit.

/// This section defines the possible NaN bit patterns returned by floating point operations.

///

/// A floating-point NaN value consists of:

/// - a sign bit

/// - a quiet/signaling bit

/// The bit pattern of a floating point NaN value is defined by:

/// - a sign bit.

/// - a quiet/signaling bit. Rust assumes that the quiet/signaling bit being set to `1` indicates a

/// quiet NaN (QNaN), and a value of `0` indicates a signaling NaN (SNaN). In the following we

/// will hence just call it the "quiet bit".

/// - a payload, which makes up the rest of the significand (i.e., the mantissa) except for the

/// quiet/signaling bit.

/// quiet bit.

///

/// Rust assumes that the quiet/signaling bit being set to `1` indicates a quiet NaN (QNaN), and a

/// value of `0` indicates a signaling NaN (SNaN). In the following we will hence just call it the

/// "quiet bit".

/// The rules for NaN values differ between *arithmetic* and *non-arithmetic* (or "bitwise")

/// operations. The non-arithmetic operations are unary `-`, `abs`, `copysign`, `signum`,

/// `{to,from}_bits`, `{to,from}_{be,le,ne}_bytes` and `is_sign_{positive,negative}`. These

/// operations are guaranteed to exactly preserve the bit pattern of their input except for possibly

/// changing the sign bit.

///

/// The following rules apply when a NaN value is returned: the result has a non-deterministic sign.

/// The quiet bit and payload are non-deterministically chosen from the following set of options:

/// The following rules apply when a NaN value is returned from an arithmetic operation: the result

/// has a non-deterministic sign. The quiet bit and payload are non-deterministically chosen from

/// the following set of options:

///

/// - **Preferred NaN**: The quiet bit is set and the payload is all-zero.

/// - **Quieting NaN propagation**: The quiet bit is set and the payload is copied from any input

/// (e.g. `min`, `minimum`, `max`, `maximum`); other aspects of their semantics and which IEEE 754

/// operation they correspond to are documented with the respective functions.

///

/// When a floating-point operation is executed in `const` context, the same rules apply: no

/// guarantee is made about which of the NaN bit patterns described above will be returned. The

/// result does not have to match what happens when executing the same code at runtime, and the

/// result can vary depending on factors such as compiler version and flags.

/// When an arithmetic floating point operation is executed in `const` context, the same rules

/// apply: no guarantee is made about which of the NaN bit patterns described above will be

/// returned. The result does not have to match what happens when executing the same code at

/// runtime, and the result can vary depending on factors such as compiler version and flags.

///

/// ### Target-specific "extra" NaN values

// FIXME: Is there a better place to put this?