Skip to content

Commit

Permalink
Expand documentation for FpCategory.
Browse files Browse the repository at this point in the history
I intend these changes to be helpful to readers who are not yet familiar
with the quirks of floating-point numbers. Additionally, I felt it was
misleading to describe `Nan` as being the result of division by zero,
since most divisions by zero (except for 0/0) produce `Infinite` floats,
so I moved that remark to the `Infinite` variant with adjustment.

The first sentence of the `Nan` documentation is copied from `f32`;
I followed the example of the `f64` documentation by referring to `f32`
for general concepts, rather than duplicating the text.
  • Loading branch information
kpreid committed Aug 31, 2021
1 parent 6f388bb commit 18df8d6
Showing 1 changed file with 22 additions and 4 deletions.
26 changes: 22 additions & 4 deletions library/core/src/num/mod.rs
Original file line number Diff line number Diff line change
Expand Up @@ -778,23 +778,41 @@ impl usize {
#[derive(Copy, Clone, PartialEq, Eq, Debug)]
#[stable(feature = "rust1", since = "1.0.0")]
pub enum FpCategory {
/// "Not a Number", often obtained by dividing by zero.
/// NaN (not a number): this value results from calculations like `(-1.0).sqrt()`.
///
/// See [the documentation for `f32`](f32) for more information on the unusual properties
/// of NaN.
#[stable(feature = "rust1", since = "1.0.0")]
Nan,

/// Positive or negative infinity.
/// Positive or negative infinity, which often results from dividing a nonzero number
/// by zero.
#[stable(feature = "rust1", since = "1.0.0")]
Infinite,

/// Positive or negative zero.
///
/// See [the documentation for `f32`](f32) for more information on the signedness of zeroes.
#[stable(feature = "rust1", since = "1.0.0")]
Zero,

/// De-normalized floating point representation (less precise than `Normal`).
/// “Subnormal” or “denormal” floating point representation (less precise, relative to
/// their magnitude, than [`Normal`]).
///
/// Subnormal numbers are larger in magnitude than [`Zero`] but smaller in magnitude than all
/// [`Normal`] numbers.
///
/// [`Normal`]: Self::Normal
/// [`Zero`]: Self::Zero
#[stable(feature = "rust1", since = "1.0.0")]
Subnormal,

/// A regular floating point number.
/// A regular floating point number, not any of the exceptional categories.
///
/// The smallest positive normal numbers are [`f32::MIN_POSITIVE`] and [`f64::MIN_POSITIVE`],
/// and the largest positive normal numbers are [`f32::MAX`] and [`f64::MAX`]. (Unlike signed
/// integers, floating point numbers are symmetric in their range, so negating any of these
/// constants will produce their negative counterpart.)
#[stable(feature = "rust1", since = "1.0.0")]
Normal,
}
Expand Down

0 comments on commit 18df8d6

Please sign in to comment.