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.
let a: u8 = 250; // a + 10 // debug: panic; release: 4 let b = a.wrapping_add(10); // always 4
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.
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 = truekeeps checks in release builds;[profile.dev] overflow-checks = falseturns them off.rustc -C overflow-checks=on|offdoes 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_*orWrapping<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 usechecked_add,checked_mulandtry_from, and treatNoneas 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() - 1panics on an empty vector in checked builds and wraps to a huge number otherwise. abs_diffgives 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), whenu64is not enough.