nordic-dev.net/rust
nordic-dev.net/rust
2
0
Fork 0
mirror of https://github.com/rust-lang/rust.git synced 2024-11-22 23:04:33 +00:00
Code Issues Packages Projects Releases Wiki Activity

f32 docs: define 'arithmetic' operations

Browse Source
This commit is contained in:
Ralf Jung 2024-08-29 08:55:37 +02:00
parent 6cf068db56
commit eb8e78f624
1 changed files with 19 additions and 16 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

35
library/core/src/primitive_docs.rs
View File

@ -1219,22 +1219,25 @@ mod prim_f16 {}
///
/// # 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
@ -1273,10 +1276,10 @@ mod prim_f16 {}
/// (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?