mathjslab/lib/types/Structure.d.ts

MathJSLab - An interpreter with language syntax like MATLAB®/Octave, ISBN 978-65-00-82338-7.

import { ComplexType } from './Complex';
import { type ElementType, MultiArray } from './MultiArray';
import type { RuntimeDisplay } from './RuntimeDisplay';
/** Concrete runtime value that may be stored in a structure field. */
type StructureFieldValue = Exclude<ElementType, null | undefined>;
/**
 * Runtime representation of a MATLAB/Octave structure scalar.
 *
 * Structure arrays are represented as `MultiArray` values whose elements are
 * `Structure` instances. A scalar `Structure` stores fields in a plain object
 * keyed by field name.
 */
declare class Structure {
    /** Runtime type tag used by interpreter predicates. */
    static readonly STRUCTURE = 4;
    /** Runtime type tag stored on the structure value. */
    readonly type = 4;
    /** Optional AST-style parent pointer used by generic value handling. */
    parent?: unknown;
    /** Field storage keyed by field name. */
    field: Record<string, StructureFieldValue>;
    /** Shared diagnostic for invalid dot-indexing targets. */
    private static readonly invalidReferenceMessage;
    /**
     * Test whether an object is a `Structure` instance.
     *
     * @param obj Object to test.
     * @returns `true` when `obj` is a `Structure`.
     */
    static isInstanceOf: (obj: unknown) => obj is Structure;
    /**
     * Structure constructor. If an object is passed as parameter then create
     * a Structure with same fields and values of object. If an array of field
     * names as string is passed then create a Structure with this field
     * branch and nested field value set to empty array.
     *
     * @param field An object with fields and values or an array of field names.
     */
    constructor(field: Record<string, StructureFieldValue> | string[]);
    /**
     * Return the structure elements stored by a scalar or non-empty structure
     * array.
     *
     * @param obj Value to inspect.
     * @returns Structure elements in linear order, or an empty list when the
     * value is not structurally a MATLAB structure array.
     */
    static structureElements: (obj: ElementType) => Structure[];
    /**
     * Test whether a value is a structure scalar or non-empty structure array.
     *
     * @param obj Value to test.
     * @returns `true` when the value can be dot-indexed as a structure.
     */
    static isStructure: (obj: ElementType) => boolean;
    /**
     * Return sorted field names for a structure scalar or structure array.
     *
     * MATLAB structure arrays share a field schema. The first element therefore
     * provides the visible field-name list after callers have validated the
     * value as a structure.
     *
     * @param obj Structure scalar or structure array.
     * @returns Sorted field names, or an empty list for non-structures.
     */
    static fieldNames: (obj: ElementType) => string[];
    /**
     * Test whether every element in a structure scalar/array defines a field.
     *
     * @param obj Structure scalar or structure array.
     * @param field Field name to test.
     * @returns `true` when all structure elements define `field`.
     */
    static hasField: (obj: ElementType, field: string) => boolean;
    /**
     * Test whether a value should create a missing intermediate field.
     *
     * @param value Existing field value.
     * @returns `true` for missing or empty-array values.
     */
    private static isMissingOrEmpty;
    /**
     * Resolve or create an intermediate value that supports further dot access.
     *
     * @param value Existing intermediate field value.
     * @returns Structure scalar or structure array ready for nested assignment.
     * @throws EvalError when the existing value cannot be dot-indexed.
     */
    private static ensureStructureLike;
    /**
     * Assign a field path inside a structure scalar or every element of a
     * structure array.
     *
     * @param target Structure scalar or structure array to mutate.
     * @param field Field path to assign.
     * @param value Value to store, or an empty array when omitted.
     */
    private static assignFieldPath;
    /**
     * Collect values reached by a nested field path.
     *
     * @param obj Structure scalar or structure array to read from.
     * @param field Field path to resolve.
     * @returns Values reached by the path in linear order.
     * @throws EvalError when any target cannot be dot-indexed.
     */
    private static collectFieldPath;
    /**
     * Assign a nested field path, replacing intermediate values with
     * structures.
     *
     * @param S Structure scalar or structure array to mutate.
     * @param field Field path to assign.
     * @param value Value to store, or an empty array when omitted.
     */
    static setField: (S: Structure | MultiArray, field: string[], value?: StructureFieldValue) => void;
    /**
     * Assign a nested field path while preserving existing non-structure values.
     *
     * @param S Structure scalar or structure array to mutate.
     * @param field Field path to assign.
     * @param value Value to store, or an empty array when omitted.
     * @throws EvalError when an intermediate field cannot be dot-indexed.
     */
    static setNewField: (S: Structure | MultiArray, field: string[], value?: StructureFieldValue) => void;
    /**
     * Read a nested field path from a structure scalar.
     *
     * @param obj Value to read from.
     * @param field Field path to resolve.
     * @returns Field value.
     * @throws EvalError when the target or path cannot be dot-indexed.
     */
    static getField: (obj: ElementType, field: string[]) => StructureFieldValue;
    /**
     * Read a nested field path from a structure scalar or structure array.
     *
     * @param obj Structure scalar or structure array.
     * @param field Field path to resolve.
     * @returns Field values in linear order.
     */
    static getFields: (obj: ElementType, field: string[]) => StructureFieldValue[];
    /**
     * Return a copy of a structure scalar or structure array without selected
     * fields.
     *
     * @param obj Structure scalar or structure array.
     * @param fields Field names to remove from every structure element.
     * @returns Copied structure value with the requested fields removed.
     * @throws EvalError when `obj` is not a structure.
     */
    static removeFields: (obj: Structure | MultiArray, fields: string[]) => Structure | MultiArray;
    /**
     * Return a copy of a structure scalar or structure array with fields sorted
     * alphabetically.
     *
     * @param obj Structure scalar or structure array.
     * @returns Copied structure value with deterministic top-level field order.
     * @throws EvalError when `obj` is not a structure.
     */
    static orderFields: (obj: Structure | MultiArray) => Structure | MultiArray;
    /**
     * Render a structure as source-like text.
     *
     * @param S Structure to render.
     * @param interpreter Interpreter that owns the unparser.
     * @param _parentPrecedence Parent operator precedence, unused.
     * @returns Source-like structure representation.
     */
    static unparse: (S: Structure, interpreter: RuntimeDisplay, _parentPrecedence?: number) => string;
    /**
     * Render a structure as MathML.
     *
     * @param S Structure to render.
     * @param interpreter Interpreter that owns the MathML unparser.
     * @param _parentPrecedence Parent operator precedence, unused.
     * @returns MathML table fragment.
     */
    static unparseMathML: (S: Structure, interpreter: RuntimeDisplay, _parentPrecedence?: number) => string;
    /**
     * Deep-copy a structure scalar.
     *
     * @param S Structure to copy.
     * @returns Copied structure with copied field values.
     */
    static copy: (S: Structure) => Structure;
    /**
     * Deep-copy this structure scalar.
     *
     * @returns Copied structure.
     */
    copy(): Structure;
    /**
     * Clone only the field names of a structure, filling every field with an
     * empty array.
     *
     * @param S Structure whose field names should be cloned.
     * @returns Structure with the same field names and empty values.
     */
    static cloneFields: (S: Structure) => Structure;
    /**
     * Convert a structure to a logical scalar.
     *
     * @param S Structure to convert.
     * @returns `true` when the structure has at least one field.
     */
    static toLogical: (S: Structure) => ComplexType;
    /**
     * Convert this structure to a logical scalar.
     *
     * @returns `true` when this structure has at least one field.
     */
    toLogical(): ComplexType;
    /**
     * Add an empty field to every element of a structure array when the field
     * does not already exist.
     *
     * @param M Structure array to mutate.
     * @param field Field name to add.
     * @throws EvalError when the array does not contain structures.
     */
    static setEmptyField: (M: MultiArray, field: string) => void;
}
export { Structure };
export type { StructureFieldValue };
declare const _default: {
    Structure: typeof Structure;
};
export default _default;