Skip to content

Commit 18df8d6

Browse files
committed
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.
1 parent 6f388bb commit 18df8d6

File tree

1 file changed

+22
-4
lines changed

1 file changed

+22
-4
lines changed

library/core/src/num/mod.rs

+22-4
Original file line numberDiff line numberDiff line change
@@ -778,23 +778,41 @@ impl usize {
778778
#[derive(Copy, Clone, PartialEq, Eq, Debug)]
779779
#[stable(feature = "rust1", since = "1.0.0")]
780780
pub enum FpCategory {
781-
/// "Not a Number", often obtained by dividing by zero.
781+
/// NaN (not a number): this value results from calculations like `(-1.0).sqrt()`.
782+
///
783+
/// See [the documentation for `f32`](f32) for more information on the unusual properties
784+
/// of NaN.
782785
#[stable(feature = "rust1", since = "1.0.0")]
783786
Nan,
784787

785-
/// Positive or negative infinity.
788+
/// Positive or negative infinity, which often results from dividing a nonzero number
789+
/// by zero.
786790
#[stable(feature = "rust1", since = "1.0.0")]
787791
Infinite,
788792

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

793-
/// De-normalized floating point representation (less precise than `Normal`).
799+
/// “Subnormal” or “denormal” floating point representation (less precise, relative to
800+
/// their magnitude, than [`Normal`]).
801+
///
802+
/// Subnormal numbers are larger in magnitude than [`Zero`] but smaller in magnitude than all
803+
/// [`Normal`] numbers.
804+
///
805+
/// [`Normal`]: Self::Normal
806+
/// [`Zero`]: Self::Zero
794807
#[stable(feature = "rust1", since = "1.0.0")]
795808
Subnormal,
796809

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

0 commit comments

Comments
 (0)