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_*returnsOption<T>:Noneon overflow.wrapping_*wraps around modulo 2^N.saturating_*clamps atMINorMAX.overflowing_*returns(wrapped_value, did_overflow).
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
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
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:
checkedfor "tell me",saturatingfor "clamp",wrappingfor hashes, counters and cryptography,overflowingwhen you need the carry (big-number arithmetic). - Overflow checks in release can be turned on with
overflow-checks = truein the Cargo profile; the explicit families behave the same regardless. try_foldwithchecked_addsums 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::Wrappingapplies 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.