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.
Try it Live
Run Uint examples in the interactive playground
Uint16
A branded type for 16-bit unsigned integers (range: 0-65535) represented as JavaScript numbers with compile-time type safety.
Overview
Uint16 provides type-safe operations on 16-bit unsigned integers with:
- Compile-time type branding for type safety
- Runtime validation and overflow/underflow checking
- Zero runtime overhead (just a number internally)
- Full arithmetic, bitwise, and comparison operations
Type Definition
import type { brand } from '../../../brand.js';
export type Uint16 = number & { readonly [brand]: "Uint16" };
Range
- Minimum: 0
- Maximum: 65535
- Size: 16 bits
Constants
import * as Uint16 from '@voltaire/primitives/Uint16';
Uint16.MIN; // 0
Uint16.MAX; // 65535
Uint16.ZERO; // 0
Uint16.ONE; // 1
Uint16.SIZE; // 16
Construction
from
Create from number or string:
const a = Uint16(30000);
const b = Uint16("65535");
const c = Uint16("0xffff");
fromNumber
Create from number:
const value = Uint16(65535);
fromBigint
Create from bigint:
const value = Uint16(65535n);
fromHex
Create from hex string:
const a = Uint16("0xffff");
const b = Uint16("ffff");
fromBytes
Create from Uint8Array (2 bytes, big-endian):
const bytes = new Uint8Array([0xff, 0xff]);
const value = Uint16(bytes); // 65535
Conversion
toNumber
const num = Uint16.toNumber(Uint16(65535)); // 65535
toBigint
const bigintValue = Uint16.toBigint(Uint16(65535)); // 65535n
toHex
const hex = Uint16.toHex(Uint16(65535)); // "0xffff"
const unpadded = Uint16.toHex(Uint16(15), false); // "0xf"
toBytes
const bytes = Uint16.toBytes(Uint16(65535)); // Uint8Array([255, 255])
toString
const str = Uint16.toString(Uint16(65535)); // "65535"
Arithmetic
All arithmetic operations validate that results stay within valid range.
plus
const sum = Uint16.plus(Uint16(30000), Uint16(20000)); // 50000
// Throws on overflow
minus
const diff = Uint16.minus(Uint16(30000), Uint16(20000)); // 10000
// Throws on underflow
times
const product = Uint16.times(Uint16(100), Uint16(500)); // 50000
// Throws on overflow
dividedBy
const quotient = Uint16.dividedBy(Uint16(10000), Uint16(100)); // 100
// Integer division
modulo
const remainder = Uint16.modulo(Uint16(10007), Uint16(1000)); // 7
Comparison
equals
Uint16.equals(Uint16(30000), Uint16(30000)); // true
lessThan
Uint16.lessThan(Uint16(10000), Uint16(30000)); // true
greaterThan
Uint16.greaterThan(Uint16(30000), Uint16(10000)); // true
isZero
Uint16.isZero(Uint16(0)); // true
minimum
const min = Uint16.minimum(Uint16(30000), Uint16(10000)); // 10000
maximum
const max = Uint16.maximum(Uint16(30000), Uint16(10000)); // 30000
Bitwise Operations
bitwiseAnd
const result = Uint16.bitwiseAnd(
Uint16(0b1111111100000000),
Uint16(0b1111000011110000)
);
// 0b1111000000000000 = 61440
bitwiseOr
const result = Uint16.bitwiseOr(
Uint16(0b1111111100000000),
Uint16(0b0000000011111111)
);
// 0b1111111111111111 = 65535
bitwiseXor
const result = Uint16.bitwiseXor(
Uint16(0b1111111100000000),
Uint16(0b1111000011110000)
);
// 0b0000111111110000 = 4080
bitwiseNot
const result = Uint16.bitwiseNot(Uint16(0b1111111100000000));
// 0b0000000011111111 = 255
shiftLeft
const result = Uint16.shiftLeft(Uint16(0b0000000011111111), 8);
// 0b1111111100000000 = 65280
shiftRight
const result = Uint16.shiftRight(Uint16(0b1111111100000000), 8);
// 0b0000000011111111 = 255
Bit Analysis
bitLength
Get number of bits needed to represent value:
Uint16.bitLength(Uint16(0)); // 0
Uint16.bitLength(Uint16(1)); // 1
Uint16.bitLength(Uint16(65535)); // 16
leadingZeros
Count leading zero bits:
Uint16.leadingZeros(Uint16(0)); // 16
Uint16.leadingZeros(Uint16(1)); // 15
Uint16.leadingZeros(Uint16(65535)); // 0
popCount
Count set bits:
Uint16.popCount(Uint16(0)); // 0
Uint16.popCount(Uint16(65535)); // 16
Uint16.popCount(Uint16(0b1010101010101010)); // 8
Validation
isValid
Uint16.isValid(30000); // true
Uint16.isValid(65535); // true
Uint16.isValid(65536); // false
Uint16.isValid(-1); // false
Uint16.isValid(1.5); // false
Use Cases
- Network port numbers
- Protocol buffers and binary formats
- File format headers and metadata
- Unicode character codes (BMP)
- Audio sample values
- Sensor readings and measurements
- Memory addresses (in 16-bit systems)
- Checksums and hash values
Error Handling
All operations throw on invalid inputs:
- Non-integer values
- Negative values
- Values exceeding 65535
- Arithmetic overflow/underflow
- Division by zero
Example
import * as Uint16 from '@voltaire/primitives/Uint16';
// Network port manipulation
const httpPort = Uint16(80);
const httpsPort = Uint16(443);
const customPort = Uint16(8080);
// Convert to bytes for network transmission
const portBytes = Uint16.toBytes(customPort);
console.log(portBytes); // Uint8Array([31, 144])
// Parse from bytes
const parsedPort = Uint16(portBytes);
console.log(Uint16.toNumber(parsedPort)); // 8080
// Bitwise operations for flags
const flags = Uint16(0b1010101010101010);
const mask = Uint16(0b1111111100000000);
const masked = Uint16.bitwiseAnd(flags, mask);
console.log(Uint16.toHex(masked)); // "0xaa00"
console.log(Uint16.popCount(masked)); // 4
