ptr - Binary Data and Pointer Utilities for Deno

The ptr module provides utilities for working with binary data and pointers in Deno. It includes classes and functions to simplify reading, writing, and manipulating binary data, as well as handling pointers and memory offsets.

Features

• Pointer-like Classes:

  • Ptr: A class for reading and writing typed data at specific offsets in a DataView.
  • Cursor: A subclass of Ptr that automatically advances the offset after each operation.
  • Buf: aA generic wrapper around TypedArray (Uint8Array, Int32Array, ...) that offers utilities for working with pointers, DataView, and custom cursor/ptr objects.

• Endianness Detection:

  • isNativeLittleEndian: A boolean indicating whether the native platform is little-endian.

• String Utilities:

  • getPstr: Decode a string from a pointer and byte length.
  • getCstr: Decode a null-terminated string from a pointer.

• Type Size Calculation:

  • sizeof: Get the size in bytes of a given native type.

Installation

To use this module, install it via npm:

deno add @g9wp/ptr

Then, import it into your project:

import {
  Cursor,
  getCstr,
  getPstr,
  isNativeLittleEndian,
  Ptr,
  sizeof,
} from "@g9wp/ptr";

Usage

Working with Ptr

The Ptr class allows you to read and write various data types at specific offsets in a DataView.

import { Ptr } from "@g9wp/ptr";

const buffer = new ArrayBuffer(16);
const ptr = new Ptr(buffer);

ptr.setI32(42); // Write a 32-bit integer at offset 0
console.log(ptr.i32); // Read the 32-bit integer: 42

Using Cursor

The Cursor class extends Ptr and automatically advances the offset after each operation.

import { Cursor } from "@g9wp/ptr";

const buffer = new ArrayBuffer(16);
const cursor = new Cursor(buffer);

cursor.setI16(123); // Write a 16-bit integer at offset 0
console.log(cursor.offset); // Offset is now 2
cursor.setU32(45); // Write a 32-bit integer at offset 2
console.log(cursor.offset); // Offset is now 6

const cursorRead = new Cursor(new DataView(buffer, 0, cursor.offset));
console.log(cursorRead.i16); // Read the 16-bit integer: 123
console.log(cursorRead.offset); // Offset is now 2
console.log(cursorRead.u32); // Read the 32-bit integer: 45
console.log(cursorRead.offset); // Offset is now 6

Endianness Detection

Check the native platform's endianness:

console.log(isNativeLittleEndian ? "Little-endian" : "Big-endian");

String Utilities

Decode a null-terminated string from a pointer:

const ptrValue = Deno.UnsafePointer.of(
  new Uint8Array([72, 101, 108, 108, 111, 0]),
); // "Hello\0"
console.log(getCstr(ptrValue)); // Output: "Hello"

Type Size Calculation

Get the size of a native type:

console.log(sizeof("i32")); // Output: 4
console.log(sizeof("pointer")); // Output: 8 (on 64-bit systems)

API Reference

Classes

Ptr

• Provides methods for reading and writing various data types (i8, u8, i16, u16, i32, u32, f32, f64, etc.).
• Supports pointer operations and string decoding.

Cursor

• Extends Ptr with automatic offset advancement after each read/write operation.

OutBuf

provides output buffer utilities for writing Foreign Function Interface (FFI) code

import { u8 } from "@g9wp/ptr/out_buf";
// FFI: extern "C" void read_color(uint8_t* r, uint8_t* g, uint8_t* b);
function read_color(): { r: number, g: number, b: number } {
  lib.symbols.read_color(u8.p0, u8.p1, u8.p2);
  return { r: u8.v0, g: u8.v1, b: u8.v2  };
}

Functions

isNativeLittleEndian

• A boolean indicating whether the native platform is little-endian.

sizeof(type: Deno.NativeType | "pcstr"): number

• Returns the size in bytes of the specified native type.

getPstr(ptr: Deno.PointerObject, byteLength: number, offset?: number): string

• Decodes a string from a pointer and byte length.

getCstr(ptr: Deno.PointerObject): string

• Decodes a null-terminated string from a pointer.

License

This module is licensed under the MIT License. See the LICENSE file for details.