or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

buffer-creation.mdbuffer-manipulation.mddata-read-write.mdindex.mdstring-encoding.md
tile.json

data-read-write.mddocs/

Data Reading and Writing

Binary data read/write operations supporting multiple data types, byte orders, and bit lengths. Essential for binary protocol implementation, data serialization, and low-level data manipulation.

Capabilities

Unsigned Integer Read Operations

Read unsigned integers from buffer with different bit lengths and byte orders.

/**
 * Read 8-bit unsigned integer
 * @param offset - Byte offset to read from
 * @param noAssert - Skip bounds checking (deprecated)
 * @returns Unsigned 8-bit integer (0-255)
 */
readUInt8(offset: number, noAssert?: boolean): number;

/**
 * Read 16-bit unsigned integer (little endian)
 * @param offset - Byte offset to read from
 * @param noAssert - Skip bounds checking (deprecated)
 * @returns Unsigned 16-bit integer (0-65535)
 */
readUInt16LE(offset: number, noAssert?: boolean): number;

/**
 * Read 16-bit unsigned integer (big endian)
 * @param offset - Byte offset to read from
 * @param noAssert - Skip bounds checking (deprecated)
 * @returns Unsigned 16-bit integer (0-65535)
 */
readUInt16BE(offset: number, noAssert?: boolean): number;

/**
 * Read 32-bit unsigned integer (little endian)
 * @param offset - Byte offset to read from
 * @param noAssert - Skip bounds checking (deprecated)
 * @returns Unsigned 32-bit integer (0-4294967295)
 */
readUInt32LE(offset: number, noAssert?: boolean): number;

/**
 * Read 32-bit unsigned integer (big endian)
 * @param offset - Byte offset to read from
 * @param noAssert - Skip bounds checking (deprecated)
 * @returns Unsigned 32-bit integer (0-4294967295)
 */
readUInt32BE(offset: number, noAssert?: boolean): number;

/**
 * Read 64-bit unsigned integer (little endian)
 * @param offset - Byte offset to read from
 * @returns Unsigned 64-bit BigInt
 */
readBigUInt64LE(offset: number): bigint;

/**
 * Read 64-bit unsigned integer (big endian)
 * @param offset - Byte offset to read from
 * @returns Unsigned 64-bit BigInt
 */
readBigUInt64BE(offset: number): bigint;

/**
 * Read variable-length unsigned integer (little endian)
 * @param offset - Byte offset to read from
 * @param byteLength - Number of bytes to read (1-6)
 * @param noAssert - Skip bounds checking (deprecated)
 * @returns Unsigned integer
 */
readUIntLE(offset: number, byteLength: number, noAssert?: boolean): number;

/**
 * Read variable-length unsigned integer (big endian)
 * @param offset - Byte offset to read from
 * @param byteLength - Number of bytes to read (1-6)
 * @param noAssert - Skip bounds checking (deprecated)
 * @returns Unsigned integer
 */
readUIntBE(offset: number, byteLength: number, noAssert?: boolean): number;

Usage Examples:

const buf = Buffer.from([0x12, 0x34, 0x56, 0x78, 0x9a, 0xbc, 0xde, 0xf0]);

// 8-bit reads
const byte = buf.readUInt8(0); // 0x12 = 18

// 16-bit reads
const uint16le = buf.readUInt16LE(0); // 0x3412 = 13330
const uint16be = buf.readUInt16BE(0); // 0x1234 = 4660

// 32-bit reads
const uint32le = buf.readUInt32LE(0); // 0x78563412
const uint32be = buf.readUInt32BE(0); // 0x12345678

// 64-bit reads (BigInt)
const uint64le = buf.readBigUInt64LE(0); // 0xf0debc9a78563412n

// Variable length reads
const uint24le = buf.readUIntLE(0, 3); // 3-byte little endian

Signed Integer Read Operations

Read signed integers with support for two's complement representation.

/**
 * Read 8-bit signed integer
 * @param offset - Byte offset to read from
 * @param noAssert - Skip bounds checking (deprecated)
 * @returns Signed 8-bit integer (-128 to 127)
 */
readInt8(offset: number, noAssert?: boolean): number;

/**
 * Read 16-bit signed integer (little endian)
 * @param offset - Byte offset to read from
 * @param noAssert - Skip bounds checking (deprecated)
 * @returns Signed 16-bit integer (-32768 to 32767)
 */
readInt16LE(offset: number, noAssert?: boolean): number;

/**
 * Read 16-bit signed integer (big endian)
 * @param offset - Byte offset to read from
 * @param noAssert - Skip bounds checking (deprecated)
 * @returns Signed 16-bit integer (-32768 to 32767)
 */
readInt16BE(offset: number, noAssert?: boolean): number;

/**
 * Read 32-bit signed integer (little endian)
 * @param offset - Byte offset to read from
 * @param noAssert - Skip bounds checking (deprecated)
 * @returns Signed 32-bit integer (-2147483648 to 2147483647)
 */
readInt32LE(offset: number, noAssert?: boolean): number;

/**
 * Read 32-bit signed integer (big endian)
 * @param offset - Byte offset to read from
 * @param noAssert - Skip bounds checking (deprecated)
 * @returns Signed 32-bit integer (-2147483648 to 2147483647)
 */
readInt32BE(offset: number, noAssert?: boolean): number;

/**
 * Read 64-bit signed integer (little endian)
 * @param offset - Byte offset to read from
 * @returns Signed 64-bit BigInt
 */
readBigInt64LE(offset: number): bigint;

/**
 * Read 64-bit signed integer (big endian)
 * @param offset - Byte offset to read from
 * @returns Signed 64-bit BigInt
 */
readBigInt64BE(offset: number): bigint;

/**
 * Read variable-length signed integer (little endian)
 * @param offset - Byte offset to read from
 * @param byteLength - Number of bytes to read (1-6)
 * @param noAssert - Skip bounds checking (deprecated)
 * @returns Signed integer
 */
readIntLE(offset: number, byteLength: number, noAssert?: boolean): number;

/**
 * Read variable-length signed integer (big endian)
 * @param offset - Byte offset to read from
 * @param byteLength - Number of bytes to read (1-6)
 * @param noAssert - Skip bounds checking (deprecated)
 * @returns Signed integer
 */
readIntBE(offset: number, byteLength: number, noAssert?: boolean): number;

Floating Point Read Operations

Read IEEE 754 floating point numbers in single and double precision.

/**
 * Read 32-bit float (little endian)
 * @param offset - Byte offset to read from
 * @param noAssert - Skip bounds checking (deprecated)
 * @returns 32-bit floating point number
 */
readFloatLE(offset: number, noAssert?: boolean): number;

/**
 * Read 32-bit float (big endian)
 * @param offset - Byte offset to read from
 * @param noAssert - Skip bounds checking (deprecated)
 * @returns 32-bit floating point number
 */
readFloatBE(offset: number, noAssert?: boolean): number;

/**
 * Read 64-bit double (little endian)
 * @param offset - Byte offset to read from
 * @param noAssert - Skip bounds checking (deprecated)
 * @returns 64-bit floating point number
 */
readDoubleLE(offset: number, noAssert?: boolean): number;

/**
 * Read 64-bit double (big endian)
 * @param offset - Byte offset to read from
 * @param noAssert - Skip bounds checking (deprecated)
 * @returns 64-bit floating point number
 */
readDoubleBE(offset: number, noAssert?: boolean): number;

Usage Examples:

// Float buffer: [0x41, 0x48, 0x00, 0x00] = 12.5 (little endian)
const floatBuf = Buffer.from([0x41, 0x48, 0x00, 0x00]);
const float = floatBuf.readFloatBE(0); // 12.5

// Double buffer
const doubleBuf = Buffer.alloc(8);
doubleBuf.writeDoubleLE(3.14159, 0);
const pi = doubleBuf.readDoubleLE(0); // 3.14159

Unsigned Integer Write Operations

Write unsigned integers to buffer with different bit lengths and byte orders.

/**
 * Write 8-bit unsigned integer
 * @param value - Integer value to write (0-255)
 * @param offset - Byte offset to write to
 * @param noAssert - Skip bounds checking (deprecated)
 * @returns Offset plus bytes written
 */
writeUInt8(value: number, offset: number, noAssert?: boolean): number;

/**
 * Write 16-bit unsigned integer (little endian)
 * @param value - Integer value to write (0-65535)
 * @param offset - Byte offset to write to
 * @param noAssert - Skip bounds checking (deprecated)
 * @returns Offset plus bytes written
 */
writeUInt16LE(value: number, offset: number, noAssert?: boolean): number;

/**
 * Write 16-bit unsigned integer (big endian)
 * @param value - Integer value to write (0-65535)
 * @param offset - Byte offset to write to
 * @param noAssert - Skip bounds checking (deprecated)
 * @returns Offset plus bytes written
 */
writeUInt16BE(value: number, offset: number, noAssert?: boolean): number;

/**
 * Write 32-bit unsigned integer (little endian)
 * @param value - Integer value to write (0-4294967295)
 * @param offset - Byte offset to write to
 * @param noAssert - Skip bounds checking (deprecated)
 * @returns Offset plus bytes written
 */
writeUInt32LE(value: number, offset: number, noAssert?: boolean): number;

/**
 * Write 32-bit unsigned integer (big endian)
 * @param value - Integer value to write (0-4294967295)
 * @param offset - Byte offset to write to
 * @param noAssert - Skip bounds checking (deprecated)
 * @returns Offset plus bytes written
 */
writeUInt32BE(value: number, offset: number, noAssert?: boolean): number;

/**
 * Write 64-bit unsigned integer (little endian)
 * @param value - BigInt value to write
 * @param offset - Byte offset to write to (default: 0)
 * @returns Offset plus bytes written
 */
writeBigUInt64LE(value: bigint, offset?: number): number;

/**
 * Write 64-bit unsigned integer (big endian)
 * @param value - BigInt value to write
 * @param offset - Byte offset to write to (default: 0)
 * @returns Offset plus bytes written
 */
writeBigUInt64BE(value: bigint, offset?: number): number;

/**
 * Write variable-length unsigned integer (little endian)
 * @param value - Integer value to write
 * @param offset - Byte offset to write to
 * @param byteLength - Number of bytes to write (1-6)
 * @param noAssert - Skip bounds checking (deprecated)
 * @returns Offset plus bytes written
 */
writeUIntLE(value: number, offset: number, byteLength: number, noAssert?: boolean): number;

/**
 * Write variable-length unsigned integer (big endian)
 * @param value - Integer value to write
 * @param offset - Byte offset to write to
 * @param byteLength - Number of bytes to write (1-6)
 * @param noAssert - Skip bounds checking (deprecated)
 * @returns Offset plus bytes written
 */
writeUIntBE(value: number, offset: number, byteLength: number, noAssert?: boolean): number;

Signed Integer Write Operations

Write signed integers with two's complement representation.

/**
 * Write 8-bit signed integer
 * @param value - Integer value to write (-128 to 127)
 * @param offset - Byte offset to write to
 * @param noAssert - Skip bounds checking (deprecated)
 * @returns Offset plus bytes written
 */
writeInt8(value: number, offset: number, noAssert?: boolean): number;

/**
 * Write 16-bit signed integer (little endian)
 * @param value - Integer value to write (-32768 to 32767)
 * @param offset - Byte offset to write to
 * @param noAssert - Skip bounds checking (deprecated)
 * @returns Offset plus bytes written
 */
writeInt16LE(value: number, offset: number, noAssert?: boolean): number;

/**
 * Write 16-bit signed integer (big endian)
 * @param value - Integer value to write (-32768 to 32767)
 * @param offset - Byte offset to write to
 * @param noAssert - Skip bounds checking (deprecated)
 * @returns Offset plus bytes written
 */
writeInt16BE(value: number, offset: number, noAssert?: boolean): number;

/**
 * Write 32-bit signed integer (little endian)
 * @param value - Integer value to write (-2147483648 to 2147483647)
 * @param offset - Byte offset to write to
 * @param noAssert - Skip bounds checking (deprecated)
 * @returns Offset plus bytes written
 */
writeInt32LE(value: number, offset: number, noAssert?: boolean): number;

/**
 * Write 32-bit signed integer (big endian)
 * @param value - Integer value to write (-2147483648 to 2147483647)
 * @param offset - Byte offset to write to
 * @param noAssert - Skip bounds checking (deprecated)
 * @returns Offset plus bytes written
 */
writeInt32BE(value: number, offset: number, noAssert?: boolean): number;

/**
 * Write 64-bit signed integer (little endian)
 * @param value - BigInt value to write
 * @param offset - Byte offset to write to (default: 0)
 * @returns Offset plus bytes written
 */
writeBigInt64LE(value: bigint, offset?: number): number;

/**
 * Write 64-bit signed integer (big endian)
 * @param value - BigInt value to write
 * @param offset - Byte offset to write to (default: 0)
 * @returns Offset plus bytes written
 */
writeBigInt64BE(value: bigint, offset?: number): number;

/**
 * Write variable-length signed integer (little endian)
 * @param value - Integer value to write
 * @param offset - Byte offset to write to
 * @param byteLength - Number of bytes to write (1-6)
 * @param noAssert - Skip bounds checking (deprecated)
 * @returns Offset plus bytes written
 */
writeIntLE(value: number, offset: number, byteLength: number, noAssert?: boolean): number;

/**
 * Write variable-length signed integer (big endian)
 * @param value - Integer value to write
 * @param offset - Byte offset to write to
 * @param byteLength - Number of bytes to write (1-6)
 * @param noAssert - Skip bounds checking (deprecated)
 * @returns Offset plus bytes written
 */
writeIntBE(value: number, offset: number, byteLength: number, noAssert?: boolean): number;

Floating Point Write Operations

Write IEEE 754 floating point numbers in single and double precision.

/**
 * Write 32-bit float (little endian)
 * @param value - Float value to write
 * @param offset - Byte offset to write to
 * @param noAssert - Skip bounds checking (deprecated)
 * @returns Offset plus bytes written
 */
writeFloatLE(value: number, offset: number, noAssert?: boolean): number;

/**
 * Write 32-bit float (big endian)
 * @param value - Float value to write
 * @param offset - Byte offset to write to
 * @param noAssert - Skip bounds checking (deprecated)
 * @returns Offset plus bytes written
 */
writeFloatBE(value: number, offset: number, noAssert?: boolean): number;

/**
 * Write 64-bit double (little endian)
 * @param value - Double value to write
 * @param offset - Byte offset to write to
 * @param noAssert - Skip bounds checking (deprecated)
 * @returns Offset plus bytes written
 */
writeDoubleLE(value: number, offset: number, noAssert?: boolean): number;

/**
 * Write 64-bit double (big endian)
 * @param value - Double value to write
 * @param offset - Byte offset to write to
 * @param noAssert - Skip bounds checking (deprecated)
 * @returns Offset plus bytes written
 */
writeDoubleBE(value: number, offset: number, noAssert?: boolean): number;

Usage Examples:

const buf = Buffer.alloc(16);

// Write various integer types
buf.writeUInt8(255, 0);           // Byte 0: 0xFF
buf.writeUInt16LE(0x1234, 1);     // Bytes 1-2: 0x34, 0x12
buf.writeInt32BE(-1000, 3);       // Bytes 3-6: signed big endian

// Write floating point
buf.writeFloatLE(3.14, 7);        // Bytes 7-10: 32-bit float
buf.writeDoubleLE(2.718, 11);     // Bytes 11-18: 64-bit double (but buffer only 16 bytes)

// Write BigInt (64-bit)
const bigBuf = Buffer.alloc(8);
bigBuf.writeBigUInt64LE(0x123456789abcdef0n, 0);

Byte Order Conversion

Swap byte order for multi-byte values within the buffer.

/**
 * Swap byte order for 16-bit values
 * @returns This buffer for chaining
 */
swap16(): Buffer;

/**
 * Swap byte order for 32-bit values
 * @returns This buffer for chaining
 */
swap32(): Buffer;

/**
 * Swap byte order for 64-bit values
 * @returns This buffer for chaining
 */
swap64(): Buffer;

Usage Examples:

const buf = Buffer.from([0x01, 0x02, 0x03, 0x04]);
buf.swap16(); // Now: [0x02, 0x01, 0x04, 0x03]
buf.swap32(); // Now: [0x04, 0x03, 0x02, 0x01]

Error Handling

Read/write operations may throw the following errors:

  • RangeError: When offset is out of buffer bounds
  • RangeError: When trying to read/write beyond buffer length
  • TypeError: When value is of incorrect type for BigInt operations
  • Error: "BigInt not supported" when BigInt methods are called in environments without BigInt support
const buf = Buffer.alloc(4);

try {
  buf.readUInt32LE(10); // Throws RangeError: index out of range
} catch (error) {
  console.error('Read error:', error.message);
}

// BigInt support check
try {
  const buf64 = Buffer.alloc(8);
  buf64.readBigUInt64LE(0); // May throw "BigInt not supported" in older environments
} catch (error) {
  console.error('BigInt error:', error.message);
}

BigInt Support

BigInt methods (readBigUInt64LE, readBigUInt64BE, readBigInt64LE, readBigInt64BE, writeBigUInt64LE, writeBigUInt64BE, writeBigInt64LE, writeBigInt64BE) require native BigInt support. In environments without BigInt support, these methods will throw an error "BigInt not supported".