Integer parsing and overflow

from_str_radix, IntErrorKind, and checked, wrapping, saturating, and overflowing integer arithmetic. Complements the existing parse and TryFrom pages.

Integer types in the standard library provide radix parsing and overflow-aware arithmetic. This page does not repeat the str::parse::<u16>() recipe on the Option and Result page, and it does not repeat From or TryFrom conversions. Those APIs remain on their pages.

from_str_radix parses a digit string in a given base. On failure it returns ParseIntError; kind() is an IntErrorKind such as InvalidDigit. checked_add returns None on overflow. wrapping_add wraps in two's complement. saturating_add clamps to the type's min or max. overflowing_add returns the wrapped value and a bool. These methods were checked with rustc 1.90.0.

Examples were compiled with rustc 1.90.0 using --edition=2024 and run as a plain binary. See the Rust 1.90.0 documentation for the complete API.

Rust reference overview →

API index

APISummary
from_str_radix, ParseIntError::kindParse a digit string in a given radix and inspect IntErrorKind on failure. An invalid radix panics; invalid digits return Err.
checked_add, wrapping_add, saturating_add, overflowing_add, checked_div, saturating_subAdd or divide with an explicit overflow policy. checked_div(0) is None; some wrapping division methods still panic on zero.

from_str_radix

i32::from_str_radix("ff", 16) is Ok(255). "fg" is not a valid hexadecimal digit string, so the result is Err, and kind() is InvalidDigit. Official documentation says the radix must be in 2 through 36 inclusive, and that the function panics if it is not. This example does not pass an out-of-range radix. Overflow of a decimal string such as "65536" into a u16 is already shown on the parse page; this example uses a radix and kind() instead.

from_str_radix, ParseIntError::kind

pub fn from_str_radix(src: &str, radix: u32) -> Result<Self, ParseIntError>
pub fn kind(&self) -> &IntErrorKind

Parse a digit string in a given radix and inspect IntErrorKind on failure. An invalid radix panics; invalid digits return Err.

ParameterDescription
srcThe digit string, without a radix prefix such as 0x. Sign characters are allowed for signed types.
radixThe base, from 2 to 36 inclusive. A radix outside that range panics.

Returns: Ok(value) when the string is valid in that radix and fits in the target type, otherwise Err(ParseIntError). kind() borrows an IntErrorKind.

Errors and panics

  • ParseIntError — Returned for empty input, invalid digits, or overflow. The example prints Debug of kind(), which is InvalidDigit for "fg" in base 16. This was measured with rustc 1.90.0.
  • panic — from_str_radix panics if radix is not in 2..=36. That case is not executed here.
  • See the Option and Result page for decimal parse::<u16>() of a port string, including values that do not fit in u16.
rust
fn main() {
    println!("{}", i32::from_str_radix("ff", 16).unwrap());
    let err = i32::from_str_radix("fg", 16).unwrap_err();
    println!("{:?}", err.kind());
}

Expected output

255
InvalidDigit

Related: str::parse and Result, TryFrom for integers

Official documentation →

Checked, wrapping, and saturating arithmetic

i8::MAX is 127. checked_add(1) is None. wrapping_add(1) is -128. saturating_add(1) stays 127. overflowing_add(1) is (-128, true). checked_div(0) is None; it does not panic. Official documentation says wrapping_div and similar methods still panic on division by zero, so this page uses checked_div for a zero divisor. saturating_sub(1) on i8::MIN stays -128.

checked_add, wrapping_add, saturating_add, overflowing_add, checked_div, saturating_sub

pub const fn checked_add(self, rhs: Self) -> Option<Self>
pub const fn wrapping_add(self, rhs: Self) -> Self
pub const fn saturating_add(self, rhs: Self) -> Self
pub const fn overflowing_add(self, rhs: Self) -> (Self, bool)
pub const fn checked_div(self, rhs: Self) -> Option<Self>
pub const fn saturating_sub(self, rhs: Self) -> Self

Add or divide with an explicit overflow policy. checked_div(0) is None; some wrapping division methods still panic on zero.

ParameterDescription
rhsThe other operand. For checked_div, 0 yields None rather than a panic.

Returns: checked_ methods return Option. wrapping_add returns the two's-complement wrap. saturating_ methods return a value clamped to the type bounds. overflowing_add returns the wrapped value and whether overflow occurred.

Errors and panics

  • panic — These addition methods do not panic. wrapping_div and similar still panic on a zero divisor according to official documentation; that call is not used here.
  • The -128 and 127 results are the i8 bounds and were measured with rustc 1.90.0.
  • Integer conversion with TryFrom is on the convert page. This page stays with overflow methods and radix parsing.
rust
fn main() {
    println!("{:?}", i8::MAX.checked_add(1));
    println!("{}", i8::MAX.wrapping_add(1));
    println!("{}", i8::MAX.saturating_add(1));
    println!("{:?}", i8::MAX.overflowing_add(1));
    println!("{:?}", 1i8.checked_div(0));
    println!("{}", i8::MIN.saturating_sub(1));
}

Expected output

None
-128
127
(-128, true)
None
-128

Related: TryFrom for integers

Official documentation →