Skip to content
Tutorials Center
My learning

Topics

Rust Reference ยท Standard Library Modules

The std::num module

Reference for Rust std::num: ParseIntError and IntErrorKind, ParseFloatError, TryFromIntError, NonZero, Wrapping, Saturating and FpCategory.

std::num collects the helper types around the numeric primitives. Most are error types returned by parsing and conversion (ParseIntError, ParseFloatError, TryFromIntError), plus a few wrappers that change how arithmetic behaves: Wrapping<T> and Saturating<T> change overflow behavior, and NonZero<T> guarantees a value is never zero.

You will meet this module mostly through error messages and match arms. For instance "abc".parse::<i32>() gives Err(ParseIntError), and ParseIntError::kind() tells you whether the input was empty, invalid, or too large.

Rust
use std::num::{NonZero, Wrapping};

let w = Wrapping(250u8) + Wrapping(10);
let nz = NonZero::new(5u32);

Try it

Rust Parse errors and their kinds

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 Wrapping, Saturating and NonZero

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

Item Description
ParseIntError Error of from_str / str::parse for integers. kind() returns &IntErrorKind.
IntErrorKind Empty, InvalidDigit, PosOverflow, NegOverflow, Zero (for NonZero parsing). Non-exhaustive.
ParseFloatError Error of float parsing.
TryFromIntError Error of TryFrom between integer types.
Wrapping<T> Arithmetic wraps on overflow, in all build modes. Field .0.
Saturating<T> Arithmetic clamps at the limits (stable since 1.74).
NonZero<T> Integer known to be nonzero. new, get, checked_*, saturating_*. Aliases like NonZeroU32.
FpCategory Nan, Infinite, Zero, Subnormal, Normal, returned by f64::classify.
ZeroablePrimitive Sealed marker trait for the types NonZero accepts.

Usage notes

  • Parsing is strict. No whitespace is trimmed: " 42".parse::<i32>() fails. A leading + is accepted for all integers, - only for signed ones.
  • Parse into the target type, not a wider type followed by a cast, so the overflow errors are reported.
  • Wrapping and Saturating apply to every operator, so you do not need to call wrapping_add for each operation. Methods on the primitive (wrapping_add, saturating_sub, checked_mul, overflowing_add) cover one-off cases.
  • NonZero<T> gives layout optimizations: Option<NonZero<T>> is the same size as T. Old aliases NonZeroU8 ... NonZeroIsize still work; the generic NonZero<T> is stable since 1.79.
  • Errors implement std::error::Error, so ? converts them into Box<dyn Error>.
  • Debug builds panic on overflow; release builds wrap by default unless overflow-checks is on. Choose the explicit method when the behavior matters.
  • ParseIntError has no public constructor, and its message text is not a stable API; match on kind() instead of the text.
  • Floats: parse::<f64> accepts inf, NaN, exponents, and 1. or .5, but not hex or underscores.