f32 docs: define 'arithmetic' operations · patricklam/verify-rust-std@93a72da (original) (raw)

`@@ -1219,22 +1219,25 @@ mod prim_f16 {}

1219

`///

1220

`/// # NaN bit patterns

1221

`///

1222

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

1223

`` -

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

1224

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

1222

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

1225

1223

`///

1226

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

1227

/// - a sign bit

1228

/// - a quiet/signaling bit

1224

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

1225

/// - a sign bit.

1226

`` +

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

1227

`` +

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

1228

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

1229

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

1230

/// quiet/signaling bit.

1230

/// quiet bit.

1231

`///

1232

`` -

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

1233

`` -

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

1234

/// "quiet bit".

1232

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

1233

`` +

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

1234

`` +

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

1235

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

1236

/// changing the sign bit.

1235

1237

`///

1236

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

1237

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

1238

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

1239

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

1240

/// the following set of options:

1238

1241

`///

1239

1242

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

1240

1243

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

`@@ -1273,10 +1276,10 @@ mod prim_f16 {}

1273

1276

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

1274

1277

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

1275

1278

`///

1276

`` -

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

1277

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

1278

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

1279

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

1279

`` +

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

1280

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

1281

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

1282

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

1280

1283

`///

1281

1284

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

1282

1285

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