Skip to content
Tutorials Center
My learning

Topics

Rust Reference ยท Primitive Types

NaN, infinity and total_cmp in Rust

Reference for Rust floating-point special values: NaN, infinity, negative zero, is_nan, is_finite, partial_cmp versus total_cmp and sorting floats safely.

IEEE 754 floats include values that are not ordinary numbers: positive and negative infinity (f64::INFINITY, f64::NEG_INFINITY), NaN ("not a number", f64::NAN) and a negative zero (-0.0) that equals 0.0 but is a different bit pattern. They appear from division by zero, sqrt of negatives, 0.0 / 0.0, ln(0.0) and overflow.

NaN is never equal to anything, including itself, and every ordering comparison with it is false. That is why f32 and f64 implement PartialOrd but not Ord, and why you cannot call .sort() or use a float as a BTreeMap key. total_cmp provides a complete ordering when you need one.

Rust
let n = f64::NAN;
n == n;            // false
n.is_nan();        // true

Try it

Rust Producing and detecting special values

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with io::stdin().read_line()), it gets the next line from this box.

Rust Sorting with total_cmp

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with io::stdin().read_line()), it gets the next line from this box.

Syntax

Rust
f64::NAN
f64::INFINITY
f64::NEG_INFINITY
x.is_nan()
x.is_finite()
x.is_infinite()
x.is_normal()
x.total_cmp(&y) -> Ordering
x.partial_cmp(&y) -> Option<Ordering>
Method Returns
is_nan() true for any NaN
is_finite() true unless infinite or NaN
is_infinite() true for +inf or -inf
is_normal() false for zero, subnormal, infinite and NaN
classify() A FpCategory (Nan, Infinite, Zero, Subnormal, Normal)
total_cmp(&other) Ordering, a total order: -NaN < -inf < ... < -0.0 < +0.0 < ... < +inf < +NaN
partial_cmp(&other) None if either side is NaN
is_sign_negative() true for negative numbers, -0.0 and negative NaN

Panics: none of these panic. Parsing "NaN", "inf" and "infinity" with str::parse::<f64>() succeeds.

Usage notes

  • Check is_nan(), never == f64::NAN. The comparison is always false.
  • NaN spreads: any arithmetic with a NaN gives NaN, which makes a single bad value contaminate a whole sum. Validate input or filter with is_finite.
  • total_cmp for sorting and maps. It follows the IEEE 754 totalOrder predicate. Under it -0.0 < 0.0, which differs from ==.
  • partial_cmp(...).unwrap() panics on NaN. Use it only when NaN cannot occur.
  • f64::max and min return the non-NaN argument, which can hide bad data silently.
  • The as cast from NaN to an integer is 0, and infinity saturates to MAX/MIN.
  • Wrapper crates (ordered-float, NotNan) are the usual way to get Ord floats for BTreeSet; the std-only approach is sorting with total_cmp or keying by to_bits.
  • Subnormal numbers (below MIN_POSITIVE) are legal but may be slow on some CPUs.