enhance-data-view/dist/types/define-string.d.ts

Reactive DataView extension with chainable API for type-safe binary data manipulation.

import type { TypeDefinition } from "./core";
/** Defines encoding/decoding operations for string data */
export interface StringCoder {
    /** Converts string to byte array */
    encode: (string: string) => Uint8Array;
    /** Converts byte array to string */
    decode: (buffer: Uint8Array) => string;
}
/** Default UTF-8 encoder/decoder implementation */
export declare const DefaultStringCoder: StringCoder;
/**
 * Immutable string type definition (frozen state)
 */
export interface StringDefinitionFreezed extends TypeDefinition<string> {
    /** Padding byte value (if defined) */
    filler: number | undefined;
    /** Encoding/decoding implementation */
    coder: StringCoder;
    /**
     * Creates a mutable clone
     * @param name - Optional new name for cloned definition
     * @returns Mutable string definition
     */
    clone(name?: string): StringDefinition;
}
/**
 * Configurable string type definition
 * @remarks
 * - Supports custom encodings and padding behavior
 * - Fixed-length representation in binary data
 */
export interface StringDefinition extends StringDefinitionFreezed {
    /**
     * Sets type name
     * @param name - New name for the type
     * @returns Current instance for chaining
     */
    setName(name?: string): StringDefinition;
    /**
     * Sets fixed byte size
     * @param size - Byte length of string field
     * @returns Current instance for chaining
     * @remarks Determines maximum encoded length
     */
    setSize(size?: number): StringDefinition;
    /**
     * Sets memory alignment requirement
     * @param align - Alignment requirement
     * @returns Current instance for chaining
     * @defaultValue 1 (byte-aligned)
     */
    setAlign(align?: number): StringDefinition;
    /**
     * Sets padding behavior
     * @param filler - Byte value (0-255) for padding:
     * - When writing: Fills remaining space after encoding
     * - When reading: Stops decoding at first occurrence
     * @returns Current instance for chaining
     * @remarks
     * - Set to `undefined` to disable padding behavior
     * - Default: `undefined` (no padding)
     * @example
     * .setFiller(0) // Null-terminated string behavior
     */
    setFiller(filler?: number): StringDefinition;
    /**
     * Sets custom encoding implementation
     * @param coder - Encoding/decoding implementation
     * @returns Current instance for chaining
     * @defaultValue UTF-8 encoder
     */
    setCoder(coder?: StringCoder): StringDefinition;
    /**
     * Freezes the type definition to prevent modification
     * @returns Immutable version of the type definition
     * @remarks
     * - Improves performance by preventing runtime changes
     * - Should be called after final configuration
     * @example
     * const finalType = mutableType.freeze();
     */
    freeze(): StringDefinitionFreezed;
}
/**
 * Creates configurable string type definition
 * @overload
 * @param name - Type name
 * @returns Empty string definition (size=0, no filler)
 */
export declare function defineString(name?: string): StringDefinition;
/**
 * Creates configurable string type definition
 * @overload
 * @param size - Fixed byte size
 * @param filler - Padding byte value (0-255)
 * @param name - Optional type name
 * @returns Preconfigured string definition
 * @example
 * // Null-terminated 32-byte string
 * const NTString = defineString(32, 0, 'NullTerminated');
 */
export declare function defineString(size: number, filler?: number, name?: string): StringDefinition;