Struct revm::precompile::primitives::alloy_primitives::ruint::Uint

source ·

pub struct Uint<const BITS: usize, const LIMBS: usize> { /* private fields */ }

Expand description

The ring of numbers modulo $2^{\mathtt{BITS}}$.

Uint implements nearly all traits and methods from the std unsigned integer types, including most nightly only ones.

§Notable differences from `std` uint types.

The operators +, -, *, etc. using wrapping math by default. The std operators panic on overflow in debug, and are undefined in release, see reference.
The Uint::checked_shl, Uint::overflowing_shl, etc return overflow when non-zero bits are shifted out. In std they return overflow when the shift amount is greater than the bit size.
Some methods like u64::div_euclid and u64::rem_euclid are left out because they are meaningless or redundant for unsigned integers. Std has them for compatibility with their signed integers.
Many functions that are const in std are not in Uint.
Uint::to_le_bytes and Uint::to_be_bytes require the output size to be provided as a const-generic argument. They will runtime panic if the provided size is incorrect.
Uint::widening_mul takes as argument an Uint of arbitrary size and returns a result that is sized to fit the product without overflow (i.e. the sum of the bit sizes of self and the argument). The std version requires same-sized arguments and returns a pair of lower and higher bits.

Implementations§

source §

impl<const BITS: usize, const LIMBS: usize> Uint<BITS, LIMBS>

source

pub fn abs_diff(self, other: Uint<BITS, LIMBS>) -> Uint<BITS, LIMBS>

Computes the absolute difference between self and other.

Returns $\left\vert \mathtt{self} - \mathtt{other} \right\vert$.

source

pub const fn checked_add( self, rhs: Uint<BITS, LIMBS> ) -> Option<Uint<BITS, LIMBS>>

Computes self + rhs, returning None if overflow occurred.

source

pub const fn checked_neg(self) -> Option<Uint<BITS, LIMBS>>

Computes -self, returning None unless self == 0.

source

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

source

pub const fn saturating_sub(self, rhs: Uint<BITS, LIMBS>) -> Uint<BITS, LIMBS>

Computes self - rhs, saturating at the numeric bounds instead of overflowing

source

pub const fn wrapping_add(self, rhs: Uint<BITS, LIMBS>) -> Uint<BITS, LIMBS>

Computes self + rhs, wrapping around at the boundary of the type.

source

pub const fn wrapping_neg(self) -> Uint<BITS, LIMBS>

Computes -self, wrapping around at the boundary of the type.

source

pub const fn wrapping_sub(self, rhs: Uint<BITS, LIMBS>) -> Uint<BITS, LIMBS>

Computes self - rhs, wrapping around at the boundary of the type.

source §

impl<const BITS: usize, const LIMBS: usize> Uint<BITS, LIMBS>

source

pub fn to_base_le(&self, base: u64) -> impl Iterator<Item = u64>

Returns an iterator over the base base digits of the number in little-endian order.

Pro tip: instead of setting base = 10, set it to the highest power of 10 that still fits u64. This way much fewer iterations are required to extract all the digits.

§Panics

Panics if the base is less than 2.

source

pub fn to_base_be(&self, base: u64) -> impl Iterator<Item = u64>

Returns an iterator over the base base digits of the number in big-endian order.

pub fn set_bit(&mut self, index: usize, value: bool)

Sets a specific bit to a value.

source

pub const fn byte(&self, index: usize) -> u8

Returns a specific byte. The byte at index 0 is the least significant byte (little endian).

§Panics

Panics if index exceeds the byte width of the number.

§Examples

let x = uint!(0x1234567890_U64);
let bytes = [
    x.byte(0), // 0x90
    x.byte(1), // 0x78
    x.byte(2), // 0x56
    x.byte(3), // 0x34
    x.byte(4), // 0x12
    x.byte(5), // 0x00
    x.byte(6), // 0x00
    x.byte(7), // 0x00
];
assert_eq!(bytes, x.to_le_bytes());

Panics if out of range.

let x = uint!(0x1234567890_U64);
let _ = x.byte(8);

Returns $\mathtt{self} ⋅ 2^{\mathtt{rhs}}$ or None if the result would $≥ 2^{\mathtt{BITS}}$. That is, it returns None if the bits shifted out would be non-zero.

Note: This differs from u64::checked_shl which returns None if the shift is larger than BITS (which is IMHO not very useful).

source

Checked right shift by rhs bits.

$$ \frac{\mathtt{self}}{2^{\mathtt{rhs}}} $$

Returns the above or None if the division is not exact. This is the same as

Note: This differs from u64::checked_shr which returns None if the shift is larger than BITS (which is IMHO not very useful).

source

pub fn overflowing_shr(self, rhs: usize) -> (Uint<BITS, LIMBS>, bool)

Right shift by rhs bits with underflow detection.

$$ \floor{\frac{\mathtt{self}}{2^{\mathtt{rhs}}}} $$

Returns the above and false if the division was exact, and true if it was rounded down. This is the same as non-zero bits being shifted out.

Note: This differs from u64::overflowing_shr which returns true if the shift is larger than BITS (which is IMHO not very useful).

source

pub fn wrapping_shr(self, rhs: usize) -> Uint<BITS, LIMBS>

Right shift by rhs bits.

$$ \mathtt{wrapping\_shr}(\mathtt{self}, \mathtt{rhs}) = \floor{\frac{\mathtt{self}}{2^{\mathtt{rhs}}}} $$

Note: This differs from u64::wrapping_shr which first reduces rhs by BITS (which is IMHO not very useful).

source

pub fn arithmetic_shr(self, rhs: usize) -> Uint<BITS, LIMBS>

Arithmetic shift right by rhs bits.

source

pub fn rotate_left(self, rhs: usize) -> Uint<BITS, LIMBS>

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

Access the underlying store as a mutable little-endian slice of bytes.

Only available on litte-endian targets.

Converts the Uint to a little-endian byte array of size exactly Self::BYTES.

§Panics

Panics if the generic parameter BYTES is not exactly Self::BYTES. Ideally this would be a compile time error, but this is blocked by Rust issue #60551.

source

pub fn to_le_bytes_vec(&self) -> Vec<u8> ⓘ

Converts the Uint to a little-endian byte vector of size exactly Self::BYTES.

This method is useful when Self::to_le_bytes can not be used because byte size is not known compile time.

source

pub fn to_le_bytes_trimmed_vec(&self) -> Vec<u8> ⓘ

Converts the Uint to a little-endian byte vector with trailing zeros bytes removed.

source

pub const fn to_be_bytes<const BYTES: usize>(&self) -> [u8; BYTES]

Converts the Uint to a big-endian byte array of size exactly Self::BYTES.

§Panics

Panics if the generic parameter BYTES is not exactly Self::BYTES. Ideally this would be a compile time error, but this is blocked by Rust issue #60551.

source

pub fn to_be_bytes_vec(&self) -> Vec<u8> ⓘ

Converts the Uint to a big-endian byte vector of size exactly Self::BYTES.

This method is useful when Self::to_be_bytes can not be used because byte size is not known compile time.

source

pub fn to_be_bytes_trimmed_vec(&self) -> Vec<u8> ⓘ

Converts the Uint to a big-endian byte vector with leading zeros bytes removed.

source

pub const fn from_be_bytes<const BYTES: usize>( bytes: [u8; BYTES] ) -> Uint<BITS, LIMBS>

Converts a big-endian byte array of size exactly Self::BYTES to Uint.

§Panics

Panics if the generic parameter BYTES is not exactly Self::BYTES. Ideally this would be a compile time error, but this is blocked by Rust issue #60551.

Panics if the value is too large for the bit-size of the Uint.

source

pub const fn from_be_slice(bytes: &[u8]) -> Uint<BITS, LIMBS>

Creates a new integer from a big endian slice of bytes.

pub const fn from_le_slice(bytes: &[u8]) -> Uint<BITS, LIMBS>

Creates a new integer from a little endian slice of bytes.

source

pub fn from<T>(value: T) -> Uint<BITS, LIMBS>
where Uint<BITS, LIMBS>: UintTryFrom<T>,

Construct a new Uint from the value.

§Panics

Panics if the conversion fails, for example if the value is too large for the bit-size of the Uint. The panic will be attributed to the call site.

§Examples

assert_eq!(U8::from(142_u16), 142_U8);
assert_eq!(U64::from(0x7014b4c2d1f2_U256), 0x7014b4c2d1f2_U64);
assert_eq!(U64::from(3.145), 3_U64);

source

pub fn saturating_from<T>(value: T) -> Uint<BITS, LIMBS>
where Uint<BITS, LIMBS>: UintTryFrom<T>,

Construct a new Uint from the value saturating the value to the minimum or maximum value of the Uint.

If the value is not a number (like f64::NAN), then the result is set zero.

§Examples

assert_eq!(U8::saturating_from(300_u16), 255_U8);
assert_eq!(U8::saturating_from(-10_i16), 0_U8);
assert_eq!(U32::saturating_from(0x7014b4c2d1f2_U256), U32::MAX);

source

pub fn wrapping_from<T>(value: T) -> Uint<BITS, LIMBS>
where Uint<BITS, LIMBS>: UintTryFrom<T>,

Construct a new Uint from the value saturating the value to the minimum or maximum value of the Uint.

If the value is not a number (like f64::NAN), then the result is set zero.

§Examples

assert_eq!(U8::wrapping_from(300_u16), 44_U8);
assert_eq!(U8::wrapping_from(-10_i16), 246_U8);
assert_eq!(U32::wrapping_from(0x7014b4c2d1f2_U256), 0xb4c2d1f2_U32);

source

pub fn to<T>(&self) -> T
where Uint<BITS, LIMBS>: UintTryTo<T>, T: Debug,

§Panics

Panics if the conversion fails, for example if the value is too large for the bit-size of the target type.

§Examples

assert_eq!(300_U12.to::<i16>(), 300_i16);
assert_eq!(300_U12.to::<U256>(), 300_U256);

source

pub fn wrapping_to<T>(&self) -> T
where Uint<BITS, LIMBS>: UintTryTo<T>,

§Examples

assert_eq!(300_U12.wrapping_to::<i8>(), 44_i8);
assert_eq!(255_U32.wrapping_to::<i8>(), -1_i8);
assert_eq!(0x1337cafec0d3_U256.wrapping_to::<U32>(), 0xcafec0d3_U32);

source

pub fn saturating_to<T>(&self) -> T
where Uint<BITS, LIMBS>: UintTryTo<T>,

§Examples

assert_eq!(300_U12.saturating_to::<i16>(), 300_i16);
assert_eq!(255_U32.saturating_to::<i8>(), 127);
assert_eq!(0x1337cafec0d3_U256.saturating_to::<U32>(), U32::MAX);

source §

impl<const BITS: usize, const LIMBS: usize> Uint<BITS, LIMBS>

source

pub fn gcd(self, other: Uint<BITS, LIMBS>) -> Uint<BITS, LIMBS>

Compute the greatest common divisor of two Uints.

§Examples

assert_eq!(0_U128.gcd(0_U128), 0_U128);

source

pub fn lcm(self, other: Uint<BITS, LIMBS>) -> Option<Uint<BITS, LIMBS>>

Compute the least common multiple of two Uints or None if the result would be too large.

source

pub fn gcd_extended( self, other: Uint<BITS, LIMBS> ) -> (Uint<BITS, LIMBS>, Uint<BITS, LIMBS>, Uint<BITS, LIMBS>, bool)

⚠️ Compute the greatest common divisor and the Bézout coefficients.

Warning. This is API is unstable and may change in a minor release.

Returns $(\mathtt{gcd}, \mathtt{x}, \mathtt{y}, \mathtt{sign})$ such that

$$ \gcd(\mathtt{self}, \mathtt{other}) = \mathtt{gcd} = \begin{cases} \mathtt{self} · \mathtt{x} - \mathtt{other} . \mathtt{y} & \mathtt{sign} \\ \mathtt{other} · \mathtt{y} - \mathtt{self} · \mathtt{x} & ¬\mathtt{sign} \end{cases} $$

Note that the intermediate products may overflow, even though the result after subtraction will fit in the bit size of the Uint.

Returns the base 2 logarithm of the number, rounded down.

This is equivalent to the index of the highest set bit.

pub fn approx_log2(self) -> f64

Double precision binary logarithm.

§Examples

assert_eq!(0_U64.approx_log2(), f64::NEG_INFINITY);
assert_eq!(1_U64.approx_log2(), 0.0);
assert_eq!(2_U64.approx_log2(), 1.0);
assert_eq!(U64::MAX.approx_log2(), 64.0);

pub fn mul_mod( self, rhs: Uint<BITS, LIMBS>, modulus: Uint<BITS, LIMBS> ) -> Uint<BITS, LIMBS>

Compute $\mod{\mathtt{self} ⋅ \mathtt{rhs}}_{\mathtt{modulus}}$.

Returns zero if the modulus is zero.

See mul_redc for a faster variant at the cost of some pre-computation.

source

pub fn pow_mod( self, exp: Uint<BITS, LIMBS>, modulus: Uint<BITS, LIMBS> ) -> Uint<BITS, LIMBS>

Compute $\mod{\mathtt{self}^{\mathtt{rhs}}}_{\mathtt{modulus}}$.

Returns zero if the modulus is zero.

source

pub fn inv_mod(self, modulus: Uint<BITS, LIMBS>) -> Option<Uint<BITS, LIMBS>>

Compute $\mod{\mathtt{self}^{-1}}_{\mathtt{modulus}}$.

Returns None if the inverse does not exist.

source

pub fn mul_redc( self, other: Uint<BITS, LIMBS>, modulus: Uint<BITS, LIMBS>, inv: u64 ) -> Uint<BITS, LIMBS>

Montgomery multiplication.

Computes

$$ \mod{\frac{\mathtt{self} ⋅ \mathtt{other}}{ 2^{64 · \mathtt{LIMBS}}}}_{\mathtt{modulus}} $$

This is useful because it can be computed notably faster than mul_mod. Many computations can be done by pre-multiplying values with $R = 2^{64 · \mathtt{LIMBS}}$ and then using mul_redc instead of mul_mod.

For this algorithm to work, it needs an extra parameter inv which must be set to

$$ \mathtt{inv} = \mod{\frac{-1}{\mathtt{modulus}} }_{2^{64}} $$

The inv value only exists for odd values of modulus. It can be computed using inv_ring from U64.

let inv = U64::wrapping_from(modulus).inv_ring().unwrap().wrapping_neg().to();
let prod = 5_U256.mul_redc(6_U256, modulus, inv);

§Panics

Panics if inv is not correct.

source §

impl<const BITS: usize, const LIMBS: usize> Uint<BITS, LIMBS>

pub fn overflowing_pow( self, exp: Uint<BITS, LIMBS> ) -> (Uint<BITS, LIMBS>, bool)

Raises self to the power of exp and if the result would overflow.

§Examples

assert_eq!(
    36_U64.overflowing_pow(12_U64),
    (0x41c21cb8e1000000_U64, false)
);
assert_eq!(
    36_U64.overflowing_pow(13_U64),
    (0x3f4c09ffa4000000_U64, true)
);
assert_eq!(
    36_U68.overflowing_pow(13_U68),
    (0x093f4c09ffa4000000_U68, false)
);
assert_eq!(16_U65.overflowing_pow(32_U65), (0_U65, true));

Small cases:

assert_eq!(0_U0.overflowing_pow(0_U0), (0_U0, false));
assert_eq!(0_U1.overflowing_pow(0_U1), (1_U1, false));
assert_eq!(0_U1.overflowing_pow(1_U1), (0_U1, false));
assert_eq!(1_U1.overflowing_pow(0_U1), (1_U1, false));
assert_eq!(1_U1.overflowing_pow(1_U1), (1_U1, false));

source

pub fn pow(self, exp: Uint<BITS, LIMBS>) -> Uint<BITS, LIMBS>

Raises self to the power of exp, wrapping around on overflow.

source

pub fn saturating_pow(self, exp: Uint<BITS, LIMBS>) -> Uint<BITS, LIMBS>

Raises self to the power of exp, saturating on overflow.

source

pub fn wrapping_pow(self, exp: Uint<BITS, LIMBS>) -> Uint<BITS, LIMBS>

Raises self to the power of exp, wrapping around on overflow.

source

pub fn approx_pow2(exp: f64) -> Option<Uint<BITS, LIMBS>>

Construct from double precision binary logarithm.

§Examples

assert_eq!(U64::approx_pow2(-2.0), Some(0_U64));
assert_eq!(U64::approx_pow2(-1.0), Some(1_U64));
assert_eq!(U64::approx_pow2(0.0), Some(1_U64));
assert_eq!(U64::approx_pow2(1.0), Some(2_U64));
assert_eq!(U64::approx_pow2(1.6), Some(3_U64));
assert_eq!(U64::approx_pow2(2.0), Some(4_U64));
assert_eq!(U64::approx_pow2(64.0), None);
assert_eq!(U64::approx_pow2(10.385), Some(1337_U64));

source §

impl<const BITS: usize, const LIMBS: usize> Uint<BITS, LIMBS>

source

pub fn root(self, degree: usize) -> Uint<BITS, LIMBS>

Computes the floor of the degree-th root of the number.

$$ \floor{\sqrt[\mathtt{degree}]{\mathtt{self}}} $$

§Panics

Panics if degree is zero.

§Examples

assert_eq!(0_U64.root(2), 0_U64);
assert_eq!(1_U64.root(63), 1_U64);
assert_eq!(0x0032da8b0f88575d_U63.root(64), 1_U63);
assert_eq!(0x1756800000000000_U63.root(34), 3_U63);

source §

impl<const BITS: usize, const LIMBS: usize> Uint<BITS, LIMBS>

source

pub fn is_power_of_two(self) -> bool

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

source

pub fn next_power_of_two(self) -> Uint<BITS, LIMBS>

Returns the smallest power of two greater than or equal to self.

§Panics

Panics if the value overlfows.

source

pub fn checked_next_power_of_two(self) -> Option<Uint<BITS, LIMBS>>

Returns the smallest power of two greater than or equal to self. If the next power of two is greater than the type’s maximum value, None is returned, otherwise the power of two is wrapped in Some.

§Examples

assert_eq!(0_U64.checked_next_power_of_two(), Some(1_U64));
assert_eq!(1_U64.checked_next_power_of_two(), Some(1_U64));
assert_eq!(2_U64.checked_next_power_of_two(), Some(2_U64));
assert_eq!(3_U64.checked_next_power_of_two(), Some(4_U64));
assert_eq!(U64::MAX.checked_next_power_of_two(), None);

source §

impl<const BITS: usize, const LIMBS: usize> Uint<BITS, LIMBS>

source

pub fn next_multiple_of(self, rhs: Uint<BITS, LIMBS>) -> Uint<BITS, LIMBS>

Calculates the smallest value greater than or equal to self that is a multiple of rhs.

§Panics

This function will panic if rhs is 0 or the operation results in overflow.

source

pub fn checked_next_multiple_of( self, rhs: Uint<BITS, LIMBS> ) -> Option<Uint<BITS, LIMBS>>

Calculates the smallest value greater than or equal to self that is a multiple of rhs. Returns None is rhs is zero or the operation would result in overflow.

§Examples

assert_eq!(16_U64.checked_next_multiple_of(8_U64), Some(16_U64));
assert_eq!(23_U64.checked_next_multiple_of(8_U64), Some(24_U64));
assert_eq!(1_U64.checked_next_multiple_of(0_U64), None);
assert_eq!(U64::MAX.checked_next_multiple_of(2_U64), None);
}

assert_eq!(0_U0.checked_next_multiple_of(0_U0), None);
assert_eq!(0_U1.checked_next_multiple_of(0_U1), None);
assert_eq!(0_U1.checked_next_multiple_of(1_U1), Some(0_U1));
assert_eq!(1_U1.checked_next_multiple_of(0_U1), None);
assert_eq!(1_U1.checked_next_multiple_of(1_U1), Some(1_U1));
}

source §

impl<const BITS: usize, const LIMBS: usize> Uint<BITS, LIMBS>

source

pub fn from_str_radix( src: &str, radix: u64 ) -> Result<Uint<BITS, LIMBS>, ParseError>

Parse a string into a Uint.

For bases 2 to 36, the case-agnostic alphabet 0—1, a—b is used and _ are ignored. For bases 37 to 64, the case-sensitive alphabet a—z, A—Z, 0—9, {+-}, {/,_} is used. That is, for base 64 it is compatible with all the common base64 variants.

§Errors

ParseError::InvalidDigit if the string contains a non-digit.
ParseError::InvalidRadix if the radix is larger than 64.
ParseError::BaseConvertError if Uint::from_base_be fails.

source §

Access the array of limbs.

§Safety

This function is unsafe because it allows setting a bit outside the bit size if the bit-size is not limb-aligned.

source

pub const fn into_limbs(self) -> [u64; LIMBS]

Convert to a array of limbs.

Limbs are least significant first.

pub fn checked_from_limbs_slice(slice: &[u64]) -> Option<Uint<BITS, LIMBS>>

Construct a new integer from little-endian a slice of limbs, or None if the value is too large for the Uint.

source

pub fn wrapping_from_limbs_slice(slice: &[u64]) -> Uint<BITS, LIMBS>

Construct a new Uint from a little-endian slice of limbs. Returns a potentially truncated value.

source

pub fn overflowing_from_limbs_slice(slice: &[u64]) -> (Uint<BITS, LIMBS>, bool)

Construct a new Uint from a little-endian slice of limbs. Returns a potentially truncated value and a boolean indicating whether the value was truncated.

source

pub fn saturating_from_limbs_slice(slice: &[u64]) -> Uint<BITS, LIMBS>

Construct a new Uint from a little-endian slice of limbs. Returns the maximum value if the value is too large for the Uint.

source §

fn add_assign(&mut self, rhs: Uint<BITS, LIMBS>)

Performs the += operation. Read more

source §

impl<'a, const BITS: usize, const LIMBS: usize> Arbitrary<'a> for Uint<BITS, LIMBS>

source §

fn arbitrary(u: &mut Unstructured<'a>) -> Result<Uint<BITS, LIMBS>, Error>

Generate an arbitrary value of Self from the given unstructured data. Read more

source §

fn size_hint(_depth: usize) -> (usize, Option<usize>)

Get a size hint for how many bytes out of an Unstructured this type needs to construct itself. Read more

source §

fn arbitrary_take_rest(u: Unstructured<'a>) -> Result<Self, Error>

Generate an arbitrary value of Self from the entirety of the given unstructured data. Read more

source §

impl<const BITS: usize, const LIMBS: usize> Arbitrary for Uint<BITS, LIMBS>

§

type Parameters = ()

The type of parameters that arbitrary_with accepts for configuration of the generated Strategy. Parameters must implement Default.

§

type Strategy = Map<<[u64; LIMBS] as Arbitrary>::Strategy, fn(_: [u64; LIMBS]) -> Uint<BITS, LIMBS>>

The type of Strategy used to generate values of type Self.

source §

fn arbitrary() -> <Uint<BITS, LIMBS> as Arbitrary>::Strategy

Generates a Strategy for producing arbitrary values of type the implementing type (Self). Read more

source §

fn arbitrary_with( _: <Uint<BITS, LIMBS> as Arbitrary>::Parameters ) -> <Uint<BITS, LIMBS> as Arbitrary>::Strategy

Generates a Strategy for producing arbitrary values of type the implementing type (Self). The strategy is passed the arguments given in args. Read more

source §

Performs the &= operation. Read more

source §

Performs the |= operation. Read more

source §

impl<const BITS: usize, const LIMBS: usize> Debug for Uint<BITS, LIMBS>

source §

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter. Read more

source §

impl<const BITS: usize, const LIMBS: usize> Decodable for Uint<BITS, LIMBS>

Allows a Uint to be deserialized from RLP.

See https://ethereum.org/en/developers/docs/data-structures-and-encoding/rlp/

source §

fn decode(buf: &mut &[u8]) -> Result<Uint<BITS, LIMBS>, Error>

Decodes the blob into the appropriate type. buf must be advanced past the decoded object.

source §

impl<const BITS: usize, const LIMBS: usize> Default for Uint<BITS, LIMBS>

source §

fn default() -> Uint<BITS, LIMBS>

Returns the “default value” for a type. Read more

source §

impl<'de, const BITS: usize, const LIMBS: usize> Deserialize<'de> for Uint<BITS, LIMBS>

Deserialize human readable hex strings or byte arrays into hashes. Hex strings can be upper/lower/mixed case, have an optional 0x prefix, and can be any length. They are interpreted big-endian.