@woosh/meep-engine/src/core/binary/BinaryBuffer.d.ts

Pure JavaScript game engine. Fully featured and production ready.

/**
 * Utility for reading/writing binary data.
 * Mostly useful for serialization/deserialization tasks.
 * The buffer is dynamically resized, so you do not need to manage the size manually.
 * It is useful to think of this structure as a "stream".
 *
 * @example
 *  const buffer = new BinaryBuffer();
 *
 *  buffer.writeUTF8String("Hello World");
 *
 *  buffer.position = 0; // rewind to the beginning
 *
 *  const deserialized = buffer.readUTF8String(); // "Hello World"
 *
 *
 * @author Alex Goldring
 * @copyright Company Named Limited (c) 2025
 */
export class BinaryBuffer {
    /**
     *
     * @param {EndianType} type
     * @return {BinaryBuffer}
     */
    static fromEndianness(type: EndianType): BinaryBuffer;
    /**
     *
     * @param {ArrayBuffer} v
     * @return {BinaryBuffer}
     */
    static fromArrayBuffer(v: ArrayBuffer): BinaryBuffer;
    /**
     *
     * @param {BinaryBuffer} source
     * @param {BinaryBuffer} target
     * @returns {string} Copied value
     */
    static copyUTF8String(source: BinaryBuffer, target: BinaryBuffer): string;
    /**
     *
     * @param {BinaryBuffer} source
     * @param {BinaryBuffer} target
     * @returns {number} Copied value
     */
    static copyUintVar(source: BinaryBuffer, target: BinaryBuffer): number;
    /**
     *
     * @param {BinaryBuffer} source
     * @param {BinaryBuffer} target
     * @returns {number} Copied value
     */
    static copyUint8(source: BinaryBuffer, target: BinaryBuffer): number;
    /**
     *
     * @param {BinaryBuffer} source
     * @param {BinaryBuffer} target
     * @returns {number} Copied value
     */
    static copyUint16(source: BinaryBuffer, target: BinaryBuffer): number;
    /**
     *
     * @param {BinaryBuffer} source
     * @param {BinaryBuffer} target
     * @returns {number} Copied value
     */
    static copyUint32(source: BinaryBuffer, target: BinaryBuffer): number;
    /**
     *
     * @param {BinaryBuffer} source
     * @param {BinaryBuffer} target
     * @returns {number} Copied value
     */
    static copyFloat32(source: BinaryBuffer, target: BinaryBuffer): number;
    /**
     *
     * @param {BinaryBuffer} source
     * @param {BinaryBuffer} target
     * @returns {number} Copied value
     */
    static copyFloat64(source: BinaryBuffer, target: BinaryBuffer): number;
    /**
     *
     * @param {BinaryBuffer} source
     * @param {BinaryBuffer} target
     * @param {number} length number of bytes to copy
     * @returns {Uint8Array} Copied data
     */
    static copyBytes(source: BinaryBuffer, target: BinaryBuffer, length: number): Uint8Array;
    /**
     * Default is little-endian as most platforms operate in little-endian
     * The reason this is fixed is to ensure cross-platform compatibility as endianness in JavaScript is platform-dependent.
     * @see https://en.wikipedia.org/wiki/Endianness
     * @type {EndianType|boolean}
     */
    endianness: EndianType | boolean;
    /**
     * Current position in the buffer, where read and write operations will occur.
     * Make sure to set this to the correct value before reading/writing data.
     * Typically, this is set to 0 before reading/writing data.
     * @type {number}
     */
    position: number;
    /**
     * @deprecated
     */
    set length(arg: void);
    /**
     * @deprecated
     */
    get length(): void;
    /**
     * Managed by the buffer, do not modify directly
     * @type {number}
     */
    capacity: number;
    /**
     * Raw underlying bytes attached to the buffer, note that this is managed by the `BinaryBuffer` and can grow/shrink as needed.
     * @see setCapacity
     * @see trim
     * @type {ArrayBuffer}
     * @private
     */
    private data;
    /**
     * Bound to the {@link data} buffer, do not modify directly.
     * @type {DataView}
     * @private
     */
    private dataView;
    /**
     * Bound to the {@link data} buffer, do not modify directly.
     * @type {Uint8Array}
     * @private
     */
    private __data_uint8;
    /**
     * When the buffer grows in size, this is the multiplication factor by which it grows.
     * @type {number}
     * @private
     */
    private __growFactor;
    /**
     * Access raw underlying bytes attached to the buffer
     * @return {Uint8Array}
     */
    get raw_bytes(): Uint8Array;
    /**
     * Sets {@link capacity} to the size of the input data.
     * Sets {@link position} to 0.
     *
     * Note: if you write to the buffer past the size of the input data {@link ArrayBuffer} - bound data will be re-allocated.
     * @param {ArrayBuffer} data
     */
    fromArrayBuffer(data: ArrayBuffer): void;
    /**
     * Set capacity to contain data only up to the current `position`.
     * This will re-allocate the `data` buffer if necessary.
     * @returns {BinaryBuffer}
     */
    trim(): BinaryBuffer;
    /**
     * Advance `position`(read/write cursor) a certain number of bytes forward.
     *
     * @param {number} byte_count
     */
    skip(byte_count: number): void;
    /**
     * This will re-allocate {@link data} buffer if necessary.
     * Note that all data is retained.
     * Cannot shink past the current `position`.
     *
     * @param {number} capacity
     * @throws {Error} if requested capacity is less than current `position`
     *
     */
    setCapacity(capacity: number): void;
    /**
     *
     * @param {number} min_capacity
     */
    ensureCapacity(min_capacity: number): void;
    /**
     *
     * @returns {number}
     */
    readFloat16(): number;
    /**
     *
     * @returns {number}
     */
    readFloat32(): number;
    /**
     *
     * @returns {number}
     */
    readFloat64(): number;
    /**
     *
     * @return {number}
     */
    readInt8(): number;
    /**
     *
     * @return {number}
     */
    readInt16(): number;
    /**
     *
     * @returns {number}
     */
    readInt32(): number;
    /**
     *
     * @returns {number}
     */
    readUint8(): number;
    /**
     *
     * @returns {number}
     */
    readUint16(): number;
    /**
     *
     * @returns {number}
     */
    readUint16LE(): number;
    /**
     *
     * @returns {number}
     */
    readUint16BE(): number;
    /**
     *
     * @returns {number}
     */
    readUint24(): number;
    /**
     *
     * @returns {number}
     */
    readUint24LE(): number;
    /**
     *
     * @returns {number}
     */
    readUint24BE(): number;
    /**
     *
     * @returns {number}
     */
    readUint32(): number;
    /**
     *
     * @returns {number}
     */
    readUint32LE(): number;
    /**
     *
     * @returns {number}
     */
    readUint32BE(): number;
    /**
     *
     * @param {number} destination_offset starting index in the destination array
     * @param {number} length number of elements to read
     * @param {Uint8Array} destination
     */
    readUint8Array(destination: Uint8Array, destination_offset: number, length: number): void;
    /**
     *
     * @param {number} destination_offset starting index in the destination array
     * @param {number} length number of elements to read
     * @param {Uint16Array} destination
     */
    readUint16Array(destination: Uint16Array, destination_offset: number, length: number): void;
    /**
     *
     * @param {number} destination_offset starting index in the destination array
     * @param {number} length number of elements to read
     * @param {Uint32Array|number[]|ArrayLike<number>} destination
     */
    readUint32Array(destination: Uint32Array | number[] | ArrayLike<number>, destination_offset: number, length: number): void;
    /**
     *
     * @param {number} destination_offset starting index in the destination array
     * @param {number} length number of elements to read
     * @param {Int8Array} destination
     */
    readInt8Array(destination: Int8Array, destination_offset: number, length: number): void;
    /**
     *
     * @param {number} destination_offset starting index in the destination array
     * @param {number} length number of elements to read
     * @param {Int16Array} destination
     */
    readInt16Array(destination: Int16Array, destination_offset: number, length: number): void;
    /**
     *
     * @param {number} destination_offset starting index in the destination array
     * @param {number} length number of elements to read
     * @param {Int32Array} destination
     */
    readInt32Array(destination: Int32Array, destination_offset: number, length: number): void;
    /**
     *
     * @param {number} destination_offset starting index in the destination array
     * @param {number} length number of elements to read
     * @param {Float32Array|number[]} destination
     */
    readFloat32Array(destination: Float32Array | number[], destination_offset: number, length: number): void;
    /**
     *
     * @param {number} destination_offset starting index in the destination array
     * @param {number} length number of elements to read
     * @param {Float64Array} destination
     */
    readFloat64Array(destination: Float64Array, destination_offset: number, length: number): void;
    /**
     *
     * @param {number} source_offset starting index in the source array
     * @param {number} length number of elements to read
     * @param {Float32Array|number[]} source
     */
    writeFloat32Array(source: Float32Array | number[], source_offset: number, length: number): void;
    /**
     *
     * @param {number} value
     */
    writeFloat16(value: number): void;
    /**
     *
     * @param {number} value
     */
    writeFloat32(value: number): void;
    /**
     *
     * @param {number} value
     */
    writeFloat64(value: number): void;
    /**
     *
     * @param {number} value
     */
    writeInt8(value: number): void;
    /**
     *
     * @param {number} value
     */
    writeInt16(value: number): void;
    /**
     *
     * @param {number} value
     */
    writeInt32(value: number): void;
    /**
     *
     * @param {Int8Array|number[]|ArrayLike<number>} source
     * @param {number} source_offset
     * @param {number} length
     */
    writeInt8Array(source: Int8Array | number[] | ArrayLike<number>, source_offset: number, length: number): void;
    /**
     *
     * @param {Int16Array|number[]|ArrayLike<number>} source
     * @param {number} source_offset
     * @param {number} length
     */
    writeInt16Array(source: Int16Array | number[] | ArrayLike<number>, source_offset: number, length: number): void;
    /**
     *
     * @param {Int32Array|number[]|ArrayLike<number>} source
     * @param {number} source_offset
     * @param {number} length
     */
    writeInt32Array(source: Int32Array | number[] | ArrayLike<number>, source_offset: number, length: number): void;
    /**
     *
     * @param {number} value
     */
    writeUint8(value: number): void;
    /**
     *
     * @param {Uint8Array|number[]} source
     * @param {number} source_offset
     * @param {number} length
     */
    writeUint8Array(source: Uint8Array | number[], source_offset: number, length: number): void;
    /**
     *
     * @param {number} value
     */
    writeUint16(value: number): void;
    /**
     *
     * @param {number} value
     */
    writeUint16BE(value: number): void;
    /**
     *
     * @param {number} value
     */
    writeUint16LE(value: number): void;
    /**
     *
     * @param {Uint16Array|number[]} source
     * @param {number} source_offset
     * @param {number} length
     */
    writeUint16Array(source: Uint16Array | number[], source_offset: number, length: number): void;
    /**
     *
     * @param {number} value
     */
    writeUint24(value: number): void;
    /**
     *
     * @param {number} value
     */
    writeUint24BE(value: number): void;
    /**
     *
     * @param {number} value
     */
    writeUint24LE(value: number): void;
    /**
     * Write uint using a minimum number of bytes.
     * Compact encoding scheme, if the value is 127 or less - only one byte will be used, if the value is 16383 or less - two bytes will be used, etc.
     * NOTE: uses 7-bit encoding with 1 bit used for carry-over flag.
     * NOTE: explicitly a little-endian format, {@link endianness} is ignored.
     * @param {number} value must be an unsigned integer
     */
    writeUintVar(value: number): void;
    /**
     * Read Uint of variable length, a compliment to {@link #writeUintVar}
     * @returns {number}
     */
    readUintVar(): number;
    /**
     *
     * @param {number} value
     */
    writeUint32(value: number): void;
    /**
     *
     * @param {number} value
     */
    writeUint32BE(value: number): void;
    /**
     *
     * @param {number} value
     */
    writeUint32LE(value: number): void;
    /**
     *
     * @param {Uint32Array|number[]|ArrayLike<number>} source
     * @param {number} source_offset
     * @param {number} length
     */
    writeUint32Array(source: Uint32Array | number[] | ArrayLike<number>, source_offset: number, length: number): void;
    /**
     *
     * @param {Uint8Array|Uint8ClampedArray} array
     * @param {number} source_offset
     * @param {number} length
     */
    writeBytes(array: Uint8Array | Uint8ClampedArray, source_offset: number, length: number): void;
    /**
     *
     * @param {Uint8Array} destination
     * @param {number} destination_offset
     * @param {number} length
     */
    readBytes(destination: Uint8Array, destination_offset: number, length: number): void;
    /**
     *
     * @param {string} string
     */
    writeUTF8String(string: string): void;
    /**
     *
     * @returns {string}
     */
    readUTF8String(): string;
    /**
     * Write an ASCII (American Standard Code for Information Interchange) string. If the string contains characters that are not representable by ASCII, an error will be thrown.
     * Note that ASCII only has 128 code points (characters), so this method is not suitable for representing UTF-8 strings.
     * If the string is not ASCII representable - use {@link writeUTF8String} instead.
     *
     * @see https://en.wikipedia.org/wiki/ASCII
     *
     * @param {string} string
     */
    writeASCIIString(string: string): void;
    /**
     * Read ASCII (American Standard Code for Information Interchange) characters to the buffer.
     * Input is not validated, if the string contains non-ASCII characters, the result is unspecified.
     *
     * @see https://en.wikipedia.org/wiki/ASCII
     *
     * @param {number} length maximum number of characters to read. If `null_terminated` flag is on, resulting string might be shorter than `length`
     * @param {boolean} [null_terminated] if true will stop reading when encountering 0 byte value character (NULL)
     * @returns {string}
     */
    readASCIICharacters(length: number, null_terminated?: boolean): string;
    /**
     * Represent the object as a string. Useful mainly for debugging.
     *
     * @return {string}
     */
    toString(): string;
    /**
     * Useful for debugging, outputs contents of the buffer in hex format.
     * Only includes data up to the .position
     *
     * @example
     *  const b = new BinaryBuffer();
     *  b.writeUint8(0xCA);
     *  b.writeUint8(0xFE);
     *  b.toHexString(); // "CAFE"
     *
     * @return {string}
     */
    toHexString(): string;
    /**
     * @readonly
     * @type {boolean}
     */
    readonly isBinaryBuffer: boolean;
}
import { EndianType } from "./EndianType.js";
//# sourceMappingURL=BinaryBuffer.d.ts.map