i128

i128 is a 128-bit signed integer primitive type in Rust. It occupies 16 bytes of memory and represents values using two’s complement binary encoding, providing the largest native integer size available in the Rust standard library.

Value Range

Because it is a signed 128-bit integer, its range is defined mathematically as $-2^{127}$ to $2^{127} - 1$.

• Minimum (i128::MIN): -170,141,183,460,469,231,731,687,303,715,884,105,728
• Maximum (i128::MAX): 170,141,183,460,469,231,731,687,303,715,884,105,727

Syntax and Initialization

You can declare i128 values using type inference, explicit type annotation, or the i128 literal suffix. Rust allows the _ character as a visual separator to manage the high digit count.

// Explicit type annotation
let a: i128 = 100000000000000000000000000000000000000;

// Literal suffix
let b = -50_000_000_000_000_000_000_i128;

// Hexadecimal, octal, and binary literals
let hex_val: i128 = 0x7FFF_FFFF_FFFF_FFFF_FFFF_FFFF_FFFF_FFFF;
let bin_val: i128 = 0b1010_1010_i128;

Memory Layout and Endianness

i128 is stored as a contiguous 16-byte sequence. The byte order (endianness) depends on the target architecture, but Rust provides explicit methods to serialize and deserialize i128 into byte arrays ([u8; 16]) regardless of the host platform’s native endianness.

let val: i128 = 0x0123456789ABCDEF_0123456789ABCDEF;

// Native endianness (target-dependent)
let ne_bytes: [u8; 16] = val.to_ne_bytes();

// Little-endian (least significant byte first)
let le_bytes: [u8; 16] = val.to_le_bytes();

// Big-endian (most significant byte first)
let be_bytes: [u8; 16] = val.to_be_bytes();

// Reconstructing from bytes
let reconstructed = i128::from_be_bytes(be_bytes);

Arithmetic and Overflow Behavior

Standard arithmetic operators (+, -, *, /, %) are implemented for i128. By default, integer overflow causes a panic in debug builds and performs two’s complement wrapping in release builds.

To enforce specific overflow behaviors programmatically, i128 exposes explicit arithmetic methods:

let max = i128::MAX;

// Checked: Returns Option::None on overflow
let checked: Option<i128> = max.checked_add(1); 

// Wrapping: Wraps around the boundary (returns i128::MIN)
let wrapped: i128 = max.wrapping_add(1); 

// Saturating: Clamps to the numeric boundary (returns i128::MAX)
let saturated: i128 = max.saturating_add(1); 

// Overflowing: Returns a tuple (result, boolean_flag)
let (result, did_overflow) = max.overflowing_add(1);

Type Conversion (Casting)

Casting between i128 and other primitive types is handled via the as keyword or the From/Into traits.

• Widening: Converting smaller integers (e.g., i64, u32) to i128 is lossless and can be done safely using From.
• Narrowing: Casting i128 to smaller integers using as truncates the higher-order bits, which alters the value and potentially the sign if the truncated value exceeds the target type’s capacity.

// Lossless widening (Safe)
let small_val: i64 = 42;
let widened: i128 = i128::from(small_val);

// Narrowing via truncation (Lossy)
let large_val: i128 = 0x1234_5678_9ABC_DEF0_1111_2222_3333_4444;
let truncated: i64 = large_val as i64; // Yields 0x1111_2222_3333_4444

// Checked narrowing (Safe)
use std::convert::TryFrom;
let safe_cast = i64::try_from(large_val); // Returns Result::Err

Master Rust with Deep Grasping Methodology!

Learn More