Skip to content
Tutorials Center
My learning

Topics

Rust Reference ยท Primitive Types

Rust NonZero integer types

Reference for Rust NonZero integers: NonZero<u32> and aliases like NonZeroU32, constructing with new, niche optimization for Option, and division by nonzero.

NonZero<T> (in std::num) is an integer type that can never be zero. There is one for every integer type, with aliases such as NonZeroU8, NonZeroU32, NonZeroI64 and NonZeroUsize. Because zero is impossible, the compiler uses that bit pattern to represent None, so Option<NonZeroU32> takes exactly 4 bytes, the same as a plain u32. This is called niche optimization.

You also get a type-level promise: a function that takes a NonZeroU32 for a divisor or a count does not need to check for zero. The generic NonZero<T> form has been stable since Rust 1.79; the named aliases are older.

Rust
use std::num::NonZeroU32;
let n = NonZeroU32::new(5).unwrap();

Try it

Rust Creating NonZero values and niche size

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 Arithmetic that cannot reach zero

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
NonZero<u32>                       // generic form (1.79+)
NonZeroU32                         // alias for NonZero<u32>
NonZeroU32::new(n) -> Option<NonZeroU32>
x.get() -> u32
unsafe { NonZeroU32::new_unchecked(n) }
Item Description
new(n) Returns None when n == 0. A const fn, so it can build constants.
new_unchecked(n) unsafe; undefined behavior if n is zero.
get() The plain integer.
TryFrom<T>, From<NonZero<T>> for T Checked conversion in, infallible conversion out.
MIN, MAX, BITS Smallest nonzero value (1 for unsigned, the smallest negative for signed), largest value, bit width.

Arithmetic: operators + and * are not implemented, because the result could overflow or (for signed types) wrap to zero. Use checked_* and saturating_* methods instead. Unsigned NonZero<T> implements BitOr (an OR of nonzero values is never zero), and T / NonZero<T> and T % NonZero<T> are implemented for unsigned T and cannot panic from division by zero.

Usage notes

  • Why bother: Option<NonZeroU32> is the compact "optional ID" type. Database row IDs, handles and indexes that start at 1 fit it naturally.
  • Niche rules: the guarantee covers Option<NonZero<T>> itself. Other types with a niche, such as &T, Box<T>, NonNull<T> and bool, behave the same way.
  • Comparison and hashing work like the underlying integer; Display and Debug print the number.
  • Parsing: "5".parse::<NonZeroU32>() works and fails for "0" with a ParseIntError.
  • Signed types: NonZeroI32::MIN is i32::MIN, not 1; abs() of that value overflows (it panics in debug builds), so use checked_abs or unsigned_abs.
  • Compared with zero checks at run time: the type moves the check to the single place where the value is created.
  • Serialization crates usually support NonZero types, and zero in the input becomes a parse error.