Skip to content
Tutorials Center
My learning

Topics

Rust Reference ยท Primitive Types

Rust integer arithmetic methods

Reference for Rust integer arithmetic methods: checked_, wrapping_, saturating_, overflowing_ and strict_ families, pow, rem_euclid, and when to use each.

Plain +, - and * on integers panic on overflow in debug builds and wrap in release builds. When overflow is a real possibility, you pick the behavior you want by calling one of four method families, each available for add, sub, mul, div, rem, neg, pow, shl, shr and abs where meaningful:

  • checked_* returns Option<T>: None on overflow.
  • wrapping_* wraps around modulo 2^N.
  • saturating_* clamps at MIN or MAX.
  • overflowing_* returns (wrapped_value, did_overflow).
Rust
let x: u8 = 250;
x.checked_add(10);      // None
x.wrapping_add(10);     // 4
x.saturating_add(10);   // 255
x.overflowing_add(10);  // (4, true)

Try it

Rust Four ways to overflow

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 Choosing the right family

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
fn checked_add(self, rhs: Self) -> Option<Self>
fn wrapping_add(self, rhs: Self) -> Self
fn saturating_add(self, rhs: Self) -> Self
fn overflowing_add(self, rhs: Self) -> (Self, bool)
fn pow(self, exp: u32) -> Self
fn rem_euclid(self, rhs: Self) -> Self
Family Returns Overflow result
checked_* Option<T> None
wrapping_* T Result modulo 2^N
saturating_* T T::MIN or T::MAX
overflowing_* (T, bool) Wrapped value and true
operator (+) T Panic in debug, wrap in release (unless overridden)

Also available: checked_neg, checked_shl, checked_next_power_of_two, checked_ilog2, wrapping_neg, saturating_mul, saturating_pow, checked_add_signed (unsigned + signed), saturating_add_signed, div_ceil, isqrt.

Edge cases: the exponent of pow is always u32; checked_div/checked_rem return None for a zero divisor and for MIN / -1; the plain / and % panic in both cases regardless of build mode.

Usage notes

  • Pick by intent: checked for "tell me", saturating for "clamp", wrapping for hashes, counters and cryptography, overflowing when you need the carry (big-number arithmetic).
  • Overflow checks in release can be turned on with overflow-checks = true in the Cargo profile; the explicit families behave the same regardless.
  • try_fold with checked_add sums a sequence and short-circuits on overflow; see the second example.
  • Mixed-sign helpers: u32::checked_add_signed(i32) is the right way to apply a signed offset to an unsigned index without casts.
  • std::num::Wrapping applies wrapping semantics to ordinary operators; see Wrapping and Saturating.
  • Performance: the wrapping family compiles to a single instruction; checked and saturating variants add a branch or a conditional move.