Skip to content
Tutorials Center
My learning

Topics

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.

Rust
use std::num::Wrapping;
let w = Wrapping(250u8) + Wrapping(10);   // Wrapping(4)

Try it

Rust Wrapping versus saturating

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 hash function written with Wrapping

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
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) + 1 does not compile; wrap the literal as in Wrapping(1). Only the compound forms such as counter += 1 accept a plain integer.
  • Same layout: both wrappers are #[repr(transparent)], so Wrapping<u32> has the same size and alignment as u32.
  • Method alternatives: wrapping_*, saturating_*, checked_* and overflowing_* 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-checks explicitly in Cargo.toml if you rely on it.
  • Formatting: Display, Debug, Binary, LowerHex and UpperHex print the inner number (Debug prints just the number, so {:?} of Wrapping(4u8) shows 4).
  • Compare in generic code: neither wrapper implements the num crate traits; convert with .0 where needed.