Primitive Type i128 

The 128-bit signed integer type.

ABI compatibility

Rust’s i128 is expected to be ABI-compatible with C’s __int128 on platforms where the type is available, which includes most 64-bit architectures. If any platforms that do not specify __int128 are updated to introduce it, the Rust i128 ABI on relevant targets will be changed to match.

It is important to note that in C, __int128 is not the same as _BitInt(128), and the two types are allowed to have different ABIs. In particular, on x86, __int128 and _BitInt(128) do not use the same alignment. i128 is intended to always match __int128 and does not attempt to match _BitInt(128) on platforms without __int128.

Implementations

impl i128

pub const MIN: i128

The smallest value that can be represented by this integer type (−2¹²⁷).

Examples

assert_eq!(i128::MIN, -170141183460469231731687303715884105728);

pub const MAX: i128

The largest value that can be represented by this integer type (2¹²⁷ − 1).

Examples

assert_eq!(i128::MAX, 170141183460469231731687303715884105727);

pub const BITS: u32 = u128::BITS

The size of this integer type in bits.

Examples

assert_eq!(i128::BITS, 128);

pub const fn count_ones(self) -> u32

Returns the number of ones in the binary representation of self.

Examples

let n = 0b100_0000i128;

assert_eq!(n.count_ones(), 1);

pub const fn count_zeros(self) -> u32

Returns the number of zeros in the binary representation of self.

Examples

assert_eq!(i128::MAX.count_zeros(), 1);

pub const fn leading_zeros(self) -> u32

Returns the number of leading zeros in the binary representation of self.

Depending on what you’re doing with the value, you might also be interested in the ilog2 function which returns a consistent number, even if the type widens.

Examples

let n = -1i128;

assert_eq!(n.leading_zeros(), 0);

pub const fn trailing_zeros(self) -> u32

Returns the number of trailing zeros in the binary representation of self.

Examples

let n = -4i128;

assert_eq!(n.trailing_zeros(), 2);

pub const fn leading_ones(self) -> u32

Returns the number of leading ones in the binary representation of self.

Examples

let n = -1i128;

assert_eq!(n.leading_ones(), 128);

pub const fn trailing_ones(self) -> u32

Returns the number of trailing ones in the binary representation of self.

Examples

let n = 3i128;

assert_eq!(n.trailing_ones(), 2);

pub const fn isolate_highest_one(self) -> i128

Returns self with only the most significant bit set, or 0 if the input is 0.

Examples

let n: i128 = 0b_01100100;

assert_eq!(n.isolate_highest_one(), 0b_01000000);
assert_eq!(0_i128.isolate_highest_one(), 0);

pub const fn isolate_lowest_one(self) -> i128

Returns self with only the least significant bit set, or 0 if the input is 0.

Examples

let n: i128 = 0b_01100100;

assert_eq!(n.isolate_lowest_one(), 0b_00000100);
assert_eq!(0_i128.isolate_lowest_one(), 0);

pub const fn highest_one(self) -> Option<u32>

Returns the index of the highest bit set to one in self, or None if self is 0.

Examples

assert_eq!(0b0_i128.highest_one(), None);
assert_eq!(0b1_i128.highest_one(), Some(0));
assert_eq!(0b1_0000_i128.highest_one(), Some(4));
assert_eq!(0b1_1111_i128.highest_one(), Some(4));

pub const fn lowest_one(self) -> Option<u32>

Returns the index of the lowest bit set to one in self, or None if self is 0.

Examples

assert_eq!(0b0_i128.lowest_one(), None);
assert_eq!(0b1_i128.lowest_one(), Some(0));
assert_eq!(0b1_0000_i128.lowest_one(), Some(4));
assert_eq!(0b1_1111_i128.lowest_one(), Some(0));

pub const fn cast_unsigned(self) -> u128

Returns the bit pattern of self reinterpreted as an unsigned integer of the same size.

This produces the same result as an as cast, but ensures that the bit-width remains the same.

Examples

let n = -1i128;

assert_eq!(n.cast_unsigned(), u128::MAX);

pub const fn saturating_cast_unsigned(self) -> u128

🔬This is a nightly-only experimental API. (integer_cast_extras #154650)

Saturating conversion of self to an unsigned integer of the same size.

Negative values are clamped to 0.

For other kinds of unsigned integer casts, see cast_unsigned, checked_cast_unsigned, or strict_cast_unsigned.

Examples

#![feature(integer_cast_extras)]
let n = i128::MIN;

assert_eq!(n.saturating_cast_unsigned(), 0u128);
assert_eq!(64i128.saturating_cast_unsigned(), 64u128);

pub const fn checked_cast_unsigned(self) -> Option<u128>

🔬This is a nightly-only experimental API. (integer_cast_extras #154650)

Checked conversion of self to an unsigned integer of the same size, returning None if self is negative.

For other kinds of unsigned integer casts, see cast_unsigned, saturating_cast_unsigned, or strict_cast_unsigned.

Examples

#![feature(integer_cast_extras)]
let n = i128::MIN;

assert_eq!(n.checked_cast_unsigned(), None);
assert_eq!(64i128.checked_cast_unsigned(), Some(64u128));

pub const fn strict_cast_unsigned(self) -> u128

🔬This is a nightly-only experimental API. (integer_cast_extras #154650)

Strict conversion of self to an unsigned integer of the same size, which panics if self is negative.

For other kinds of unsigned integer casts, see cast_unsigned, checked_cast_unsigned, or saturating_cast_unsigned.

Examples

#![feature(integer_cast_extras)]
let _ = i128::MIN.strict_cast_unsigned();

pub const fn rotate_left(self, n: u32) -> i128

Shifts the bits to the left by a specified amount, n, wrapping the truncated bits to the end of the resulting integer.

rotate_left(n) is equivalent to applying rotate_left(1) a total of n times. In particular, a rotation by the number of bits in self returns the input value unchanged.

Please note this isn’t the same operation as the << shifting operator!

Examples

let n = 0x13f40000000000000000000000004f76i128;
let m = 0x4f7613f4;

assert_eq!(n.rotate_left(16), m);
assert_eq!(n.rotate_left(1024), n);

pub const fn rotate_right(self, n: u32) -> i128

Shifts the bits to the right by a specified amount, n, wrapping the truncated bits to the beginning of the resulting integer.

rotate_right(n) is equivalent to applying rotate_right(1) a total of n times. In particular, a rotation by the number of bits in self returns the input value unchanged.

Please note this isn’t the same operation as the >> shifting operator!

Examples

let n = 0x4f7613f4i128;
let m = 0x13f40000000000000000000000004f76;

assert_eq!(n.rotate_right(16), m);
assert_eq!(n.rotate_right(1024), n);

pub const fn swap_bytes(self) -> i128

Reverses the byte order of the integer.

Examples

let n = 0x12345678901234567890123456789012i128;

let m = n.swap_bytes();

assert_eq!(m, 0x12907856341290785634129078563412);

pub const fn reverse_bits(self) -> i128

Reverses the order of bits in the integer. The least significant bit becomes the most significant bit, second least-significant bit becomes second most-significant bit, etc.

Examples

let n = 0x12345678901234567890123456789012i128;
let m = n.reverse_bits();

assert_eq!(m, 0x48091e6a2c48091e6a2c48091e6a2c48);
assert_eq!(0, 0i128.reverse_bits());

pub const fn from_be(x: i128) -> i128

Converts an integer from big endian to the target’s endianness.

On big endian this is a no-op. On little endian the bytes are swapped.

See also from_be_bytes().

Examples

let n = 0x1Ai128;

if cfg!(target_endian = "big") {
    assert_eq!(i128::from_be(n), n)
} else {
    assert_eq!(i128::from_be(n), n.swap_bytes())
}

pub const fn from_le(x: i128) -> i128

Converts an integer from little endian to the target’s endianness.

On little endian this is a no-op. On big endian the bytes are swapped.

See also from_le_bytes().

Examples

let n = 0x1Ai128;

if cfg!(target_endian = "little") {
    assert_eq!(i128::from_le(n), n)
} else {
    assert_eq!(i128::from_le(n), n.swap_bytes())
}

pub const fn to_be(self) -> i128

Swaps bytes of self on little endian targets.

On big endian this is a no-op.

The returned value has the same type as self, and will be interpreted as (a potentially different) value of a native-endian i128.

See to_be_bytes() for a type-safe alternative.

Examples

let n = 0x1Ai128;

if cfg!(target_endian = "big") {
    assert_eq!(n.to_be(), n)
} else {
    assert_eq!(n.to_be(), n.swap_bytes())
}

pub const fn to_le(self) -> i128

Swaps bytes of self on big endian targets.

On little endian this is a no-op.

The returned value has the same type as self, and will be interpreted as (a potentially different) value of a native-endian i128.

See to_le_bytes() for a type-safe alternative.

Examples

let n = 0x1Ai128;

if cfg!(target_endian = "little") {
    assert_eq!(n.to_le(), n)
} else {
    assert_eq!(n.to_le(), n.swap_bytes())
}

pub const fn checked_add(self, rhs: i128) -> Option<i128>

Checked integer addition. Computes self + rhs, returning None if overflow occurred.

Examples

assert_eq!((i128::MAX - 2).checked_add(1), Some(i128::MAX - 1));
assert_eq!((i128::MAX - 2).checked_add(3), None);

pub const fn strict_add(self, rhs: i128) -> i128

Strict integer addition. Computes self + rhs, panicking if overflow occurred.

Panics

Overflow behavior

This function will always panic on overflow, regardless of whether overflow checks are enabled.

Examples

assert_eq!((i128::MAX - 2).strict_add(1), i128::MAX - 1);

The following panics because of overflow:

let _ = (i128::MAX - 2).strict_add(3);

pub const unsafe fn unchecked_add(self, rhs: i128) -> i128

Unchecked integer addition. Computes self + rhs, assuming overflow cannot occur.

Calling x.unchecked_add(y) is semantically equivalent to calling x.checked_add(y).unwrap_unchecked().

If you’re just trying to avoid the panic in debug mode, then do not use this. Instead, you’re looking for wrapping_add.

Safety

This results in undefined behavior when self + rhs > i128::MAX or self + rhs < i128::MIN, i.e. when checked_add would return None.

pub const fn checked_add_unsigned(self, rhs: u128) -> Option<i128>

Checked addition with an unsigned integer. Computes self + rhs, returning None if overflow occurred.

Examples

assert_eq!(1i128.checked_add_unsigned(2), Some(3));
assert_eq!((i128::MAX - 2).checked_add_unsigned(3), None);

pub const fn strict_add_unsigned(self, rhs: u128) -> i128

Strict addition with an unsigned integer. Computes self + rhs, panicking if overflow occurred.

Panics

Overflow behavior

This function will always panic on overflow, regardless of whether overflow checks are enabled.

Examples

assert_eq!(1i128.strict_add_unsigned(2), 3);

The following panics because of overflow:

let _ = (i128::MAX - 2).strict_add_unsigned(3);

pub const fn checked_sub(self, rhs: i128) -> Option<i128>

Checked integer subtraction. Computes self - rhs, returning None if overflow occurred.

Examples

assert_eq!((i128::MIN + 2).checked_sub(1), Some(i128::MIN + 1));
assert_eq!((i128::MIN + 2).checked_sub(3), None);

pub const fn strict_sub(self, rhs: i128) -> i128

Strict integer subtraction. Computes self - rhs, panicking if overflow occurred.

Panics

Overflow behavior

This function will always panic on overflow, regardless of whether overflow checks are enabled.

Examples

assert_eq!((i128::MIN + 2).strict_sub(1), i128::MIN + 1);

The following panics because of overflow:

let _ = (i128::MIN + 2).strict_sub(3);

pub const unsafe fn unchecked_sub(self, rhs: i128) -> i128

Unchecked integer subtraction. Computes self - rhs, assuming overflow cannot occur.

Calling x.unchecked_sub(y) is semantically equivalent to calling x.checked_sub(y).unwrap_unchecked().

If you’re just trying to avoid the panic in debug mode, then do not use this. Instead, you’re looking for wrapping_sub.

Safety

This results in undefined behavior when self - rhs > i128::MAX or self - rhs < i128::MIN, i.e. when checked_sub would return None.

pub const fn checked_sub_unsigned(self, rhs: u128) -> Option<i128>

Checked subtraction with an unsigned integer. Computes self - rhs, returning None if overflow occurred.

Examples

assert_eq!(1i128.checked_sub_unsigned(2), Some(-1));
assert_eq!((i128::MIN + 2).checked_sub_unsigned(3), None);

pub const fn strict_sub_unsigned(self, rhs: u128) -> i128

Strict subtraction with an unsigned integer. Computes self - rhs, panicking if overflow occurred.

Panics

Overflow behavior

This function will always panic on overflow, regardless of whether overflow checks are enabled.

Examples

assert_eq!(1i128.strict_sub_unsigned(2), -1);

The following panics because of overflow:

let _ = (i128::MIN + 2).strict_sub_unsigned(3);

pub const fn checked_mul(self, rhs: i128) -> Option<i128>

Checked integer multiplication. Computes self * rhs, returning None if overflow occurred.

Examples

assert_eq!(i128::MAX.checked_mul(1), Some(i128::MAX));
assert_eq!(i128::MAX.checked_mul(2), None);

pub const fn strict_mul(self, rhs: i128) -> i128

Strict integer multiplication. Computes self * rhs, panicking if overflow occurred.

Panics

Overflow behavior

This function will always panic on overflow, regardless of whether overflow checks are enabled.

Examples

assert_eq!(i128::MAX.strict_mul(1), i128::MAX);

The following panics because of overflow:

let _ = i128::MAX.strict_mul(2);

pub const unsafe fn unchecked_mul(self, rhs: i128) -> i128

Unchecked integer multiplication. Computes self * rhs, assuming overflow cannot occur.

Calling x.unchecked_mul(y) is semantically equivalent to calling x.checked_mul(y).unwrap_unchecked().

If you’re just trying to avoid the panic in debug mode, then do not use this. Instead, you’re looking for wrapping_mul.

Safety

This results in undefined behavior when self * rhs > i128::MAX or self * rhs < i128::MIN, i.e. when checked_mul would return None.

pub const fn checked_div(self, rhs: i128) -> Option<i128>

Checked integer division. Computes self / rhs, returning None if rhs == 0 or the division results in overflow.

Examples

assert_eq!((i128::MIN + 1).checked_div(-1), Some(170141183460469231731687303715884105727));
assert_eq!(i128::MIN.checked_div(-1), None);
assert_eq!((1i128).checked_div(0), None);

pub const fn strict_div(self, rhs: i128) -> i128

Strict integer division. Computes self / rhs, panicking if overflow occurred.

Panics

This function will panic if rhs is zero.

Overflow behavior

This function will always panic on overflow, regardless of whether overflow checks are enabled.

The only case where such an overflow can occur is when one divides MIN / -1 on a signed type (where MIN is the negative minimal value for the type); this is equivalent to -MIN, a positive value that is too large to represent in the type.

Examples

assert_eq!((i128::MIN + 1).strict_div(-1), 170141183460469231731687303715884105727);

The following panics because of overflow:

let _ = i128::MIN.strict_div(-1);

The following panics because of division by zero:

let _ = (1i128).strict_div(0);

pub const fn checked_div_euclid(self, rhs: i128) -> Option<i128>

Checked Euclidean division. Computes self.div_euclid(rhs), returning None if rhs == 0 or the division results in overflow.

Examples

assert_eq!((i128::MIN + 1).checked_div_euclid(-1), Some(170141183460469231731687303715884105727));
assert_eq!(i128::MIN.checked_div_euclid(-1), None);
assert_eq!((1i128).checked_div_euclid(0), None);

pub const fn strict_div_euclid(self, rhs: i128) -> i128

Strict Euclidean division. Computes self.div_euclid(rhs), panicking if overflow occurred.

Panics

This function will panic if rhs is zero.

Overflow behavior

This function will always panic on overflow, regardless of whether overflow checks are enabled.

The only case where such an overflow can occur is when one divides MIN / -1 on a signed type (where MIN is the negative minimal value for the type); this is equivalent to -MIN, a positive value that is too large to represent in the type.

Examples

assert_eq!((i128::MIN + 1).strict_div_euclid(-1), 170141183460469231731687303715884105727);

The following panics because of overflow:

let _ = i128::MIN.strict_div_euclid(-1);

The following panics because of division by zero:

let _ = (1i128).strict_div_euclid(0);

pub const fn checked_div_exact(self, rhs: i128) -> Option<i128>

🔬This is a nightly-only experimental API. (exact_div #139911)

Checked integer division without remainder. Computes self / rhs, returning None if rhs == 0, the division results in overflow, or self % rhs != 0.

Examples

#![feature(exact_div)]
assert_eq!((i128::MIN + 1).checked_div_exact(-1), Some(170141183460469231731687303715884105727));
assert_eq!((-5i128).checked_div_exact(2), None);
assert_eq!(i128::MIN.checked_div_exact(-1), None);
assert_eq!((1i128).checked_div_exact(0), None);

pub const fn div_exact(self, rhs: i128) -> Option<i128>

🔬This is a nightly-only experimental API. (exact_div #139911)

Integer division without remainder. Computes self / rhs, returning None if self % rhs != 0.

Panics

This function will panic if rhs == 0.

Overflow behavior

On overflow, this function will panic if overflow checks are enabled (default in debug mode) and wrap if overflow checks are disabled (default in release mode).

Examples

#![feature(exact_div)]
assert_eq!(64i128.div_exact(2), Some(32));
assert_eq!(64i128.div_exact(32), Some(2));
assert_eq!((i128::MIN + 1).div_exact(-1), Some(170141183460469231731687303715884105727));
assert_eq!(65i128.div_exact(2), None);

#![feature(exact_div)]
let _ = 64i128.div_exact(0);

#![feature(exact_div)]
let _ = i128::MIN.div_exact(-1);

pub const unsafe fn unchecked_div_exact(self, rhs: i128) -> i128

🔬This is a nightly-only experimental API. (exact_div #139911)

Unchecked integer division without remainder. Computes self / rhs.

Safety

This results in undefined behavior when rhs == 0, self % rhs != 0, or self == i128::MIN && rhs == -1, i.e. when checked_div_exact would return None.

pub const fn checked_rem(self, rhs: i128) -> Option<i128>

Checked integer remainder. Computes self % rhs, returning None if rhs == 0 or the division results in overflow.

Examples

assert_eq!(5i128.checked_rem(2), Some(1));
assert_eq!(5i128.checked_rem(0), None);
assert_eq!(i128::MIN.checked_rem(-1), None);

pub const fn strict_rem(self, rhs: i128) -> i128

Strict integer remainder. Computes self % rhs, panicking if the division results in overflow.

Panics

This function will panic if rhs is zero.

Overflow behavior

This function will always panic on overflow, regardless of whether overflow checks are enabled.

The only case where such an overflow can occur is x % y for MIN / -1 on a signed type (where MIN is the negative minimal value), which is invalid due to implementation artifacts.

Examples

assert_eq!(5i128.strict_rem(2), 1);

The following panics because of division by zero:

let _ = 5i128.strict_rem(0);

The following panics because of overflow:

let _ = i128::MIN.strict_rem(-1);

pub const fn checked_rem_euclid(self, rhs: i128) -> Option<i128>

Checked Euclidean remainder. Computes self.rem_euclid(rhs), returning None if rhs == 0 or the division results in overflow.

Examples

assert_eq!(5i128.checked_rem_euclid(2), Some(1));
assert_eq!(5i128.checked_rem_euclid(0), None);
assert_eq!(i128::MIN.checked_rem_euclid(-1), None);

pub const fn strict_rem_euclid(self, rhs: i128) -> i128

Strict Euclidean remainder. Computes self.rem_euclid(rhs), panicking if the division results in overflow.

Panics

This function will panic if rhs is zero.

Overflow behavior

This function will always panic on overflow, regardless of whether overflow checks are enabled.

The only case where such an overflow can occur is x % y for MIN / -1 on a signed type (where MIN is the negative minimal value), which is invalid due to implementation artifacts.

Examples

assert_eq!(5i128.strict_rem_euclid(2), 1);

The following panics because of division by zero:

let _ = 5i128.strict_rem_euclid(0);

The following panics because of overflow:

let _ = i128::MIN.strict_rem_euclid(-1);

pub const fn checked_neg(self) -> Option<i128>

Checked negation. Computes -self, returning None if self == MIN.

Examples

assert_eq!(5i128.checked_neg(), Some(-5));
assert_eq!(i128::MIN.checked_neg(), None);

pub const unsafe fn unchecked_neg(self) -> i128

Unchecked negation. Computes -self, assuming overflow cannot occur.

Safety

This results in undefined behavior when self == i128::MIN, i.e. when checked_neg would return None.

pub const fn strict_neg(self) -> i128

Strict negation. Computes -self, panicking if self == MIN.

Panics

Overflow behavior

This function will always panic on overflow, regardless of whether overflow checks are enabled.

Examples

assert_eq!(5i128.strict_neg(), -5);

The following panics because of overflow:

let _ = i128::MIN.strict_neg();

pub const fn checked_shl(self, rhs: u32) -> Option<i128>

Checked shift left. Computes self << rhs, returning None if rhs is larger than or equal to the number of bits in self.

Examples

assert_eq!(0x1i128.checked_shl(4), Some(0x10));
assert_eq!(0x1i128.checked_shl(129), None);
assert_eq!(0x10i128.checked_shl(127), Some(0));

pub const fn strict_shl(self, rhs: u32) -> i128

Strict shift left. Computes self << rhs, panicking if rhs is larger than or equal to the number of bits in self.

Panics

Overflow behavior

This function will always panic on overflow, regardless of whether overflow checks are enabled.

Examples

assert_eq!(0x1i128.strict_shl(4), 0x10);

The following panics because of overflow:

let _ = 0x1i128.strict_shl(129);

pub const unsafe fn unchecked_shl(self, rhs: u32) -> i128

Unchecked shift left. Computes self << rhs, assuming that rhs is less than the number of bits in self.

Safety

This results in undefined behavior if rhs is larger than or equal to the number of bits in self, i.e. when checked_shl would return None.

pub const fn unbounded_shl(self, rhs: u32) -> i128

Unbounded shift left. Computes self << rhs, without bounding the value of rhs.

If rhs is larger or equal to the number of bits in self, the entire value is shifted out, and 0 is returned.

Examples

assert_eq!(0x1_i128.unbounded_shl(4), 0x10);
assert_eq!(0x1_i128.unbounded_shl(129), 0);
assert_eq!(0b101_i128.unbounded_shl(0), 0b101);
assert_eq!(0b101_i128.unbounded_shl(1), 0b1010);
assert_eq!(0b101_i128.unbounded_shl(2), 0b10100);
assert_eq!(42_i128.unbounded_shl(128), 0);
assert_eq!(42_i128.unbounded_shl(1).unbounded_shl(127), 0);
assert_eq!((-13_i128).unbounded_shl(128), 0);
assert_eq!((-13_i128).unbounded_shl(1).unbounded_shl(127), 0);

pub const fn shl_exact(self, rhs: u32) -> Option<i128>

🔬This is a nightly-only experimental API. (exact_bitshifts #144336)

Exact shift left. Computes self << rhs as long as it can be reversed losslessly.

Returns None if any bits that would be shifted out differ from the resulting sign bit or if rhs >= i128::BITS. Otherwise, returns Some(self << rhs).

Examples

#![feature(exact_bitshifts)]

assert_eq!(0x1i128.shl_exact(4), Some(0x10));
assert_eq!(0x1i128.shl_exact(i128::BITS - 2), Some(1 << i128::BITS - 2));
assert_eq!(0x1i128.shl_exact(i128::BITS - 1), None);
assert_eq!((-0x2i128).shl_exact(i128::BITS - 2), Some(-0x2 << i128::BITS - 2));
assert_eq!((-0x2i128).shl_exact(i128::BITS - 1), None);

pub const unsafe fn unchecked_shl_exact(self, rhs: u32) -> i128

🔬This is a nightly-only experimental API. (exact_bitshifts #144336)

Unchecked exact shift left. Computes self << rhs, assuming the operation can be losslessly reversed and rhs cannot be larger than i128::BITS.

Safety

This results in undefined behavior when rhs >= self.leading_zeros() && rhs >= self.leading_ones() i.e. when i128::shl_exact would return None.

pub const fn checked_shr(self, rhs: u32) -> Option<i128>

Checked shift right. Computes self >> rhs, returning None if rhs is larger than or equal to the number of bits in self.

Examples

assert_eq!(0x10i128.checked_shr(4), Some(0x1));
assert_eq!(0x10i128.checked_shr(128), None);

pub const fn strict_shr(self, rhs: u32) -> i128

Strict shift right. Computes self >> rhs, panicking if rhs is larger than or equal to the number of bits in self.

Panics

Overflow behavior

This function will always panic on overflow, regardless of whether overflow checks are enabled.

Examples

assert_eq!(0x10i128.strict_shr(4), 0x1);

The following panics because of overflow:

let _ = 0x10i128.strict_shr(128);

pub const unsafe fn unchecked_shr(self, rhs: u32) -> i128

Unchecked shift right. Computes self >> rhs, assuming that rhs is less than the number of bits in self.

Safety

This results in undefined behavior if rhs is larger than or equal to the number of bits in self, i.e. when checked_shr would return None.

pub const fn unbounded_shr(self, rhs: u32) -> i128

Unbounded shift right. Computes self >> rhs, without bounding the value of rhs.

If rhs is larger or equal to the number of bits in self, the entire value is shifted out, which yields 0 for a positive number, and -1 for a negative number.

Examples

assert_eq!(0x10_i128.unbounded_shr(4), 0x1);
assert_eq!(0x10_i128.unbounded_shr(129), 0);
assert_eq!(i128::MIN.unbounded_shr(129), -1);
assert_eq!(0b1010_i128.unbounded_shr(0), 0b1010);
assert_eq!(0b1010_i128.unbounded_shr(1), 0b101);
assert_eq!(0b1010_i128.unbounded_shr(2), 0b10);
assert_eq!(42_i128.unbounded_shr(128), 0);
assert_eq!(42_i128.unbounded_shr(1).unbounded_shr(127), 0);
assert_eq!((-13_i128).unbounded_shr(128), -1);
assert_eq!((-13_i128).unbounded_shr(1).unbounded_shr(127), -1);

pub const fn shr_exact(self, rhs: u32) -> Option<i128>

🔬This is a nightly-only experimental API. (exact_bitshifts #144336)

Exact shift right. Computes self >> rhs as long as it can be reversed losslessly.

Returns None if any non-zero bits would be shifted out or if rhs >= i128::BITS. Otherwise, returns Some(self >> rhs).

Examples

#![feature(exact_bitshifts)]

assert_eq!(0x10i128.shr_exact(4), Some(0x1));
assert_eq!(0x10i128.shr_exact(5), None);

pub const unsafe fn unchecked_shr_exact(self, rhs: u32) -> i128

🔬This is a nightly-only experimental API. (exact_bitshifts #144336)

Unchecked exact shift right. Computes self >> rhs, assuming the operation can be losslessly reversed and rhs cannot be larger than i128::BITS.

Safety

This results in undefined behavior when rhs > self.trailing_zeros() || rhs >= i128::BITS i.e. when i128::shr_exact would return None.

pub const fn checked_abs(self) -> Option<i128>

Checked absolute value. Computes self.abs(), returning None if self == MIN.

Examples

assert_eq!((-5i128).checked_abs(), Some(5));
assert_eq!(i128::MIN.checked_abs(), None);

pub const fn strict_abs(self) -> i128

Strict absolute value. Computes self.abs(), panicking if self == MIN.

Panics

Overflow behavior

This function will always panic on overflow, regardless of whether overflow checks are enabled.

Examples

assert_eq!((-5i128).strict_abs(), 5);

The following panics because of overflow:

let _ = i128::MIN.strict_abs();

pub const fn checked_pow(self, exp: u32) -> Option<i128>

Checked exponentiation. Computes self.pow(exp), returning None if overflow occurred.

Examples

assert_eq!(8i128.checked_pow(2), Some(64));
assert_eq!(0_i128.checked_pow(0), Some(1));
assert_eq!(i128::MAX.checked_pow(2), None);

pub const fn strict_pow(self, exp: u32) -> i128

Strict exponentiation. Computes self.pow(exp), panicking if overflow occurred.

Panics

Overflow behavior

This function will always panic on overflow, regardless of whether overflow checks are enabled.

Examples

assert_eq!(8i128.strict_pow(2), 64);
assert_eq!(0_i128.strict_pow(0), 1);

The following panics because of overflow:

let _ = i128::MAX.strict_pow(2);

pub const fn checked_isqrt(self) -> Option<i128>

Returns the integer square root of the number, rounded down.

This function returns the principal (non-negative) square root. For a given number n, although both x and -x satisfy x² = n, this function always returns the non-negative value.

Returns None if self is negative.

Examples

assert_eq!(10i128.checked_isqrt(), Some(3));

pub const fn saturating_add(self, rhs: i128) -> i128

Saturating integer addition. Computes self + rhs, saturating at the numeric bounds instead of overflowing.

Examples

assert_eq!(100i128.saturating_add(1), 101);
assert_eq!(i128::MAX.saturating_add(100), i128::MAX);
assert_eq!(i128::MIN.saturating_add(-1), i128::MIN);

pub const fn saturating_add_unsigned(self, rhs: u128) -> i128

Saturating addition with an unsigned integer. Computes self + rhs, saturating at the numeric bounds instead of overflowing.

Examples

assert_eq!(1i128.saturating_add_unsigned(2), 3);
assert_eq!(i128::MAX.saturating_add_unsigned(100), i128::MAX);

pub const fn saturating_sub(self, rhs: i128) -> i128

Saturating integer subtraction. Computes self - rhs, saturating at the numeric bounds instead of overflowing.

Examples

assert_eq!(100i128.saturating_sub(127), -27);
assert_eq!(i128::MIN.saturating_sub(100), i128::MIN);
assert_eq!(i128::MAX.saturating_sub(-1), i128::MAX);

pub const fn saturating_sub_unsigned(self, rhs: u128) -> i128

Saturating subtraction with an unsigned integer. Computes self - rhs, saturating at the numeric bounds instead of overflowing.

Examples

assert_eq!(100i128.saturating_sub_unsigned(