Primitive Type u128

1.26.0

Expand description

The 128-bit unsigned integer type.

Please see the documentation for i128 for information on ABI compatibility.

Implementations§

Source §

let n = 0b01001100u128;
assert_eq!(n.count_ones(), 3);

let max = u128::MAX;
assert_eq!(max.count_ones(), 128);

let zero = 0u128;
assert_eq!(zero.count_ones(), 0);

1.0.0 (const: 1.32.0) · Source

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

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.

§Examples

let n = 0x1Au128;

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

1.0.0 (const: 1.32.0) · Source

pub const fn to_le(self) -> Self

Converts self to little endian from the target’s endianness.

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

§Examples

let n = 0x1Au128;

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

1.0.0 (const: 1.47.0) · Source

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

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

§Examples

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

1.79.0 (const: 1.79.0) · Source

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

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 > u128::MAX or self + rhs < u128::MIN, i.e. when checked_add would return None.

1.0.0 (const: 1.47.0) · Source

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

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

§Examples

assert_eq!(1u128.checked_sub(1), Some(0));
assert_eq!(0u128.checked_sub(1), None);

1.79.0 (const: 1.79.0) · Source

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

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.

If you find yourself writing code like this:

if foo >= bar {
    // SAFETY: just checked it will not overflow
    let diff = unsafe { foo.unchecked_sub(bar) };
    // ... use diff ...
}

Consider changing it to

if let Some(diff) = foo.checked_sub(bar) {
    // ... use diff ...
}

As that does exactly the same thing – including telling the optimizer that the subtraction cannot overflow – but avoids needing unsafe.

§Safety

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

1.0.0 (const: 1.47.0) · Source

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

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

§Examples

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

1.0.0 (const: 1.32.0) · Source

pub const fn wrapping_sub(self, rhs: Self) -> Self

Wrapping (modular) subtraction. Computes self - rhs, wrapping around at the boundary of the type.

§Examples

assert_eq!(100u128.wrapping_sub(100), 0);
assert_eq!(100u128.wrapping_sub(u128::MAX), 101);

1.7.0 (const: 1.32.0) · Source

pub const fn overflowing_add(self, rhs: Self) -> (Self, bool)

Calculates self + rhs.

Returns a tuple of the addition along with a boolean indicating whether an arithmetic overflow would occur. If an overflow would have occurred then the wrapped value is returned.

§Examples

assert_eq!(5u128.overflowing_add(2), (7, false));
assert_eq!(u128::MAX.overflowing_add(1), (0, true));

1.7.0 (const: 1.32.0) · Source

pub const fn overflowing_sub(self, rhs: Self) -> (Self, bool)

Calculates self - rhs.

Returns a tuple of the subtraction along with a boolean indicating whether an arithmetic overflow would occur. If an overflow would have occurred then the wrapped value is returned.

§Examples

assert_eq!(5u128.overflowing_sub(2), (3, false));
assert_eq!(0u128.overflowing_sub(1), (u128::MAX, true));

1.60.0 (const: 1.60.0) · Source

pub const fn abs_diff(self, other: Self) -> Self

Computes the absolute difference between self and other.

§Examples

assert_eq!(100u128.abs_diff(80), 20u128);
assert_eq!(100u128.abs_diff(110), 10u128);

1.7.0 (const: 1.32.0) · Source

pub const fn overflowing_mul(self, rhs: Self) -> (Self, bool)

Calculates the multiplication of self and rhs.

Returns a tuple of the multiplication along with a boolean indicating whether an arithmetic overflow would occur. If an overflow would have occurred then the wrapped value is returned.

If you want the value of the overflow, rather than just whether an overflow occurred, see [Self::carrying_mul].

§Examples

Please note that this example is shared among integer types, which is why u32 is used.

assert_eq!(5u32.overflowing_mul(2), (10, false));
assert_eq!(1_000_000_000u32.overflowing_mul(10), (1410065408, true));

1.73.0 (const: 1.73.0) · Source

pub const fn div_ceil(self, rhs: Self) -> Self

Calculates the quotient of self and rhs, rounding the result towards positive infinity.

§Panics

This function will panic if rhs is zero.

§Examples

assert_eq!(7_u128.div_ceil(4), 2);

1.87.0 (const: 1.87.0) · Source

pub const fn is_multiple_of(self, rhs: Self) -> bool

Returns true if self is an integer multiple of rhs, and false otherwise.

This function is equivalent to self % rhs == 0, except that it will not panic for rhs == 0. Instead, 0.is_multiple_of(0) == true, and for any non-zero n, n.is_multiple_of(0) == false.

§Examples

assert!(6_u128.is_multiple_of(2));
assert!(!5_u128.is_multiple_of(2));

assert!(0_u128.is_multiple_of(0));
assert!(!6_u128.is_multiple_of(0));

1.0.0 (const: 1.32.0) · Source

pub const fn is_power_of_two(self) -> bool

Returns true if and only if self == 2^k for some unsigned integer k.

§Examples

assert!(16u128.is_power_of_two());
assert!(!10u128.is_power_of_two());

1.32.0 (const: 1.44.0) · Source

pub const fn to_le_bytes(self) -> [u8; 16]

Returns the memory representation of this integer as a byte array in little-endian byte order.

§Examples

let bytes = 0x12345678901234567890123456789012u128.to_le_bytes();
assert_eq!(bytes, [0x12, 0x90, 0x78, 0x56, 0x34, 0x12, 0x90, 0x78, 0x56, 0x34, 0x12, 0x90, 0x78, 0x56, 0x34, 0x12]);

1.32.0 (const: 1.44.0) · Source

pub const fn to_ne_bytes(self) -> [u8; 16]

Returns the memory representation of this integer as a byte array in native byte order.

As the target platform’s native endianness is used, portable code should use to_be_bytes or to_le_bytes, as appropriate, instead.

§Examples

let bytes = 0x12345678901234567890123456789012u128.to_ne_bytes();
assert_eq!(
    bytes,
    if cfg!(target_endian = "big") {
        [0x12, 0x34, 0x56, 0x78, 0x90, 0x12, 0x34, 0x56, 0x78, 0x90, 0x12, 0x34, 0x56, 0x78, 0x90, 0x12]
    } else {
        [0x12, 0x90, 0x78, 0x56, 0x34, 0x12, 0x90, 0x78, 0x56, 0x34, 0x12, 0x90, 0x78, 0x56, 0x34, 0x12]
    }
);

1.32.0 (const: 1.44.0) · Source

pub const fn from_le_bytes(bytes: [u8; 16]) -> Self

Creates a native endian integer value from its representation as a byte array in little endian.

§Examples

let value = u128::from_le_bytes([0x12, 0x90, 0x78, 0x56, 0x34, 0x12, 0x90, 0x78, 0x56, 0x34, 0x12, 0x90, 0x78, 0x56, 0x34, 0x12]);
assert_eq!(value, 0x12345678901234567890123456789012);

When starting from a slice rather than an array, fallible conversion APIs can be used:

fn read_le_u128(input: &mut &[u8]) -> u128 {
    let (int_bytes, rest) = input.split_at(size_of::<u128>());
    *input = rest;
    u128::from_le_bytes(int_bytes.try_into().unwrap())
}

1.32.0 (const: 1.44.0) · Source

pub const fn from_ne_bytes(bytes: [u8; 16]) -> Self

Creates a native endian integer value from its memory representation as a byte array in native endianness.

As the target platform’s native endianness is used, portable code likely wants to use from_be_bytes or from_le_bytes, as appropriate instead.

§Examples

let value = u128::from_ne_bytes(if cfg!(target_endian = "big") {
    [0x12, 0x34, 0x56, 0x78, 0x90, 0x12, 0x34, 0x56, 0x78, 0x90, 0x12, 0x34, 0x56, 0x78, 0x90, 0x12]
} else {
    [0x12, 0x90, 0x78, 0x56, 0x34, 0x12, 0x90, 0x78, 0x56, 0x34, 0x12, 0x90, 0x78, 0x56, 0x34, 0x12]
});
assert_eq!(value, 0x12345678901234567890123456789012);

When starting from a slice rather than an array, fallible conversion APIs can be used:

fn read_ne_u128(input: &mut &[u8]) -> u128 {
    let (int_bytes, rest) = input.split_at(size_of::<u128>());
    *input = rest;
    u128::from_ne_bytes(int_bytes.try_into().unwrap())
}

Performs the unary ! operation. Read more

1.0.0 (const: unstable) · Source§

impl Not for u128

Source §

type Output = u128

The resulting type after applying the ! operator.

Source §

fn not(self) -> u128

Performs the unary ! operation. Read more

1.0.0 (const: unstable) · Source§

impl Ord for u128

Source §

fn cmp(&self, other: &Self) -> Ordering

This method returns an Ordering between self and other. Read more

1.21.0 · Source§

fn max(self, other: Self) -> Self
where Self: Sized,

Compares and returns the maximum of two values. Read more

1.21.0 · Source§

fn min(self, other: Self) -> Self
where Self: Sized,

Compares and returns the minimum of two values. Read more

1.50.0 · Source§

fn clamp(self, min: Self, max: Self) -> Self
where Self: Sized,

Restrict a value to a certain interval. Read more

1.0.0 (const: unstable) · Source§

impl PartialEq for u128

Source §

fn eq(&self, other: &Self) -> bool

Tests for self and other values to be equal, and is used by ==.

Source §

fn ne(&self, other: &Self) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

1.0.0 (const: unstable) · Source§

1.0.0 (const: unstable) · Source§

impl Eq for u128

Source §

impl StructuralPartialEq for u128

Auto Trait Implementations§

§

impl Unpin for u128

Blanket Implementations§

Source §

impl<T> From<T> for T

Source §

fn from(t: T) -> T

Returns the argument unchanged.

fn try_from(value: U) -> Result<T, <T as TryFrom>::Error>

Performs the conversion.

Source §

impl<T, U> TryInto for T
where U: TryFrom<T>,

Source §

type Error = >::Error

The type returned in the event of a conversion error.

Source §

fn try_into(self) -> Result<U, >::Error>

Performs the conversion.

Primitive Type u128 Copy item path

Implementations§

impl u128

pub const MIN: Self = 0u128

§Examples

pub const MAX: Self = 340_282_366_920_938_463_463_374_607_431_768_211_455u128

§Examples

pub const fn count_ones(self) -> u32

§Examples

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

§Examples

pub const fn to_le(self) -> Self

§Examples

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

§Examples

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

§Safety

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

§Examples

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

§Safety

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

§Examples

pub const fn wrapping_sub(self, rhs: Self) -> Self

§Examples

pub const fn overflowing_add(self, rhs: Self) -> (Self, bool)

§Examples

pub const fn overflowing_sub(self, rhs: Self) -> (Self, bool)

§Examples

pub const fn abs_diff(self, other: Self) -> Self

§Examples

pub const fn overflowing_mul(self, rhs: Self) -> (Self, bool)

§Examples

pub const fn div_ceil(self, rhs: Self) -> Self

§Panics

§Examples

pub const fn is_multiple_of(self, rhs: Self) -> bool

§Examples

pub const fn is_power_of_two(self) -> bool

§Examples

pub const fn to_le_bytes(self) -> [u8; 16]

§Examples

pub const fn to_ne_bytes(self) -> [u8; 16]

§Examples

pub const fn from_le_bytes(bytes: [u8; 16]) -> Self

§Examples

pub const fn from_ne_bytes(bytes: [u8; 16]) -> Self

§Examples

Trait Implementations§

impl Add<&u128> for &u128

type Output = <u128 as Add>::Output

fn add(self, other: &u128) -> <u128 as Add<u128>>::Output

impl Add<&u128> for u128

type Output = <u128 as Add>::Output

fn add(self, other: &u128) -> <u128 as Add<u128>>::Output

impl Add<u128> for &u128

type Output = <u128 as Add>::Output

fn add(self, other: u128) -> <u128 as Add<u128>>::Output

impl Add for u128

type Output = u128

fn add(self, other: u128) -> u128

impl AddAssign<&u128> for u128

fn add_assign(&mut self, other: &u128)

impl AddAssign for u128

fn add_assign(&mut self, other: u128)

impl BitAnd<&u128> for &u128

type Output = <u128 as BitAnd>::Output

fn bitand(self, other: &u128) -> <u128 as BitAnd<u128>>::Output

impl BitAnd<&u128> for u128

type Output = <u128 as BitAnd>::Output

fn bitand(self, other: &u128) -> <u128 as BitAnd<u128>>::Output

impl BitAnd<u128> for &u128

type Output = <u128 as BitAnd>::Output

fn bitand(self, other: u128) -> <u128 as BitAnd<u128>>::Output

impl BitAnd for u128

type Output = u128

fn bitand(self, rhs: u128) -> u128

impl BitAndAssign<&u128> for u128

fn bitand_assign(&mut self, other: &u128)

impl BitAndAssign for u128

Primitive Type u128

fn clone_from(&mut self, source: &Self)
where Self:,