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.
use std::num::NonZeroU32; let n = NonZeroU32::new(5).unwrap();
Try it
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.
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
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>andbool, behave the same way. - Comparison and hashing work like the underlying integer;
DisplayandDebugprint the number. - Parsing:
"5".parse::<NonZeroU32>()works and fails for"0"with aParseIntError. - Signed types:
NonZeroI32::MINisi32::MIN, not1;abs()of that value overflows (it panics in debug builds), so usechecked_absorunsigned_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
NonZerotypes, and zero in the input becomes a parse error.