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 (∞).
#[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;
self.abs_private() == Self::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;
}
/// Returns `true` if the number is neither zero, infinite,
- /// [subnormal], or `NaN`.
+ /// [subnormal], or NaN.
///
/// ```
/// let min = f32::MIN_POSITIVE; // 1.17549435e-38f32
}
}
- /// 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;
!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_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.0f32;
/// Returns the maximum of the two numbers.
///
- /// 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;
///
/// 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]
/// Returns the minimum of the two numbers.
///
- /// 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;
///
/// 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]
intrinsics::minnumf32(self, other)
}
- /// Returns the maximum of the two numbers, propagating NaNs.
+ /// Returns the maximum of the two numbers.
///
/// This returns NaN when *either* argument is NaN, as opposed to
/// [`f32::max`] which only returns NaN when *both* arguments are NaN.
}
}
- /// Returns the minimum of the two numbers, propagating NaNs.
+ /// Returns the minimum of the two numbers.
///
/// This returns NaN when *either* argument is NaN, as opposed to
/// [`f32::min`] which only returns NaN when *both* arguments are NaN.
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 (∞).
#[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;
self.abs_private() == Self::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;
}
/// Returns `true` if the number is neither zero, infinite,
- /// [subnormal], or `NaN`.
+ /// [subnormal], or NaN.
///
/// ```
/// let min = f64::MIN_POSITIVE; // 2.2250738585072014e-308f64
}
}
- /// 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;
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_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;
/// Returns the maximum of the two numbers.
///
- /// 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;
///
/// 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]
/// Returns the minimum of the two numbers.
///
- /// 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;
///
/// 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]
intrinsics::minnumf64(self, other)
}
- /// Returns the maximum of the two numbers, propagating NaNs.
+ /// Returns the maximum of the two numbers.
///
/// This returns NaN when *either* argument is NaN, as opposed to
/// [`f64::max`] which only returns NaN when *both* arguments are NaN.
}
}
- /// Returns the minimum of the two numbers, propagating NaNs.
+ /// Returns the minimum of the two numbers.
///
/// This returns NaN when *either* argument is NaN, as opposed to
/// [`f64::min`] which only returns NaN when *both* arguments are NaN.
/// 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!
+/// - It is also neither smaller nor greater than any float, making it
+/// impossible to sort by the default comparison operation. This is the
+/// reason `f32` doesn't implement the `Ord` and `Eq` traits.
+/// - 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 *not* observed by the operation.
+/// - 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,
+/// so 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].
///
#[cfg(not(test))]
#[cfg_attr(bootstrap, lang = "f32_runtime")]
impl f32 {
- /// Returns the largest integer less than or equal to a number.
+ /// Returns the largest integer less than or equal to `self`.
///
/// # Examples
///
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
///
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
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
///
unsafe { intrinsics::truncf32(self) }
}
- /// Returns the fractional part of a number.
+ /// Returns the fractional part of `self`.
///
/// # Examples
///
self - self.trunc()
}
- /// Computes the absolute value of `self`. Returns `NAN` if the
- /// number is `NAN`.
+ /// Computes the absolute value of `self`.
///
/// # Examples
///
///
/// - `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
///
/// `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
///
/// 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 different sequence of rounding operations than `powf`,
+ /// so the results are not guaranteed to agree.
///
/// # Examples
///
#[cfg(not(test))]
#[cfg_attr(bootstrap, lang = "f64_runtime")]
impl f64 {
- /// Returns the largest integer less than or equal to a number.
+ /// Returns the largest integer less than or equal to `self`.
///
/// # Examples
///
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
///
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
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
///
unsafe { intrinsics::truncf64(self) }
}
- /// Returns the fractional part of a number.
+ /// Returns the fractional part of `self`.
///
/// # Examples
///
self - self.trunc()
}
- /// Computes the absolute value of `self`. Returns `NAN` if the
- /// number is `NAN`.
+ /// Computes the absolute value of `self`.
///
/// # Examples
///
///
/// - `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
///
/// `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
///
/// 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 different sequence of rounding operations than `powf`,
+ /// so the results are not guaranteed to agree.
///
/// # Examples
///
/// 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!
+/// - It is also neither smaller nor greater than any float, making it
+/// impossible to sort by the default comparison operation. This is the
+/// reason `f32` doesn't implement the `Ord` and `Eq` traits.
+/// - 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 *not* observed by the operation.
+/// - 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,
+/// so 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].
///
projects / rust.git / commitdiff