Rust Reference ยท Primitive Types
Rust Wrapping and Saturating types
Reference for Rust Wrapping<T> and Saturating<T> in std::num: integer wrappers whose operators wrap around or clamp instead of panicking on overflow.
Ordinary integer arithmetic panics on overflow in debug builds and wraps silently in release builds (unless overflow checks are enabled). When you want one specific behavior everywhere, std::num offers two wrapper types. Wrapping<T> always wraps around using two's complement, like modular arithmetic. Saturating<T> (stable since Rust 1.74) clamps to the type's minimum or maximum.
Both are tuple structs with a public field, so Wrapping(5u8).0 reads the number back. They implement the arithmetic, bitwise and assignment operators, so ordinary-looking code like hash = hash * 31 + c keeps its shape.
use std::num::Wrapping; let w = Wrapping(250u8) + Wrapping(10); // Wrapping(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.
Syntax
Wrapping<T>(pub T) Saturating<T>(pub T) Wrapping(a) + Wrapping(b) // Wrapping<T> Wrapping(a) + b // error: needs a wrapper on the right w += b // compound forms accept a plain integer
| Item | Description |
|---|---|
.0 |
The inner integer. |
| Operators | + - * / %, the bitwise operators (and, or, xor, not), << >>, unary - (signed types), and their *= forms. Binary operators need a wrapper on both sides; compound forms (+=) also take a plain integer; shifts take usize. |
| Integer methods | Mostly unstable on the wrappers (pow, MIN, MAX and friends); on stable, read .0 and call the wrapping_* method there. |
Edge cases: division and remainder by zero still panic. Wrapping(i8::MIN) / Wrapping(-1) wraps to i8::MIN instead of panicking. Shift amounts are reduced modulo the bit width, so << 35 on a u32 shifts by 3.
Usage notes
- Hashes and checksums such as FNV, Adler and linear congruential generators rely on wrapping multiplication and addition. The wrapper type documents that intent and survives a change of build profile.
- Counters and meters that must never go below zero or above a limit fit
Saturating. - Mixed operands:
Wrapping(1u8) + 1does not compile; wrap the literal as inWrapping(1). Only the compound forms such ascounter += 1accept a plain integer. - Same layout: both wrappers are
#[repr(transparent)], soWrapping<u32>has the same size and alignment asu32. - Method alternatives:
wrapping_*,saturating_*,checked_*andoverflowing_*on the integers choose a behavior per operation and are better for one-off spots. - Release builds: the default release profile wraps without panicking, but that is a profile setting, not a language promise; set
overflow-checksexplicitly inCargo.tomlif you rely on it. - Formatting:
Display,Debug,Binary,LowerHexandUpperHexprint the inner number (Debugprints just the number, so{:?}ofWrapping(4u8)shows4). - Compare in generic code: neither wrapper implements the
numcrate traits; convert with.0where needed.