Skip to content
Tutorials Center
My learning

Topics

Rust Reference ยท Concepts

Integer overflow in Rust

Reference for integer overflow in Rust: panics in debug builds, wrapping in release builds, checked, wrapping, saturating and overflowing methods, casts and edge cases.

Fixed-width integers have a limited range: a u8 holds 0 to 255, an i32 about plus or minus 2.1 billion. When an arithmetic result does not fit, that is overflow. Rust never lets it silently produce undefined behavior, and it refuses to guess what you want: the outcome depends on the build profile.

With overflow checks on, which is the default for debug builds (and for this site's runner), an overflowing +, - or * panics with "attempt to add with overflow". With overflow checks off, which is the default for release builds, the result wraps around in two's complement (255u8 + 1 becomes 0). Both behaviors are defined; neither is undefined behavior. When wrapping or saturation is what you actually mean, say so with an explicit method.

Rust
let a: u8 = 250;
// a + 10                  // debug: panic; release: 4
let b = a.wrapping_add(10);  // always 4

Try it

Rust The four explicit families

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 Casts never panic

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 A real overflow panic in a debug build

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.

What can overflow

Operation In a checked build
+, -, * panics attempt to add/subtract/multiply with overflow
unary -, abs() on MIN panics (-i32::MIN does not fit)
/, % by zero always panics, in every build
MIN / -1, MIN % -1 always panics, in every build
<<, >> by >= bits panics attempt to shift left with overflow
pow panics on overflow like *; use checked_pow
as casts never panic; truncate, wrap or saturate
iter().sum() / product() panic on overflow in checked builds
u32 - bigger u32 panics (attempt to subtract with overflow), a classic bug with len() - 1

Constant expressions that are certain to overflow, like 255_u8 + 1, are rejected at compile time by the deny-by-default arithmetic_overflow lint, so tests that trigger a runtime panic need values the compiler cannot see.

Usage notes

  • Where it is configured: in Cargo.toml, [profile.release] overflow-checks = true keeps checks in release builds; [profile.dev] overflow-checks = false turns them off. rustc -C overflow-checks=on|off does the same. See Cargo profiles.
  • Do not rely on wrapping by accident. Code that works in release only because it wraps is a bug that debug builds reveal. Use wrapping_* or Wrapping<T> for hashes, checksums and random-number generators, where wrapping is intended.
  • checked_* for untrusted input. Parsing, sizes and offsets from users or files should use checked_add, checked_mul and try_from, and treat None as an error.
  • saturating_* for clamped quantities such as health points, volume and counters that must not go below zero.
  • Subtracting indexes: write a.saturating_sub(b) or compare first; v.len() - 1 panics on an empty vector in checked builds and wraps to a huge number otherwise.
  • abs_diff gives the absolute difference of two integers without overflow, returning the unsigned type.
  • Compound assignment (+=) follows the same rules as +.
  • Performance: overflow checks cost a branch per operation; release builds omit them by default for speed.
  • 128-bit and big values: use u128/i128, or a bignum crate (not available in our runner), when u64 is not enough.