nordic-dev.net/rust
nordic-dev.net/rust
2
0
Fork 0
mirror of https://github.com/rust-lang/rust.git synced 2025-06-04 19:29:07 +00:00
Code Issues Packages Projects Releases Wiki Activity

Rollup merge of #95483 - golddranks:improve_float_docs, r=joshtriplett

Browse Source 
Improve floating point documentation

This is my attempt to improve/solve https://github.com/rust-lang/rust/issues/95468 and https://github.com/rust-lang/rust/issues/73328 .

Added/refined explanations:
- Refine the "NaN as a special value" top level explanation of f32
- Refine `const NAN` docstring: add an explanation about there being multitude of NaN bitpatterns and disclaimer about the portability/stability guarantees.
- Refine `fn is_sign_positive` and `fn is_sign_negative` docstrings: add disclaimer about the sign bit of NaNs.
- Refine `fn min` and `fn max` docstrings: explain the semantics and their relationship to the standard and libm better.
- Refine `fn trunc` docstrings: explain the semantics slightly more.
- Refine `fn powi` docstrings: add disclaimer that the rounding behaviour might be different from `powf`.
- Refine `fn copysign` docstrings: add disclaimer about payloads of NaNs.
- Refine `minimum` and `maximum`: add disclaimer that "propagating NaN" doesn't mean that propagating the NaN bit patterns is guaranteed.
- Refine `max` and `min` docstrings: add "ignoring NaN" to bring the one-row explanation to parity with `minimum` and `maximum`.

Cosmetic changes:
- Reword `NaN` and `NAN` as plain "NaN", unless they refer to the specific `const NAN`.
- Reword "a number" to `self` in function docstrings to clarify.
- Remove "Returns NAN if the number is NAN" from `abs`, as this is told to be the default behavior in the top explanation.
This commit is contained in:
Matthias Krüger 2022-05-09 18:45:35 +02:00 committed by GitHub
commit 28d800ce1c
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
6 changed files with 182 additions and 68 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

79
library/core/src/num/f32.rs
View File

@ -393,6 +393,15 @@ impl f32 {
pub const MAX_10_EXP: i32 = 38;
/// Not a Number (NaN).
///
/// Note that IEEE-745 doesn't define just a single NaN value;
/// a plethora of bit patterns are considered to be NaN.
/// Furthermore, the standard makes a difference
/// between a "signaling" and a "quiet" NaN,
/// and allows inspecting its "payload" (the unspecified bits in the bit pattern).
/// This constant isn't guaranteed to equal to any specific NaN bitpattern,
/// and the stability of its representation over Rust versions
/// and target platforms isn't guaranteed.
#[stable(feature = "assoc_int_consts", since = "1.43.0")]
pub const NAN: f32 = 0.0_f32 / 0.0_f32;
/// Infinity (∞).
@ -402,7 +411,7 @@ impl f32 {
#[stable(feature = "assoc_int_consts", since = "1.43.0")]
pub const NEG_INFINITY: f32 = -1.0_f32 / 0.0_f32;
/// Returns `true` if this value is `NaN`.
/// Returns `true` if this value is NaN.
///
/// ```
/// let nan = f32::NAN;
@ -455,7 +464,7 @@ impl f32 {
(self == f32::INFINITY) | (self == f32::NEG_INFINITY)
}
/// Returns `true` if this number is neither infinite nor `NaN`.
/// Returns `true` if this number is neither infinite nor NaN.
///
/// ```
/// let f = 7.0f32;
@ -506,7 +515,7 @@ impl f32 {
}
/// Returns `true` if the number is neither zero, infinite,
/// [subnormal], or `NaN`.
/// [subnormal], or NaN.
///
/// ```
/// let min = f32::MIN_POSITIVE; // 1.17549435e-38f32
@ -622,8 +631,12 @@ impl f32 {
}
}
/// Returns `true` if `self` has a positive sign, including `+0.0`, `NaN`s with
/// positive sign bit and positive infinity.
/// Returns `true` if `self` has a positive sign, including `+0.0`, NaNs with
/// positive sign bit and positive infinity. Note that IEEE-745 doesn't assign any
/// meaning to the sign bit in case of a NaN, and as Rust doesn't guarantee that
/// the bit pattern of NaNs are conserved over arithmetic operations, the result of
/// `is_sign_positive` on a NaN might produce an unexpected result in some cases.
/// See [explanation of NaN as a special value](f32) for more info.
///
/// ```
/// let f = 7.0_f32;
@ -640,8 +653,12 @@ impl f32 {
!self.is_sign_negative()
}
/// Returns `true` if `self` has a negative sign, including `-0.0`, `NaN`s with
/// negative sign bit and negative infinity.
/// Returns `true` if `self` has a negative sign, including `-0.0`, NaNs with
/// negative sign bit and negative infinity. Note that IEEE-745 doesn't assign any
/// meaning to the sign bit in case of a NaN, and as Rust doesn't guarantee that
/// the bit pattern of NaNs are conserved over arithmetic operations, the result of
/// `is_sign_negative` on a NaN might produce an unexpected result in some cases.
/// See [explanation of NaN as a special value](f32) for more info.
///
/// ```
/// let f = 7.0f32;
@ -713,10 +730,12 @@ impl f32 {
self * (value / 180.0f32)
}
/// Returns the maximum of the two numbers.
/// Returns the maximum of the two numbers, ignoring NaN.
///
/// Follows the IEEE-754 2008 semantics for maxNum, except for handling of signaling NaNs.
/// This matches the behavior of libm’s fmax.
/// If one of the arguments is NaN, then the other argument is returned.
/// This follows the IEEE-754 2008 semantics for maxNum, except for handling of signaling NaNs;
/// this function handles all NaNs the same way and avoids maxNum's problems with associativity.
/// This also matches the behavior of libm’s fmax.
///
/// ```
/// let x = 1.0f32;
@ -724,8 +743,6 @@ impl f32 {
///
/// assert_eq!(x.max(y), y);
/// ```
///
/// If one of the arguments is NaN, then the other argument is returned.
#[must_use = "this returns the result of the comparison, without modifying either input"]
#[stable(feature = "rust1", since = "1.0.0")]
#[inline]
@ -733,10 +750,12 @@ impl f32 {
intrinsics::maxnumf32(self, other)
}
/// Returns the minimum of the two numbers.
/// Returns the minimum of the two numbers, ignoring NaN.
///
/// Follows the IEEE-754 2008 semantics for minNum, except for handling of signaling NaNs.
/// This matches the behavior of libm’s fmin.
/// If one of the arguments is NaN, then the other argument is returned.
/// This follows the IEEE-754 2008 semantics for minNum, except for handling of signaling NaNs;
/// this function handles all NaNs the same way and avoids minNum's problems with associativity.
/// This also matches the behavior of libm’s fmin.
///
/// ```
/// let x = 1.0f32;
@ -744,8 +763,6 @@ impl f32 {
///
/// assert_eq!(x.min(y), x);
/// ```
///
/// If one of the arguments is NaN, then the other argument is returned.
#[must_use = "this returns the result of the comparison, without modifying either input"]
#[stable(feature = "rust1", since = "1.0.0")]
#[inline]
@ -753,7 +770,7 @@ impl f32 {
intrinsics::minnumf32(self, other)
}
/// Returns the maximum of the two numbers, propagating NaNs.
/// Returns the maximum of the two numbers, propagating NaN.
///
/// This returns NaN when *either* argument is NaN, as opposed to
/// [`f32::max`] which only returns NaN when *both* arguments are NaN.
@ -770,6 +787,9 @@ impl f32 {
/// If one of the arguments is NaN, then NaN is returned. Otherwise this returns the greater
/// of the two numbers. For this operation, -0.0 is considered to be less than +0.0.
/// Note that this follows the semantics specified in IEEE 754-2019.
///
/// Also note that "propagation" of NaNs here doesn't necessarily mean that the bitpattern of a NaN
/// operand is conserved; see [explanation of NaN as a special value](f32) for more info.
#[must_use = "this returns the result of the comparison, without modifying either input"]
#[unstable(feature = "float_minimum_maximum", issue = "91079")]
#[inline]
@ -785,7 +805,7 @@ impl f32 {
}
}
/// Returns the minimum of the two numbers, propagating NaNs.
/// Returns the minimum of the two numbers, propagating NaN.
///
/// This returns NaN when *either* argument is NaN, as opposed to
/// [`f32::min`] which only returns NaN when *both* arguments are NaN.
@ -802,6 +822,9 @@ impl f32 {
/// If one of the arguments is NaN, then NaN is returned. Otherwise this returns the lesser
/// of the two numbers. For this operation, -0.0 is considered to be less than +0.0.
/// Note that this follows the semantics specified in IEEE 754-2019.
///
/// Also note that "propagation" of NaNs here doesn't necessarily mean that the bitpattern of a NaN
/// operand is conserved; see [explanation of NaN as a special value](f32) for more info.
#[must_use = "this returns the result of the comparison, without modifying either input"]
#[unstable(feature = "float_minimum_maximum", issue = "91079")]
#[inline]
@ -1009,6 +1032,9 @@ impl f32 {
/// Return the memory representation of this floating point number as a byte array in
/// big-endian (network) byte order.
///
/// See [`from_bits`](Self::from_bits) for some discussion of the
/// portability of this operation (there are almost no issues).
///
/// # Examples
///
/// ```
@ -1027,6 +1053,9 @@ impl f32 {
/// Return the memory representation of this floating point number as a byte array in
/// little-endian byte order.
///
/// See [`from_bits`](Self::from_bits) for some discussion of the
/// portability of this operation (there are almost no issues).
///
/// # Examples
///
/// ```
@ -1051,6 +1080,9 @@ impl f32 {
/// [`to_be_bytes`]: f32::to_be_bytes
/// [`to_le_bytes`]: f32::to_le_bytes
///
/// See [`from_bits`](Self::from_bits) for some discussion of the
/// portability of this operation (there are almost no issues).
///
/// # Examples
///
/// ```
@ -1075,6 +1107,9 @@ impl f32 {
/// Create a floating point value from its representation as a byte array in big endian.
///
/// See [`from_bits`](Self::from_bits) for some discussion of the
/// portability of this operation (there are almost no issues).
///
/// # Examples
///
/// ```
@ -1091,6 +1126,9 @@ impl f32 {
/// Create a floating point value from its representation as a byte array in little endian.
///
/// See [`from_bits`](Self::from_bits) for some discussion of the
/// portability of this operation (there are almost no issues).
///
/// # Examples
///
/// ```
@ -1114,6 +1152,9 @@ impl f32 {
/// [`from_be_bytes`]: f32::from_be_bytes
/// [`from_le_bytes`]: f32::from_le_bytes
///
/// See [`from_bits`](Self::from_bits) for some discussion of the
/// portability of this operation (there are almost no issues).
///
/// # Examples
///
/// ```

79
library/core/src/num/f64.rs
View File

@ -392,6 +392,15 @@ impl f64 {
pub const MAX_10_EXP: i32 = 308;
/// Not a Number (NaN).
///
/// Note that IEEE-745 doesn't define just a single NaN value;
/// a plethora of bit patterns are considered to be NaN.
/// Furthermore, the standard makes a difference
/// between a "signaling" and a "quiet" NaN,
/// and allows inspecting its "payload" (the unspecified bits in the bit pattern).
/// This constant isn't guaranteed to equal to any specific NaN bitpattern,
/// and the stability of its representation over Rust versions
/// and target platforms isn't guaranteed.
#[stable(feature = "assoc_int_consts", since = "1.43.0")]
pub const NAN: f64 = 0.0_f64 / 0.0_f64;
/// Infinity (∞).
@ -401,7 +410,7 @@ impl f64 {
#[stable(feature = "assoc_int_consts", since = "1.43.0")]
pub const NEG_INFINITY: f64 = -1.0_f64 / 0.0_f64;
/// Returns `true` if this value is `NaN`.
/// Returns `true` if this value is NaN.
///
/// ```
/// let nan = f64::NAN;
@ -456,7 +465,7 @@ impl f64 {
(self == f64::INFINITY) | (self == f64::NEG_INFINITY)
}
/// Returns `true` if this number is neither infinite nor `NaN`.
/// Returns `true` if this number is neither infinite nor NaN.
///
/// ```
/// let f = 7.0f64;
@ -507,7 +516,7 @@ impl f64 {
}
/// Returns `true` if the number is neither zero, infinite,
/// [subnormal], or `NaN`.
/// [subnormal], or NaN.
///
/// ```
/// let min = f64::MIN_POSITIVE; // 2.2250738585072014e-308f64
@ -614,8 +623,12 @@ impl f64 {
}
}
/// Returns `true` if `self` has a positive sign, including `+0.0`, `NaN`s with
/// positive sign bit and positive infinity.
/// Returns `true` if `self` has a positive sign, including `+0.0`, NaNs with
/// positive sign bit and positive infinity. Note that IEEE-745 doesn't assign any
/// meaning to the sign bit in case of a NaN, and as Rust doesn't guarantee that
/// the bit pattern of NaNs are conserved over arithmetic operations, the result of
/// `is_sign_positive` on a NaN might produce an unexpected result in some cases.
/// See [explanation of NaN as a special value](f32) for more info.
///
/// ```
/// let f = 7.0_f64;
@ -641,8 +654,12 @@ impl f64 {
self.is_sign_positive()
}
/// Returns `true` if `self` has a negative sign, including `-0.0`, `NaN`s with
/// negative sign bit and negative infinity.
/// Returns `true` if `self` has a negative sign, including `-0.0`, NaNs with
/// negative sign bit and negative infinity. Note that IEEE-745 doesn't assign any
/// meaning to the sign bit in case of a NaN, and as Rust doesn't guarantee that
/// the bit pattern of NaNs are conserved over arithmetic operations, the result of
/// `is_sign_negative` on a NaN might produce an unexpected result in some cases.
/// See [explanation of NaN as a special value](f32) for more info.
///
/// ```
/// let f = 7.0_f64;
@ -724,10 +741,12 @@ impl f64 {
self * (value / 180.0)
}
/// Returns the maximum of the two numbers.
/// Returns the maximum of the two numbers, ignoring NaN.
///
/// Follows the IEEE-754 2008 semantics for maxNum, except for handling of signaling NaNs.
/// This matches the behavior of libm’s fmax.
/// If one of the arguments is NaN, then the other argument is returned.
/// This follows the IEEE-754 2008 semantics for maxNum, except for handling of signaling NaNs;
/// this function handles all NaNs the same way and avoids maxNum's problems with associativity.
/// This also matches the behavior of libm’s fmax.
///
/// ```
/// let x = 1.0_f64;
@ -735,8 +754,6 @@ impl f64 {
///
/// assert_eq!(x.max(y), y);
/// ```
///
/// If one of the arguments is NaN, then the other argument is returned.
#[must_use = "this returns the result of the comparison, without modifying either input"]
#[stable(feature = "rust1", since = "1.0.0")]
#[inline]
@ -744,10 +761,12 @@ impl f64 {
intrinsics::maxnumf64(self, other)
}
/// Returns the minimum of the two numbers.
/// Returns the minimum of the two numbers, ignoring NaN.
///
/// Follows the IEEE-754 2008 semantics for minNum, except for handling of signaling NaNs.
/// This matches the behavior of libm’s fmin.
/// If one of the arguments is NaN, then the other argument is returned.
/// This follows the IEEE-754 2008 semantics for minNum, except for handling of signaling NaNs;
/// this function handles all NaNs the same way and avoids minNum's problems with associativity.
/// This also matches the behavior of libm’s fmin.
///
/// ```
/// let x = 1.0_f64;
@ -755,8 +774,6 @@ impl f64 {
///
/// assert_eq!(x.min(y), x);
/// ```
///
/// If one of the arguments is NaN, then the other argument is returned.
#[must_use = "this returns the result of the comparison, without modifying either input"]
#[stable(feature = "rust1", since = "1.0.0")]
#[inline]
@ -764,7 +781,7 @@ impl f64 {
intrinsics::minnumf64(self, other)
}
/// Returns the maximum of the two numbers, propagating NaNs.
/// Returns the maximum of the two numbers, propagating NaN.
///
/// This returns NaN when *either* argument is NaN, as opposed to
/// [`f64::max`] which only returns NaN when *both* arguments are NaN.
@ -781,6 +798,9 @@ impl f64 {
/// If one of the arguments is NaN, then NaN is returned. Otherwise this returns the greater
/// of the two numbers. For this operation, -0.0 is considered to be less than +0.0.
/// Note that this follows the semantics specified in IEEE 754-2019.
///
/// Also note that "propagation" of NaNs here doesn't necessarily mean that the bitpattern of a NaN
/// operand is conserved; see [explanation of NaN as a special value](f32) for more info.
#[must_use = "this returns the result of the comparison, without modifying either input"]
#[unstable(feature = "float_minimum_maximum", issue = "91079")]
#[inline]
@ -796,7 +816,7 @@ impl f64 {
}
}
/// Returns the minimum of the two numbers, propagating NaNs.
/// Returns the minimum of the two numbers, propagating NaN.
///
/// This returns NaN when *either* argument is NaN, as opposed to
/// [`f64::min`] which only returns NaN when *both* arguments are NaN.
@ -813,6 +833,9 @@ impl f64 {
/// If one of the arguments is NaN, then NaN is returned. Otherwise this returns the lesser
/// of the two numbers. For this operation, -0.0 is considered to be less than +0.0.
/// Note that this follows the semantics specified in IEEE 754-2019.
///
/// Also note that "propagation" of NaNs here doesn't necessarily mean that the bitpattern of a NaN
/// operand is conserved; see [explanation of NaN as a special value](f32) for more info.
#[must_use = "this returns the result of the comparison, without modifying either input"]
#[unstable(feature = "float_minimum_maximum", issue = "91079")]
#[inline]
@ -1007,6 +1030,9 @@ impl f64 {
/// Return the memory representation of this floating point number as a byte array in
/// big-endian (network) byte order.
///
/// See [`from_bits`](Self::from_bits) for some discussion of the
/// portability of this operation (there are almost no issues).
///
/// # Examples
///
/// ```
@ -1025,6 +1051,9 @@ impl f64 {
/// Return the memory representation of this floating point number as a byte array in
/// little-endian byte order.
///
/// See [`from_bits`](Self::from_bits) for some discussion of the
/// portability of this operation (there are almost no issues).
///
/// # Examples
///
/// ```
@ -1049,6 +1078,9 @@ impl f64 {
/// [`to_be_bytes`]: f64::to_be_bytes
/// [`to_le_bytes`]: f64::to_le_bytes
///
/// See [`from_bits`](Self::from_bits) for some discussion of the
/// portability of this operation (there are almost no issues).
///
/// # Examples
///
/// ```
@ -1073,6 +1105,9 @@ impl f64 {
/// Create a floating point value from its representation as a byte array in big endian.
///
/// See [`from_bits`](Self::from_bits) for some discussion of the
/// portability of this operation (there are almost no issues).
///
/// # Examples
///
/// ```
@ -1089,6 +1124,9 @@ impl f64 {
/// Create a floating point value from its representation as a byte array in little endian.
///
/// See [`from_bits`](Self::from_bits) for some discussion of the
/// portability of this operation (there are almost no issues).
///
/// # Examples
///
/// ```
@ -1112,6 +1150,9 @@ impl f64 {
/// [`from_be_bytes`]: f64::from_be_bytes
/// [`from_le_bytes`]: f64::from_le_bytes
///
/// See [`from_bits`](Self::from_bits) for some discussion of the
/// portability of this operation (there are almost no issues).
///
/// # Examples
///
/// ```

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

@ -977,10 +977,22 @@ mod prim_tuple {}
/// like `1.0 / 0.0`.
/// - [NaN (not a number)](#associatedconstant.NAN): this value results from
/// calculations like `(-1.0).sqrt()`. NaN has some potentially unexpected
/// behavior: it is unequal to any float, including itself! It is also neither
/// smaller nor greater than any float, making it impossible to sort. Lastly,
/// it is considered infectious as almost all calculations where one of the
/// operands is NaN will also result in NaN.
/// behavior:
/// - It is unequal to any float, including itself! This is the reason `f32`
/// doesn't implement the `Eq` trait.
/// - It is also neither smaller nor greater than any float, making it
/// impossible to sort by the default comparison operation, which is the
/// reason `f32` doesn't implement the `Ord` trait.
/// - It is also considered *infectious* as almost all calculations where one
/// of the operands is NaN will also result in NaN. The explanations on this
/// page only explicitly document behavior on NaN operands if this default
/// is deviated from.
/// - Lastly, there are multiple bit patterns that are considered NaN.
/// Rust does not currently guarantee that the bit patterns of NaN are
/// preserved over arithmetic operations, and they are not guaranteed to be
/// portable or even fully deterministic! This means that there may be some
/// surprising results upon inspecting the bit patterns,
/// as the same calculations might produce NaNs with different bit patterns.
///
/// For more information on floating point numbers, see [Wikipedia][wikipedia].
///

26
library/std/src/f32.rs
View File

@ -29,7 +29,7 @@ pub use core::f32::{
#[cfg(not(test))]
impl f32 {
/// Returns the largest integer less than or equal to a number.
/// Returns the largest integer less than or equal to `self`.
///
/// # Examples
///
@ -50,7 +50,7 @@ impl f32 {
unsafe { intrinsics::floorf32(self) }
}
/// Returns the smallest integer greater than or equal to a number.
/// Returns the smallest integer greater than or equal to `self`.
///
/// # Examples
///
@ -69,7 +69,7 @@ impl f32 {
unsafe { intrinsics::ceilf32(self) }
}
/// Returns the nearest integer to a number. Round half-way cases away from
/// Returns the nearest integer to `self`. Round half-way cases away from
/// `0.0`.
///
/// # Examples
@ -89,7 +89,8 @@ impl f32 {
unsafe { intrinsics::roundf32(self) }
}
/// Returns the integer part of a number.
/// Returns the integer part of `self`.
/// This means that non-integer numbers are always truncated towards zero.
///
/// # Examples
///
@ -110,7 +111,7 @@ impl f32 {
unsafe { intrinsics::truncf32(self) }
}
/// Returns the fractional part of a number.
/// Returns the fractional part of `self`.
///
/// # Examples
///
@ -131,8 +132,7 @@ impl f32 {
self - self.trunc()
}
/// Computes the absolute value of `self`. Returns `NAN` if the
/// number is `NAN`.
/// Computes the absolute value of `self`.
///
/// # Examples
///
@ -160,7 +160,7 @@ impl f32 {
///
/// - `1.0` if the number is positive, `+0.0` or `INFINITY`
/// - `-1.0` if the number is negative, `-0.0` or `NEG_INFINITY`
/// - `NAN` if the number is `NAN`
/// - NaN if the number is NaN
///
/// # Examples
///
@ -184,8 +184,10 @@ impl f32 {
/// `sign`.
///
/// Equal to `self` if the sign of `self` and `sign` are the same, otherwise
/// equal to `-self`. If `self` is a `NAN`, then a `NAN` with the sign of
/// `sign` is returned.
/// equal to `-self`. If `self` is a NaN, then a NaN with the sign bit of
/// `sign` is returned. Note, however, that conserving the sign bit on NaN
/// across arithmetical operations is not generally guaranteed.
/// See [explanation of NaN as a special value](primitive@f32) for more info.
///
/// # Examples
///
@ -298,7 +300,9 @@ impl f32 {
/// Raises a number to an integer power.
///
/// Using this function is generally faster than using `powf`
/// Using this function is generally faster than using `powf`.
/// It might have a different sequence of rounding operations than `powf`,
/// so the results are not guaranteed to agree.
///
/// # Examples
///

26
library/std/src/f64.rs
View File

@ -29,7 +29,7 @@ pub use core::f64::{
#[cfg(not(test))]
impl f64 {
/// Returns the largest integer less than or equal to a number.
/// Returns the largest integer less than or equal to `self`.
///
/// # Examples
///
@ -50,7 +50,7 @@ impl f64 {
unsafe { intrinsics::floorf64(self) }
}
/// Returns the smallest integer greater than or equal to a number.
/// Returns the smallest integer greater than or equal to `self`.
///
/// # Examples
///
@ -69,7 +69,7 @@ impl f64 {
unsafe { intrinsics::ceilf64(self) }
}
/// Returns the nearest integer to a number. Round half-way cases away from
/// Returns the nearest integer to `self`. Round half-way cases away from
/// `0.0`.
///
/// # Examples
@ -89,7 +89,8 @@ impl f64 {
unsafe { intrinsics::roundf64(self) }
}
/// Returns the integer part of a number.
/// Returns the integer part of `self`.
/// This means that non-integer numbers are always truncated towards zero.
///
/// # Examples
///
@ -110,7 +111,7 @@ impl f64 {
unsafe { intrinsics::truncf64(self) }
}
/// Returns the fractional part of a number.
/// Returns the fractional part of `self`.
///
/// # Examples
///
@ -131,8 +132,7 @@ impl f64 {
self - self.trunc()
}
/// Computes the absolute value of `self`. Returns `NAN` if the
/// number is `NAN`.
/// Computes the absolute value of `self`.
///
/// # Examples
///
@ -160,7 +160,7 @@ impl f64 {
///
/// - `1.0` if the number is positive, `+0.0` or `INFINITY`
/// - `-1.0` if the number is negative, `-0.0` or `NEG_INFINITY`
/// - `NAN` if the number is `NAN`
/// - NaN if the number is NaN
///
/// # Examples
///
@ -184,8 +184,10 @@ impl f64 {
/// `sign`.
///
/// Equal to `self` if the sign of `self` and `sign` are the same, otherwise
/// equal to `-self`. If `self` is a `NAN`, then a `NAN` with the sign of
/// `sign` is returned.
/// equal to `-self`. If `self` is a NaN, then a NaN with the sign bit of
/// `sign` is returned. Note, however, that conserving the sign bit on NaN
/// across arithmetical operations is not generally guaranteed.
/// See [explanation of NaN as a special value](primitive@f32) for more info.
///
/// # Examples
///
@ -298,7 +300,9 @@ impl f64 {
/// Raises a number to an integer power.
///
/// Using this function is generally faster than using `powf`
/// Using this function is generally faster than using `powf`.
/// It might have a different sequence of rounding operations than `powf`,
/// so the results are not guaranteed to agree.
///
/// # Examples
///

20
library/std/src/primitive_docs.rs
View File

@ -977,10 +977,22 @@ mod prim_tuple {}
/// like `1.0 / 0.0`.
/// - [NaN (not a number)](#associatedconstant.NAN): this value results from
/// calculations like `(-1.0).sqrt()`. NaN has some potentially unexpected
/// behavior: it is unequal to any float, including itself! It is also neither
/// smaller nor greater than any float, making it impossible to sort. Lastly,
/// it is considered infectious as almost all calculations where one of the
/// operands is NaN will also result in NaN.
/// behavior:
/// - It is unequal to any float, including itself! This is the reason `f32`
/// doesn't implement the `Eq` trait.
/// - It is also neither smaller nor greater than any float, making it
/// impossible to sort by the default comparison operation, which is the
/// reason `f32` doesn't implement the `Ord` trait.
/// - It is also considered *infectious* as almost all calculations where one
/// of the operands is NaN will also result in NaN. The explanations on this
/// page only explicitly document behavior on NaN operands if this default
/// is deviated from.
/// - Lastly, there are multiple bit patterns that are considered NaN.
/// Rust does not currently guarantee that the bit patterns of NaN are
/// preserved over arithmetic operations, and they are not guaranteed to be
/// portable or even fully deterministic! This means that there may be some
/// surprising results upon inspecting the bit patterns,
/// as the same calculations might produce NaNs with different bit patterns.
///
/// For more information on floating point numbers, see [Wikipedia][wikipedia].
///