Documentation Index
Fetch the complete documentation index at: https://voltaire.tevm.sh/llms.txt
Use this file to discover all available pages before exploring further.
Uint32
A branded type for 32-bit unsigned integers (0 to 4,294,967,295). Represented as JavaScript number with compile-time type safety.
Overview
Uint32Type provides:
- Compile-time type branding
- Range validation (0 to 2^32-1)
- Full arithmetic and bitwise operations
- Efficient
number representation (fits in JavaScript safe integer range)
Type Definition
import type { brand } from '../../../brand.js';
export type Uint32Type = number & { readonly [brand]: "Uint32" };
Range
- Minimum: 0
- Maximum: 4,294,967,295 (2^32 - 1)
- Size: 32 bits (4 bytes)
Constants
import * as Uint32 from '@voltaire/primitives/Uint32';
Uint32.MIN; // 0
Uint32.MAX; // 4294967295
Uint32.ZERO; // 0
Uint32.ONE; // 1
Uint32.SIZE; // 4 (bytes)
Construction
from
Create from number, bigint, or string:
import * as Uint32 from '@voltaire/primitives/Uint32';
const a = Uint32.from(100);
const b = Uint32.from("255");
const c = Uint32.from("0xff");
const d = Uint32.from(42n);
fromNumber
const value = Uint32.fromNumber(21000); // Gas limit
fromBigInt
const value = Uint32.fromBigInt(12345678n);
fromHex
const value = Uint32.fromHex("0xffffffff"); // MAX
fromBytes
Create from Uint8Array (big-endian, up to 4 bytes):
const bytes = new Uint8Array([0x01, 0x00, 0x00, 0x00]);
const value = Uint32.fromBytes(bytes); // 16777216
fromAbiEncoded
Create from 32-byte ABI-encoded data:
const encoded = new Uint8Array(32);
encoded[31] = 100;
const value = Uint32.fromAbiEncoded(encoded); // 100
tryFrom
Safe construction that returns undefined on invalid input:
const valid = Uint32.tryFrom(100); // Uint32Type
const invalid = Uint32.tryFrom(-1); // undefined
const tooBig = Uint32.tryFrom(2**33); // undefined
Conversion
toNumber
const num = Uint32.toNumber(Uint32.from(100)); // 100
toBigInt
const bigint = Uint32.toBigInt(Uint32.from(100)); // 100n
toHex
const hex = Uint32.toHex(Uint32.from(255)); // "0xff"
toBytes
const bytes = Uint32.toBytes(Uint32.from(256)); // Uint8Array
toAbiEncoded
const encoded = Uint32.toAbiEncoded(Uint32.from(100)); // 32-byte Uint8Array
toString
const str = Uint32.toString(Uint32.from(255)); // "255"
Arithmetic
plus
const sum = Uint32.plus(Uint32.from(100), Uint32.from(50)); // 150
// Throws on overflow
minus
const diff = Uint32.minus(Uint32.from(100), Uint32.from(50)); // 50
// Throws on underflow
times
const product = Uint32.times(Uint32.from(1000), Uint32.from(1000)); // 1000000
// Throws on overflow
dividedBy
const quotient = Uint32.dividedBy(Uint32.from(100), Uint32.from(7)); // 14
modulo
const remainder = Uint32.modulo(Uint32.from(100), Uint32.from(7)); // 2
toPower
const result = Uint32.toPower(Uint32.from(2), Uint32.from(10)); // 1024
Comparison
equals
Uint32.equals(Uint32.from(100), Uint32.from(100)); // true
lessThan / greaterThan
Uint32.lessThan(Uint32.from(50), Uint32.from(100)); // true
Uint32.greaterThan(Uint32.from(100), Uint32.from(50)); // true
isZero
Uint32.isZero(Uint32.from(0)); // true
minimum / maximum
const min = Uint32.minimum(Uint32.from(100), Uint32.from(50)); // 50
const max = Uint32.maximum(Uint32.from(100), Uint32.from(50)); // 100
Bitwise Operations
bitwiseAnd / bitwiseOr / bitwiseXor
const and = Uint32.bitwiseAnd(Uint32.from(0xff00), Uint32.from(0x0ff0)); // 0x0f00
const or = Uint32.bitwiseOr(Uint32.from(0xff00), Uint32.from(0x00ff)); // 0xffff
const xor = Uint32.bitwiseXor(Uint32.from(0xff00), Uint32.from(0xf0f0)); // 0x0ff0
bitwiseNot
const not = Uint32.bitwiseNot(Uint32.from(0)); // 4294967295 (MAX)
shiftLeft / shiftRight
const left = Uint32.shiftLeft(Uint32.from(1), 8); // 256
const right = Uint32.shiftRight(Uint32.from(256), 4); // 16
Bit Analysis
bitLength
Uint32.bitLength(Uint32.from(0)); // 0
Uint32.bitLength(Uint32.from(255)); // 8
Uint32.bitLength(Uint32.from(256)); // 9
leadingZeros
Uint32.leadingZeros(Uint32.from(1)); // 31
Uint32.leadingZeros(Uint32.from(256)); // 23
popCount
Uint32.popCount(Uint32.from(0)); // 0
Uint32.popCount(Uint32.from(255)); // 8
Uint32.popCount(Uint32.from(0b10101010)); // 4
Validation
isValid
Uint32.isValid(100); // true
Uint32.isValid(4294967295); // true
Uint32.isValid(-1); // false
Uint32.isValid(4294967296); // false
Uint32.isValid(1.5); // false
Use Cases
- Block numbers: Ethereum block numbers fit in 32 bits until ~year 2100
- Gas limits: Transaction and block gas limits
- Timestamps: Unix timestamps (valid until year 2106)
- Nonces: Transaction nonces
- Indices: Array indices, loop counters
- IP addresses: IPv4 addresses
Example: Block Number Operations
import * as Uint32 from '@voltaire/primitives/Uint32';
// Current block and confirmations
const currentBlock = Uint32.from(18500000);
const confirmations = Uint32.from(12);
// Calculate confirmed block
const confirmedBlock = Uint32.minus(currentBlock, confirmations);
console.log(Uint32.toNumber(confirmedBlock)); // 18499988
// Check if block is finalized (32+ confirmations)
const minConfirmations = Uint32.from(32);
const isFinalized = Uint32.greaterThan(confirmations, minConfirmations);
Example: Timestamp Handling
import * as Uint32 from '@voltaire/primitives/Uint32';
// Current Unix timestamp
const now = Uint32.from(Math.floor(Date.now() / 1000));
// Add 1 hour (3600 seconds)
const oneHour = Uint32.from(3600);
const future = Uint32.plus(now, oneHour);
// Check expiry
const expiry = Uint32.from(1735689600); // Jan 1, 2025
const isExpired = Uint32.greaterThan(now, expiry);
API Reference
| Category | Methods |
|---|
| Construction | from, fromNumber, fromBigInt, fromHex, fromBytes, fromAbiEncoded, tryFrom |
| Conversion | toNumber, toBigInt, toHex, toBytes, toAbiEncoded, toString, clone |
| Arithmetic | plus, minus, times, dividedBy, modulo, toPower |
| Comparison | equals, lessThan, greaterThan, isZero, minimum, maximum |
| Bitwise | bitwiseAnd, bitwiseOr, bitwiseXor, bitwiseNot, shiftLeft, shiftRight |
| Bit Analysis | bitLength, leadingZeros, popCount |
| Validation | isValid |