Skip to main content

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