Numeric data encoding and decoding utilities for binary structures.

This module provides comprehensive support for encoding and decoding numeric values in binary format with configurable endianness. It includes:

  • Integer Types: 8, 16, 32, and 64-bit signed and unsigned integers
  • Floating Point: 16, 32, and 64-bit floating point numbers
  • Endianness Support: Both big-endian (network byte order) and little-endian
  • Type Safety: Full TypeScript support with proper type inference
  • Performance: Optimized using native DataView methods

All numeric coders follow the same interface pattern and can be used interchangeably in struct definitions, arrays, and other binary structures.

It's the user's responsibility to provide a buffer big enough to fit the whole data.

Examples

Basic numeric encoding and decoding:

import { assertEquals } from "@std/assert";
import { u16le, s32be, f64le } from "@hertzg/binstruct/numeric";
import { struct } from "@hertzg/binstruct/struct";

// Create a simple numeric structure
const numericStruct = struct({
  smallNumber: u16le(),      // 16-bit unsigned, little-endian
  signedNumber: s32be(),     // 32-bit signed, big-endian
  floatNumber: f64le(),      // 64-bit float, little-endian
});

// Test data
const testData = {
  smallNumber: 12345,        // Fits in 16-bit unsigned (0-65535)
  signedNumber: -1000000,    // 32-bit signed range
  floatNumber: 3.14159,      // Pi approximation
};

// Encode to binary
const buffer = new Uint8Array(100);
const bytesWritten = numericStruct.encode(testData, buffer);

// Decode from binary
const [decoded, bytesRead] = numericStruct.decode(buffer);

// Verify the results
assertEquals(decoded.smallNumber, testData.smallNumber);
assertEquals(decoded.signedNumber, testData.signedNumber);
assertEquals(decoded.floatNumber, testData.floatNumber);
assertEquals(bytesWritten, bytesRead);

Network protocol with mixed endianness:

import { assertEquals } from "@std/assert";
import { u16be, u32le, u64be } from "@hertzg/binstruct/numeric";
import { struct } from "@hertzg/binstruct/struct";

// Network packet header with mixed endianness
const packetHeader = struct({
  magic: u32le(),            // Magic number (little-endian)
  version: u16be(),          // Protocol version (big-endian, network order)
  flags: u16be(),            // Control flags (big-endian)
  timestamp: u64be(),        // Timestamp (big-endian)
  payloadSize: u32le(),      // Payload size (little-endian)
});

const testPacket = {
  magic: 0x12345678,
  version: 1,
  flags: 0x8000,
  timestamp: 1234567890n,
  payloadSize: 1024,
};

const buffer = new Uint8Array(100);
const bytesWritten = packetHeader.encode(testPacket, buffer);
const [decoded, bytesRead] = packetHeader.decode(buffer);

assertEquals(decoded.magic, testPacket.magic);
assertEquals(decoded.version, testPacket.version);
assertEquals(decoded.flags, testPacket.flags);
assertEquals(decoded.timestamp, testPacket.timestamp);
assertEquals(decoded.payloadSize, testPacket.payloadSize);
assertEquals(bytesWritten, bytesRead);

Functions

f
f16(endianness?: Endianness): Coder<number>

Creates a coder for 16-bit floating-point numbers.

f
f16be(): Coder<number>

Convenience function for 16-bit floating point with big-endian byte order.

f
f16le(): Coder<number>

Convenience function for 16-bit floating point with little-endian byte order.

f
f32(endianness?: Endianness): Coder<number>

Creates a coder for 32-bit floating-point numbers.

f
f32be(): Coder<number>

Convenience function for 32-bit floating point with big-endian byte order.

f
f32le(): Coder<number>

Convenience function for 32-bit floating point with little-endian byte order.

f
f64(endianness?: Endianness): Coder<number>

Creates a coder for 64-bit floating-point numbers.

f
f64be(): Coder<number>

Convenience function for 64-bit floating point with big-endian byte order.

f
f64le(): Coder<number>

Convenience function for 64-bit floating point with little-endian byte order.

f
s16(endianness?: Endianness): Coder<number>

Creates a coder for 16-bit signed integers.

f
s16be(): Coder<number>

Convenience function for 16-bit signed integer with big-endian byte order.

f
s16le(): Coder<number>

Convenience function for 16-bit signed integer with little-endian byte order.

f
s32(endianness?: Endianness): Coder<number>

Creates a coder for 32-bit signed integers.

f
s32be(): Coder<number>

Convenience function for 32-bit signed integer with big-endian byte order.

f
s32le(): Coder<number>

Convenience function for 32-bit signed integer with little-endian byte order.

f
s64(endianness?: Endianness): Coder<bigint>

Creates a coder for 64-bit signed integers.

f
s64be(): Coder<bigint>

Convenience function for 64-bit signed integer with big-endian byte order.

f
s64le(): Coder<bigint>

Convenience function for 64-bit signed integer with little-endian byte order.

f
s8(endianness?: Endianness): Coder<number>

Creates a coder for 8-bit signed integers.

f
s8be(): Coder<number>

Convenience function for 8-bit signed integer with big-endian byte order.

f
s8le(): Coder<number>

Convenience function for 8-bit signed integer with little-endian byte order.

f
u16(endianness?: Endianness): Coder<number>

Creates a coder for 16-bit unsigned integers.

f
u16be(): Coder<number>

Convenience function for 16-bit unsigned integer with big-endian byte order.

f
u16le(): Coder<number>

Convenience function for 16-bit unsigned integer with little-endian byte order.

f
u32(endianness?: Endianness): Coder<number>

Creates a coder for 32-bit unsigned integers.

f
u32be(): Coder<number>

Convenience function for 32-bit unsigned integer with big-endian byte order.

f
u32le(): Coder<number>

Convenience function for 32-bit unsigned integer with little-endian byte order.

f
u64(endianness?: Endianness): Coder<bigint>

Creates a coder for 64-bit unsigned integers.

f
u64be(): Coder<bigint>

Convenience function for 64-bit unsigned integer with big-endian byte order.

f
u64le(): Coder<bigint>

Convenience function for 64-bit unsigned integer with little-endian byte order.

f
u8(endianness?: Endianness): Coder<number>

Creates a coder for 8-bit unsigned integers.

f
u8be(): Coder<number>

Convenience function for 8-bit unsigned integer with big-endian byte order.

f
u8le(): Coder<number>

Convenience function for 8-bit unsigned integer with little-endian byte order.

Type Aliases

T
Endianness = "be" | "le"

Endianness type for numeric data encoding and decoding.

Usage

import * as mod from "numeric/numeric.ts";