Try it Live

Run Uint examples in the interactive playground

Uint8

A branded type for 8-bit unsigned integers (range: 0-255) represented as JavaScript numbers with compile-time type safety.

Overview

Uint8Type provides type-safe operations on 8-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 Uint8Type = number & { readonly [brand]: "Uint8" };

Range

Minimum: 0
Maximum: 255
Size: 8 bits

Constants

import * as Uint8 from '@voltaire/primitives/Uint8';

Uint8.MIN;    // 0
Uint8.MAX;    // 255
Uint8.ZERO;   // 0
Uint8.ONE;    // 1
Uint8.SIZE;   // 8

Construction

from

Create from number or string:

const a = Uint8(100);
const b = Uint8("255");
const c = Uint8("0xff");

fromNumber

Create from number:

const value = Uint8(255);

fromBigint

Create from bigint:

const value = Uint8(255n);

fromHex

Create from hex string:

const a = Uint8("0xff");
const b = Uint8("ff");

fromBytes

Create from Uint8Array (1 byte):

const bytes = new Uint8Array([255]);
const value = Uint8(bytes);

Conversion

toNumber

const num = Uint8.toNumber(Uint8(255)); // 255

toBigint

const bigintValue = Uint8.toBigint(Uint8(255)); // 255n

toHex

const hex = Uint8.toHex(Uint8(255)); // "0xff"
const unpadded = Uint8.toHex(Uint8(15), false); // "0xf"

toBytes

const bytes = Uint8.toBytes(Uint8(255)); // Uint8Array([255])

toString

const str = Uint8.toString(Uint8(255)); // "255"

Arithmetic

All arithmetic operations validate that results stay within valid range.

plus

const sum = Uint8.plus(Uint8(100), Uint8(50)); // 150
// Throws on overflow

minus

const diff = Uint8.minus(Uint8(100), Uint8(50)); // 50
// Throws on underflow

times

const product = Uint8.times(Uint8(10), Uint8(5)); // 50
// Throws on overflow

dividedBy

const quotient = Uint8.dividedBy(Uint8(100), Uint8(5)); // 20
// Integer division

modulo

const remainder = Uint8.modulo(Uint8(100), Uint8(7)); // 2

Comparison

equals

Uint8.equals(Uint8(100), Uint8(100)); // true

lessThan

Uint8.lessThan(Uint8(50), Uint8(100)); // true

greaterThan

Uint8.greaterThan(Uint8(100), Uint8(50)); // true

isZero

Uint8.isZero(Uint8(0)); // true

minimum

const min = Uint8.minimum(Uint8(100), Uint8(50)); // 50

maximum

const max = Uint8.maximum(Uint8(100), Uint8(50)); // 100

Bitwise Operations

bitwiseAnd

const result = Uint8.bitwiseAnd(Uint8(0b11110000), Uint8(0b11001100));
// 0b11000000 = 192

bitwiseOr

const result = Uint8.bitwiseOr(Uint8(0b11110000), Uint8(0b00001111));
// 0b11111111 = 255

bitwiseXor

const result = Uint8.bitwiseXor(Uint8(0b11110000), Uint8(0b11001100));
// 0b00111100 = 60

bitwiseNot

const result = Uint8.bitwiseNot(Uint8(0b11110000));
// 0b00001111 = 15

shiftLeft

const result = Uint8.shiftLeft(Uint8(0b00001111), 4);
// 0b11110000 = 240

shiftRight

const result = Uint8.shiftRight(Uint8(0b11110000), 4);
// 0b00001111 = 15

Bit Analysis

bitLength

Get number of bits needed to represent value:

Uint8.bitLength(Uint8(0)); // 0
Uint8.bitLength(Uint8(1)); // 1
Uint8.bitLength(Uint8(255)); // 8

leadingZeros

Count leading zero bits:

Uint8.leadingZeros(Uint8(0)); // 8
Uint8.leadingZeros(Uint8(1)); // 7
Uint8.leadingZeros(Uint8(255)); // 0

popCount

Count set bits:

Uint8.popCount(Uint8(0)); // 0
Uint8.popCount(Uint8(255)); // 8
Uint8.popCount(Uint8(0b10101010)); // 4

Validation

isValid

Uint8.isValid(100); // true
Uint8.isValid(255); // true
Uint8.isValid(256); // false
Uint8.isValid(-1); // false
Uint8.isValid(1.5); // false

Use Cases

Protocol buffers and binary formats
Network packet headers
Byte-level data manipulation
Image pixel values (RGB components)
Hardware register values
Compact data structures
Checksum and hash algorithms

Error Handling

All operations throw on invalid inputs:

Non-integer values
Negative values
Values exceeding 255
Arithmetic overflow/underflow
Division by zero

Example

import * as Uint8 from '@voltaire/primitives/Uint8';

// RGB color manipulation
const red = Uint8(255);
const green = Uint8(128);
const blue = Uint8(64);

// Combine into single value (simplified)
const rgb = [
  Uint8.toBytes(red),
  Uint8.toBytes(green),
  Uint8.toBytes(blue)
].flat();

// Bitwise operations for flags
const flags = Uint8(0b10101010);
const mask = Uint8(0b11110000);
const masked = Uint8.bitwiseAnd(flags, mask);

console.log(Uint8.toHex(masked)); // "0xa0"

Try it Live

​Uint8

​Overview

​Type Definition

​Range

​Constants

​Construction

​from

​fromNumber

​fromBigint

​fromHex

​fromBytes

​Conversion

​toNumber

​toBigint

​toHex

​toBytes

​toString

​Arithmetic

​plus

​minus

​times

​dividedBy

​modulo

​Comparison

​equals

​lessThan

​greaterThan

​isZero

​minimum

​maximum

​Bitwise Operations

​bitwiseAnd

​bitwiseOr

​bitwiseXor

​bitwiseNot

​shiftLeft

​shiftRight

​Bit Analysis

​bitLength

​leadingZeros

​popCount

​Validation

​isValid

​Use Cases

​Error Handling

​Example