Expand documentation for FpCategory.

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.
This commit is contained in:
Kevin Reid 2021-08-30 20:20:14 -07:00
parent 6f388bb369
commit 18df8d6e55

View file

@ -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,
}