Unsigned 256-bit integer operations
Module miden::core::math::u256 contains a set of procedures which can be used to perform unsigned 256-bit integer operations. These operations fall into the following categories:
- Arithmetic operations - addition, subtraction, multiplication.
- Comparison operations - equality, equality to zero.
- Bitwise operations - binary AND, OR, XOR.
A u256 value is represented as a struct with two u128 components:
pub type u256 = struct { lo: u128, hi: u128 }
When placed on the stack, a 256-bit integer is encoded using eight 32-bit limbs (elements) in little-endian limb order: the least-significant limb is on top of the stack. For example, a u256 value a with limbs a0..a7 would be positioned on the stack like so:
[a0, a1, a2, a3, a4, a5, a6, a7, ...]
where a0 is the least-significant 32-bit limb and a7 is the most significant.
The procedures in this module assume that the input values are represented using valid 32-bit limbs, but this is not checked. Using invalid inputs may produce undefined results.
Arithmetic operations
| Procedure | Description |
|---|---|
| wrapping_add | Performs addition of two unsigned 256-bit integers discarding the overflow. Stack transition: [b0..b7, a0..a7, ...] -> [c0..c7, ...]where c = (a + b) % 2^256 |
| overflowing_add | Performs addition of two unsigned 256-bit integers preserving the overflow. Stack transition: [b0..b7, a0..a7, ...] -> [overflow, c0..c7, ...]where c = (a + b) % 2^256 |
| widening_add | Performs addition of two unsigned 256-bit integers preserving the overflow with sum on top. Stack transition: [b0..b7, a0..a7, ...] -> [c0..c7, overflow, ...]where c = (a + b) % 2^256 |
| wrapping_sub | Performs subtraction of two unsigned 256-bit integers discarding the underflow. Stack transition: [b0..b7, a0..a7, ...] -> [c0..c7, ...]where c = (a - b) % 2^256 |
| overflowing_sub | Performs subtraction of two unsigned 256-bit integers preserving the underflow. Stack transition: [b0..b7, a0..a7, ...] -> [underflow, c0..c7, ...]where c = (a - b) % 2^256 |
| wrapping_mul | Performs multiplication of two unsigned 256-bit integers discarding the overflow. Stack transition: [b0..b7, a0..a7, ...] -> [c0..c7, ...]where c = (a * b) % 2^256 |
Comparison operations
| Procedure | Description |
|---|---|
| eq | Checks equality of two unsigned 256-bit integers. Stack transition: [b0..b7, a0..a7, ...] -> [c, ...]where c = 1 when a == b, and 0 otherwise. |
| eqz | Checks if an unsigned 256-bit integer equals zero. Stack transition: [a0..a7, ...] -> [c, ...]where c = 1 when a == 0, and 0 otherwise. |
Bitwise operations
| Procedure | Description |
|---|---|
| and | Performs bitwise AND of two unsigned 256-bit integers. Stack transition: [b0..b7, a0..a7, ...] -> [c0..c7, ...]where c = a AND b |
| or | Performs bitwise OR of two unsigned 256-bit integers. Stack transition: [b0..b7, a0..a7, ...] -> [c0..c7, ...]where c = a OR b |
| xor | Performs bitwise XOR of two unsigned 256-bit integers. Stack transition: [b0..b7, a0..a7, ...] -> [c0..c7, ...]where c = a XOR b |