Rollup merge of #95483 - golddranks:improve_float_docs, r=joshtriplett
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
GitHub
commit
28d800ce1c
6 changed files with 182 additions and 68 deletions
|
|
@ -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
|
||||
///
|
||||
|
|
|
|||
|
|
@ -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
|
||||
///
|
||||
|
|
|
|||
|
|
@ -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].
|
||||
///
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue