> ## 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. # Uint16 > Type-safe 16-bit unsigned integer (0-65535) with compile-time branding 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 ```typescript theme={null} import type { brand } from '../../../brand.js'; export type Uint16 = number & { readonly [brand]: "Uint16" }; ``` ## Range * **Minimum**: 0 * **Maximum**: 65535 * **Size**: 16 bits ## Constants ```typescript theme={null} 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: ```typescript theme={null} const a = Uint16(30000); const b = Uint16("65535"); const c = Uint16("0xffff"); ``` ### fromNumber Create from number: ```typescript theme={null} const value = Uint16(65535); ``` ### fromBigint Create from bigint: ```typescript theme={null} const value = Uint16(65535n); ``` ### fromHex Create from hex string: ```typescript theme={null} const a = Uint16("0xffff"); const b = Uint16("ffff"); ``` ### fromBytes Create from Uint8Array (2 bytes, big-endian): ```typescript theme={null} const bytes = new Uint8Array([0xff, 0xff]); const value = Uint16(bytes); // 65535 ``` ## Conversion ### toNumber ```typescript theme={null} const num = Uint16.toNumber(Uint16(65535)); // 65535 ``` ### toBigint ```typescript theme={null} const bigintValue = Uint16.toBigint(Uint16(65535)); // 65535n ``` ### toHex ```typescript theme={null} const hex = Uint16.toHex(Uint16(65535)); // "0xffff" const unpadded = Uint16.toHex(Uint16(15), false); // "0xf" ``` ### toBytes ```typescript theme={null} const bytes = Uint16.toBytes(Uint16(65535)); // Uint8Array([255, 255]) ``` ### toString ```typescript theme={null} const str = Uint16.toString(Uint16(65535)); // "65535" ``` ## Arithmetic All arithmetic operations validate that results stay within valid range. ### plus ```typescript theme={null} const sum = Uint16.plus(Uint16(30000), Uint16(20000)); // 50000 // Throws on overflow ``` ### minus ```typescript theme={null} const diff = Uint16.minus(Uint16(30000), Uint16(20000)); // 10000 // Throws on underflow ``` ### times ```typescript theme={null} const product = Uint16.times(Uint16(100), Uint16(500)); // 50000 // Throws on overflow ``` ### dividedBy ```typescript theme={null} const quotient = Uint16.dividedBy(Uint16(10000), Uint16(100)); // 100 // Integer division ``` ### modulo ```typescript theme={null} const remainder = Uint16.modulo(Uint16(10007), Uint16(1000)); // 7 ``` ## Comparison ### equals ```typescript theme={null} Uint16.equals(Uint16(30000), Uint16(30000)); // true ``` ### lessThan ```typescript theme={null} Uint16.lessThan(Uint16(10000), Uint16(30000)); // true ``` ### greaterThan ```typescript theme={null} Uint16.greaterThan(Uint16(30000), Uint16(10000)); // true ``` ### isZero ```typescript theme={null} Uint16.isZero(Uint16(0)); // true ``` ### minimum ```typescript theme={null} const min = Uint16.minimum(Uint16(30000), Uint16(10000)); // 10000 ``` ### maximum ```typescript theme={null} const max = Uint16.maximum(Uint16(30000), Uint16(10000)); // 30000 ``` ## Bitwise Operations ### bitwiseAnd ```typescript theme={null} const result = Uint16.bitwiseAnd( Uint16(0b1111111100000000), Uint16(0b1111000011110000) ); // 0b1111000000000000 = 61440 ``` ### bitwiseOr ```typescript theme={null} const result = Uint16.bitwiseOr( Uint16(0b1111111100000000), Uint16(0b0000000011111111) ); // 0b1111111111111111 = 65535 ``` ### bitwiseXor ```typescript theme={null} const result = Uint16.bitwiseXor( Uint16(0b1111111100000000), Uint16(0b1111000011110000) ); // 0b0000111111110000 = 4080 ``` ### bitwiseNot ```typescript theme={null} const result = Uint16.bitwiseNot(Uint16(0b1111111100000000)); // 0b0000000011111111 = 255 ``` ### shiftLeft ```typescript theme={null} const result = Uint16.shiftLeft(Uint16(0b0000000011111111), 8); // 0b1111111100000000 = 65280 ``` ### shiftRight ```typescript theme={null} const result = Uint16.shiftRight(Uint16(0b1111111100000000), 8); // 0b0000000011111111 = 255 ``` ## Bit Analysis ### bitLength Get number of bits needed to represent value: ```typescript theme={null} Uint16.bitLength(Uint16(0)); // 0 Uint16.bitLength(Uint16(1)); // 1 Uint16.bitLength(Uint16(65535)); // 16 ``` ### leadingZeros Count leading zero bits: ```typescript theme={null} Uint16.leadingZeros(Uint16(0)); // 16 Uint16.leadingZeros(Uint16(1)); // 15 Uint16.leadingZeros(Uint16(65535)); // 0 ``` ### popCount Count set bits: ```typescript theme={null} Uint16.popCount(Uint16(0)); // 0 Uint16.popCount(Uint16(65535)); // 16 Uint16.popCount(Uint16(0b1010101010101010)); // 8 ``` ## Validation ### isValid ```typescript theme={null} 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 ```typescript theme={null} 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 ```