Skip to main content

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

​
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"