@thi.ng/wasm-api/string.d.ts

Generic, modular, extensible API bridge and infrastructure for hybrid JS & WebAssembly projects

import type { IWasmMemoryAccess, MemorySlice, ReadonlyWasmString } from "./api.js";
/**
 * Memory mapped string wrapper for Zig-style UTF-8 encoded byte slices (aka
 * pointer & length pair). The actual JS string can be obtained via
 * {@link WasmStringSlice.deref} and possibly mutated via
 * {@link WasmStringSlice.set}.
 *
 * @remarks
 * Currently only supports wasm32 target, need alt. solution for 64bit (possibly
 * diff implementation) using bigint addresses (TODO)
 */
export declare class WasmStringSlice implements ReadonlyWasmString {
    readonly mem: IWasmMemoryAccess;
    readonly base: number;
    protected isConst: boolean;
    protected terminated: boolean;
    protected maxLen: number;
    constructor(mem: IWasmMemoryAccess, base: number, isConst?: boolean, terminated?: boolean);
    /**
     * Returns string start address (deref'd pointer).
     */
    get addr(): number;
    /**
     * Returns string length (read from memory)
     */
    get length(): number;
    /**
     * Returns memory as JS string (aka wrapper for
     * {@link WasmBridge.getString}).
     */
    deref(): string;
    /**
     * If given a JS string as arg (and if **not** a const slice), attempts to
     * overwrite this wrapped string's memory with bytes from given string. If
     * given another {@link WasmStringSlice} as arg, only the slice pointer &
     * new length will be updated (always succeeds).
     *
     * @remarks
     * When copying bytes from a JS string, an error will be thrown if the new
     * string is longer than the _original_ length of the slice (i.e. from when
     * this `WasmStringSlice` wrapper instance was created). Also updates the
     * slice's length field to new string length.
     *
     * Passing a `WasmString` instance as arg is faster than JS string since
     * only the slice definition itself will be updated.
     *
     * @param str
     */
    set(str: string | WasmStringSlice): void;
    /**
     * Sets the slice itself to the new values provided.
     *
     * @param slice
     * @param terminated
     */
    setSlice(slice: MemorySlice, terminated: boolean): MemorySlice;
    setSlice(addr: number, len: number, terminated: boolean): MemorySlice;
    /**
     * Encodes given string to UTF-8 (by default zero terminated), allocates
     * memory for it, updates this slice and returns a {@link MemorySlice} of
     * the allocated region.
     *
     * @remarks
     * If `terminated` is true, the stored slice length will **NOT** include the
     * sentinel! E.g. the slice length of zero-terminated string `"abc"` is 3,
     * but the number of allocated bytes is 4. This is done for compatibility
     * with Zig's sentinel-terminated slice handling (e.g. `[:0]u8` slices).
     *
     * Regardless of `terminated` setting, the returned `MemorySlice` **always**
     * covers the entire allocated region!
     *
     * @param str
     * @param terminate
     */
    setAlloc(str: string, terminate?: boolean): MemorySlice;
    toJSON(): string;
    toString(): string;
    valueOf(): string;
}
/**
 * Memory mapped string wrapper for C-style UTF-8 encoded and **always**
 * zero-terminated char pointers. The actual JS string can be obtained via
 * {@link WasmStringPtr.deref} and mutated via {@link WasmStringPtr.set}.
 *
 * @remarks
 * Pointers with addr=0 are interpreted as null/optional pointers. See
 * {@link WasmStringPtr.length} and {@link WasmStringPtr.deref} for details.
 */
export declare class WasmStringPtr implements ReadonlyWasmString {
    readonly mem: IWasmMemoryAccess;
    readonly base: number;
    protected isConst: boolean;
    constructor(mem: IWasmMemoryAccess, base: number, isConst?: boolean);
    /**
     * Returns string start address (deref'd pointer).
     */
    get addr(): number;
    set addr(addr: number);
    get isNull(): boolean;
    /**
     * Returns computed string length (scanning memory for zero sentinel)
     *
     * @remarks
     * Always returns 0 if null pointer (i.e. if {@link WasmStringPtr.addr} is
     * zero).
     */
    get length(): number;
    /**
     * Returns memory as JS string (via {@link WasmBridge.getString}). Returns
     * empty string if null pointer (i.e. if {@link WasmStringPtr.addr} is
     * zero).
     */
    deref(): string;
    /**
     * If given a JS string as arg (and if this `WasmStringPtr` instance itself
     * is not a `const` pointer), attempts to overwrite this wrapped string's
     * memory with bytes from given string. If given another
     * {@link WasmStringPtr}, it merely overrides the pointer to the new one
     * (always succeeds).
     *
     * @remarks
     * Unlike with {@link WasmStringSlice.set} this implementation which
     * performs bounds checking when copying bytes from a JS string, this method
     * only throws an error if the new string is longer than the available
     * memory (from the start address until the end of the WASM memory).
     * **Therefore, this is as (un)safe as a C pointer and should be used with
     * caution!**
     *
     * Passing a `WasmStringPtr` instance as arg is faster than JS string since
     * only the pointer itself will be updated.
     *
     * @param str
     */
    set(str: string | WasmStringPtr): void;
    /**
     * Encodes given string to UTF-8 (by default zero terminated), allocates
     * memory for it, updates this pointer to new address and returns allocated
     * {@link MemorySlice}.
     *
     * @remarks
     * See {@link WasmStringSlice.setAlloc} for important details.
     *
     * @param str
     */
    setAlloc(str: string): MemorySlice;
    toJSON(): string;
    toString(): string;
    valueOf(): string;
}
//# sourceMappingURL=string.d.ts.map