Uint16

Type-safe 16-bit unsigned integer (0-65535) with compile-time branding

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