mathjslab/lib/src/MultiArray.d.ts

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

import type { TUnaryOperationLeftName, TBinaryOperationName } from './ComplexInterface';
import { ComplexType } from './Complex';
import { CharString } from './CharString';
import { Evaluator, NameTable } from './Evaluator';
import { FunctionHandle } from './FunctionHandle';
import { Structure } from './Structure';
import { NodeReturnList } from './AST';
/**
 * MultiArray Element type.
 */
type ElementType = MultiArray | ComplexType | CharString | Structure | FunctionHandle | null | undefined;
/**
 * Reduce factory function types.
 */
type ReduceComparisonType = 'lt' | 'gt';
type ReduceType = 'reduce' | 'cumulative' | 'cumcomparison' | 'comparison';
type ReduceElementType = ElementType;
type ReduceCallbackType = (prev: ReduceElementType, curr: ReduceElementType, index?: number) => ReduceElementType;
type ReduceCallbackOrComparisonType = ReduceCallbackType | ReduceComparisonType;
type ReduceInitialType = ReduceElementType;
type ReduceReduceHandlerType = (M: ReduceElementType, DIM?: ReduceElementType) => ReduceElementType;
type ReduceComparisonHandlerType = (...args: ElementType[]) => MultiArray | NodeReturnList | undefined;
type ReduceHandlerType = ReduceReduceHandlerType | ReduceComparisonHandlerType;
/**
 * # MultiArray
 *
 * Multimensional array library. This class represents common arrays and cell arrays.
 */
declare class MultiArray {
    /**
     * Dimensions property ([lines, columns, pages, blocks, ...]).
     */
    dimension: number[];
    /**
     * Dimensions excluding columns getter ([lines, pages, blocks, ...]).
     */
    get dimensionR(): number[];
    /**
     * Array content.
     */
    array: ElementType[][];
    /**
     * Type attribute.
     */
    type: number;
    static readonly isInstanceOf: (value: unknown) => value is MultiArray;
    static readonly LOGICAL: number;
    static readonly REAL: number;
    static readonly COMPLEX: number;
    static readonly STRING = 3;
    static readonly STRUCTURE = 4;
    static readonly FUNCTION_HANDLE = 5;
    /**
     * True if cell array.
     */
    isCell: boolean;
    /**
     * Parent node property.
     */
    parent: any;
    /**
     * MultiArray constructor.
     * @param shape Dimensions ([rows, columns, pages, blocks, ...]).
     * @param fill Data to fill MultiArray. The same object will be put in all elements of MultiArray.
     */
    constructor(shape?: number[], fill?: ElementType, iscell?: boolean);
    /**
     * Check if object is a scalar.
     * @param obj Any object.
     * @returns `true` if object is a scalar. false otherwise.
     */
    static readonly isScalar: (obj: unknown) => boolean;
    /**
     * Check if object is a MultiArray and it is a row vector.
     * @param obj Any object.
     * @returns `true` if object is a row vector. false otherwise.
     */
    static readonly isRowVector: (obj: unknown) => boolean;
    /**
     * Check if object is a MultiArray and it is a row vector.
     * @param obj Any object.
     * @returns `true` if object is a row vector. false otherwise.
     */
    static readonly isColumnVector: (obj: unknown) => boolean;
    /**
     * Check if object is a MultiArray and it is a row vector or a column vector.
     * @param obj Any object.
     * @returns `true` if object is a row vector or a column vector. false otherwise.
     */
    static readonly isVector: (obj: unknown) => boolean;
    /**
     * Check if object is a scalar or a 2-D MultiArray.
     * @param obj Any object.
     * @returns `true` if object is a row vector or a column vector. false otherwise.
     */
    static readonly isMatrix: (obj: unknown) => boolean;
    /**
     * Returns `true` if `obj` any one of its dimensions is zero.
     * Returns `false` otherwise.
     * @param obj Any object.
     * @returns `true` if object is an empty array.
     */
    static readonly isEmpty: (obj: unknown) => boolean;
    /**
     * Check if object is a MultiArray and it is a cell array.
     * @param obj Any object.
     * @returns `true` if object is a cell array. false otherwise.
     */
    static readonly isCellArray: (obj: unknown) => boolean;
    /**
     * Set type property in place with maximum value of array items type.
     * @param M MultiArray to set type property.
     */
    static readonly setType: (M: MultiArray) => void;
    /**
     * Test if two array are equals.
     * @param left Array<boolean | number | string>.
     * @param right Array<boolean | number | string>.
     * @returns true if two arrays are equals. false otherwise.
     */
    static readonly arrayEquals: (a: (boolean | number | string)[], b: (boolean | number | string)[]) => boolean;
    /**
     * Returns a one-based range array ([1, 2, ..., length]).
     * @param length Length or last value of range array.
     * @returns Range array.
     */
    static readonly rangeArray: (length: number) => number[];
    /**
     * Converts linear index to subscript.
     * @param dimension Dimensions of multidimensional array ([line, column, page, block, ...]).
     * @param index Zero-based linear index.
     * @returns One-based subscript ([line, column, page, block, ...]).
     */
    static readonly linearIndexToSubscript: (dimension: number[], index: number) => number[];
    /**
     * Converts subscript to linear index.
     * @param dimension Dimensions of multidimensional array ([lines, columns, pages, blocks, ...]).
     * @param subscript One-based subscript ([line, column, page, block, ...]).
     * @returns Zero-based linear index.
     */
    static readonly subscriptToLinearIndex: (dimension: number[], subscript: number[]) => number;
    /**
     * Converts linear index to MultiArray.array subscript.
     * @param row Row dimension.
     * @param column Column dimension.
     * @param index Zero-based linear index.
     * @returns MultiArray.array subscript ([row, column]).
     */
    static readonly linearIndexToMultiArrayRowColumn: (row: number, column: number, index: number) => [number, number];
    /**
     * Converts MultiArray subscript to MultiArray.array subscript.
     * @param dimension MultiArray dimension.
     * @param subscript Subscript.
     * @returns MultiArray.array subscript ([row, column]).
     */
    static readonly subscriptToMultiArrayRowColumn: (dimension: number[], subscript: number[]) => [number, number];
    /**
     * Converts MultiArray raw row and column to MultiArray linear index.
     * @param dimension MultiArray dimension (can be only the two first dimensions)
     * @param i Raw row
     * @param j Raw column
     * @returns Linear index
     */
    static readonly rowColumnToLinearIndex: (dimension: number[], i: number, j: number) => number;
    /**
     * Compute stride vector (column-major order).
     * Example: [3,4,2] → [1, 3, 12]
     */
    static readonly computeStrides: (dim: number[]) => number[];
    /**
     *
     * @param M
     * @param dim
     * @returns
     */
    static readonly getStride: (M: MultiArray, dim: number) => number;
    /**
     * Returns a 2D slice corresponding to page k (for 3D+ arrays).
     * @param M
     * @param pageIndex
     * @returns
     */
    static readonly pageSlice: (M: MultiArray, pageIndex: number) => ComplexType[][];
    /**
     * Sets the 2D pageIndex page in an N-D (row-major) MultiArray.
     * @param M
     * @param pageIndex
     * @param pageData
     */
    static readonly setPage: (M: MultiArray, pageIndex: number, pageData: ComplexType[][]) => void;
    /**
     * Returns content as 1D array (column-major linear order), length = product(dimension).
     * @param arr
     * @returns
     */
    static readonly toFlatArray: (arr: MultiArray) => ComplexType[];
    /**
     * Reconstructs arr.array (2D physical storage) from the column-major linear vector.
     * @param arr
     * @param flat
     */
    static readonly fromFlatArray: (arr: MultiArray, flat: ComplexType[]) => void;
    /**
     * Check if two MultiArrays have the same shape, or if they are identical
     * except for one dimension d where both have size 3.
     *
     * Returns true if either:
     *  - A.dimension equals B.dimension (exact match), or
     *  - there exists an index d such that A.dimension[d] === 3 and B.dimension[d] === 3
     *    and for every i !== d we have A.dimension[i] === B.dimension[i].
     *
     * This matches the requirement of cross(A,B) where the operation dimension
     * must have length 3 while all other dimensions must match.
     * @param A
     * @param B
     * @returns
     */
    static readonly sameSizeExcept: (A: MultiArray, B: MultiArray) => boolean;
    /**
     * Base method of the ind2sub function. Returns dimension.length + 1
     * dimensions. If the index exceeds the dimensions, the last dimension
     * will contain the multiplier of the other dimensions. Otherwise it will
     * be 1.
     * @param dimension Array of dimensions.
     * @param index One-base linear index.
     * @returns One-based subscript ([line, column, page, block, ...]).
     */
    static readonly ind2subNumber: (dimension: number[], index: number) => number[];
    /**
     * Returns the number of elements in M.
     * @param M Multidimensional array.
     * @returns Number of elements in M.
     */
    static readonly linearLength: (M: MultiArray) => number;
    /**
     * Get dimension at index d of MultiArray M
     * @param M MultiArray.
     * @param d Zero-based dimension index.
     * @returns Dimension d.
     */
    static readonly getDimension: (M: MultiArray, d: number) => number;
    /**
     * Remove singleton tail of dimension array in place.
     * @param dimension Dimension array.
     */
    static readonly removeSingletonTail: (dimension: number[]) => void;
    /**
     * Append singleton tail of dimension array in place.
     * @param dimension Dimension array.
     * @param length Resulting length of dimension array.
     */
    static readonly appendSingletonTail: (dimension: number[], length: number) => void;
    /**
     * Find first non-single dimension.
     * @param M MultiArray.
     * @returns First non-single dimension of `M`.
     */
    static readonly firstNonSingleDimension: (M: MultiArray) => number;
    /**
     * Creates a MultiArray object from the first row of elements (for
     * parsing purposes).
     * @param row Array of objects.
     * @returns MultiArray with `row` parameter as first line.
     */
    static readonly firstRow: (row: ElementType[], iscell?: boolean) => MultiArray;
    /**
     * Append a row of elements to a MultiArray object (for parsing
     * purposes).
     * @param M MultiArray.
     * @param row Array of objects to append as row of MultiArray.
     * @returns MultiArray with row appended.
     */
    static readonly appendRow: (M: MultiArray, row: ElementType[]) => MultiArray;
    /**
     * Unparse MultiArray.
     * @param M MultiArray object.
     * @returns String of unparsed MultiArray.
     */
    static readonly unparse: (M: MultiArray, evaluator: Evaluator, parentPrecedence?: number) => string;
    /**
     * Unparse MultiArray as MathML language.
     * @param M MultiArray object.
     * @returns String of unparsed MultiArray in MathML language.
     */
    static readonly unparseMathML: (M: MultiArray, evaluator: Evaluator, parentPrecedence?: number) => string;
    /**
     * Converts CharString to MultiArray.
     * @param text CharString.
     * @returns MultiArray with character codes as integer.
     */
    static readonly fromCharString: (text: CharString) => MultiArray;
    /**
     * Linearize MultiArray in an array of ElementType using row-major
     * order.
     * @param M
     * @returns
     */
    static readonly flatten: (M: MultiArray) => ElementType[];
    /**
     * Linearize MultiArray in an array of ElementType using column-major
     * order.
     * @param M Multidimensional array.
     * @returns `ElementType[]` of multidimensional array `M` linearized.
     */
    static readonly linearize: (M: ElementType) => ElementType[];
    /**
     * Returns a empty array (0x0 matrix).
     * @returns Empty array (0x0 matrix).
     */
    static readonly emptyArray: (iscell?: boolean) => MultiArray;
    /**
     * Convert scalar to MultiArray with aditional test if it is MultiArray.
     * @param value
     * @param test
     * @returns
     */
    private static readonly scalarToMultiArrayWithTest;
    /**
     * If value is a scalar then convert to a 1x1 MultiArray. If is cell array
     * the cell is put in a 1x1 MultiArray too.
     * @param value MultiArray or scalar.
     * @returns MultiArray 1x1 if value is scalar.
     */
    static readonly scalarToMultiArray: (value: ElementType) => MultiArray;
    /**
     * If value is a scalar then convert to a 1x1 MultiArray. If is common
     * array or cell array returns `value` unchanged.
     * @param value MultiArray or scalar.
     * @returns MultiArray 1x1 if value is scalar.
     */
    static readonly scalarOrCellToMultiArray: (value: ElementType) => MultiArray;
    /**
     * If `value` parameter is a MultiArray of size 1x1 then returns as scalar.
     * @param value MultiArray or scalar.
     * @returns Scalar value if `value` parameter has all dimensions as singular.
     */
    static readonly MultiArrayToScalar: (value: ElementType) => ElementType;
    /**
     * If `value` parameter is a non empty MultiArray returns it's first element.
     * Otherwise returns `value` parameter.
     * @param value
     * @returns
     */
    static readonly firstElement: (value: ElementType) => ElementType;
    /**
     * If M is a line vector then return the line of M else return first column of M.
     * @param M
     * @returns
     */
    static readonly firstVector: (M: ElementType) => ElementType[];
    /**
     * Copy of MultiArray.
     * @param M MultiArray.
     * @returns Copy of MultiArray.
     */
    static readonly copy: (M: MultiArray) => MultiArray;
    /**
     * Copy method (for element's generics).
     * @returns
     */
    copy(): MultiArray;
    /**
     * Convert MultiArray to logical value. It's true if all elements is
     * non-null. Otherwise is false.
     * @param M
     * @returns
     */
    static readonly toLogical: (M: MultiArray) => ComplexType;
    /**
     * toLogical method (for element's generics).
     * @returns
     */
    toLogical(): ComplexType;
    /**
     * Expand Multidimensional array dimensions if dimensions in `dim` is greater than dimensions of `M`.
     * If a dimension of `M` is greater than corresponding dimension in `dim` it's unchanged.
     * The array is filled with zeros and is expanded in place.
     * @param M Multidimensional array.
     * @param dim New dimensions.
     */
    static readonly expand: (M: MultiArray, dim: number[]) => void;
    /**
     * Reshape an array acording dimensions in `dim`.
     * @param M MultiArray.
     * @param dim Result dimensions.
     * @param d Undefined dimension index (optional).
     * @returns
     */
    static readonly reshape: (M: MultiArray, dim: number[], d?: number) => MultiArray;
    /**
     * Expand range.
     * @param startNode Start of range.
     * @param stopNode Stop of range.
     * @param strideNode Optional stride value.
     * @returns MultiArray of range expanded.
     */
    static readonly expandRange: (start: ComplexType, stop: ComplexType, stride?: ComplexType | null) => MultiArray;
    /**
     * Expand colon to a column vector.
     * @param length
     * @returns
     */
    static readonly expandColon: (length: number) => MultiArray;
    /**
     * Detect whether MultiArray `M` contains any non-zero imaginary part.
     * @param M MultiArray to test.
     * @returns `true` if any element has non-zero imaginary component.
     * `false` otherwise.
     */
    static readonly haveAnyComplex: (M: MultiArray) => boolean;
    /**
     * Check if subscript is a integer number, convert Complex to
     * number.
     * @param k Index as Complex.
     * @param prefix Optional id reference of object.
     * @returns k as number, if real part is integer greater than 1 and imaginary part is 0.
     */
    static readonly testInteger: (k: ComplexType, prefix?: string, infix?: string, constraint?: number | [number, number]) => number;
    /**
     * Check if subscript is a integer number, convert Complex to
     * number.
     * @param k Index as Complex.
     * @param input Optional id reference of object.
     * @returns k as number, if real part is integer greater than 1 and imaginary part is 0.
     */
    static readonly testIndex: (k: ComplexType, input?: string) => number;
    /**
     * Check if subscript is a integer number, convert Complex to
     * number, then check if it's less than bound.
     * @param k Index as Complex.
     * @param bound Maximum acceptable value for the index
     * @param dim Dimensions (to generate error message)
     * @param input Optional string to generate error message.
     * @returns Index as number.
     */
    static readonly testIndexBound: (k: ComplexType, bound: number, dim: number[], input?: string) => number;
    /**
     * Converts subscript to linear index. Performs checks and throws
     * comprehensive errors if dimension bounds are exceeded.
     * @param dimension Dimension of multidimensional array ([line, column, page, block, ...]) as number[].
     * @param subscript Subscript ([line, column, page, block, ...]) as a Complex[].
     * @param input Input string to generate error messages (the id of array).
     * @returns linear index.
     */
    static readonly parseSubscript: (dimension: number[], subscript: ComplexType[], input?: string, evaluator?: Evaluator) => number;
    /**
     * Binary operation 'scalar `operation` array'.
     * @param op Binary operation name.
     * @param left Left operand (scalar).
     * @param right Right operand (array).
     * @returns Result of operation.
     */
    static readonly scalarOpMultiArray: (op: TBinaryOperationName, left: ComplexType, right: MultiArray) => MultiArray;
    /**
     * Binary operation 'array `operation` scalar'.
     * @param op Binary operation name.
     * @param left Left operand (array).
     * @param right Right operaand (scalar).
     * @returns Result of operation.
     */
    static readonly MultiArrayOpScalar: (op: TBinaryOperationName, left: MultiArray, right: ComplexType) => MultiArray;
    /**
     * Unary left operation.
     * @param op Unary operation name.
     * @param right Operand (array)
     * @returns Result of operation.
     */
    static readonly leftOperation: (op: TUnaryOperationLeftName, right: MultiArray) => MultiArray;
    /**
     * Binary element-wise operation with full MATLAB-compatible broadcasting.
     * Supports N-D arrays and row/column vector expansion.
     * @param op Binary operation.
     * @param left Left operand.
     * @param right Right operand.
     * @returns Binary element-wise result.
     */
    static readonly elementWiseOperation: (op: TBinaryOperationName, left: MultiArray, right: MultiArray) => MultiArray;
    /**
     * Calls a defined callback function on each element of an MultiArray,
     * and returns an MultiArray that contains the results.
     * @param M MultiArray.
     * @param callback Callback function.
     * @returns A new MultiArray with each element being the result of the callback function.
     */
    static readonly rawMap: (M: MultiArray, callback: Function) => MultiArray;
    /**
     * Calls a defined callback function on each element of an MultiArray,
     * and returns an MultiArray that contains the results. Pass indices
     * to callback function. The index parameter is the array linear index
     * of element parameter.
     * @param M MultiArray
     * @param callback Callback function.
     * @returns A new MultiArray with each element being the result of the callback function.
     */
    static readonly rawMapRowColumn: (M: MultiArray, callback: (element: ElementType, i: number, j: number) => ElementType) => MultiArray;
    /**
     * Calls a defined callback function on each element of an MultiArray,
     * and returns an MultiArray that contains the results. Pass indices
     * to callback function. The index parameter is the array linear index
     * of element parameter.
     * @param M MultiArray.
     * @param callback Callback function.
     * @returns A new MultiArray with each element being the result of the callback function.
     */
    static readonly rawMapLinearIndex: (M: MultiArray, callback: (element: ElementType, index: number, i?: number, j?: number) => ElementType) => MultiArray;
    /**
     * Calls a defined callback function on each element of an MultiArray,
     * along a specified dimension, and returns an MultiArray that contains
     * the results. Pass dimension index and MultiArray row and column to
     * callback function.
     * @param dimension Dimension to map.
     * @param M MultiArray
     * @param callback Callback function.
     * @returns A new MultiArray with each element being the result of the callback function.
     */
    static readonly alongDimensionMap: (dimension: number, M: MultiArray, callback: (element: ElementType, d: number, i: number, j: number) => ElementType) => MultiArray;
    /**
     *
     * @param M
     * @param DIM
     * @returns
     */
    static readonly sizeAlongDimension: (M: MultiArray, DIM?: ElementType) => number;
    /**
     * Returns the element at the given index along the specified dimension.
     * @param M MultiArray instance
     * @param dimension Dimension index (0-based)
     * @param index Index along the dimension (0-based)
     * @returns ElementType
     */
    static readonly getElementAlongDimension: (M: MultiArray, dimension: number, index: number) => ElementType;
    /**
     *
     * @param elem
     * @param scalar
     * @returns
     */
    static readonly divideElementByScalar: (elem: ElementType, scalar: ComplexType) => ElementType;
    /**
     *
     * @param meanElem
     * @param dim
     * @param d
     * @returns
     */
    static readonly getMeanElementForPosition: (meanElem: ElementType, dim: number, d: number) => ElementType;
    /**
     * Reduce one dimension of MultiArray putting entire dimension in one
     * element of resulting MultiArray as an Array. The resulting MultiArray
     * cannot be unparsed or used as argument of any other method of
     * MultiArray class.
     * @param dimension Dimension to reduce to Array
     * @param M MultiArray to be reduced.
     * @returns MultiArray reduced.
     */
    static readonly reduceToArray: (dimension: number, M: MultiArray) => MultiArray;
    /**
     * Contract MultiArray along `dimension` calling callback. This method is
     * analogous to the JavaScript Array.reduce function.
     * @param dimension Dimension to operate callback and contract.
     * @param M Multidimensional array.
     * @param callback Reduce function.
     * @param initial Optional initial value to set as previous in the first
     * call of callback. If not set the previous will be set to the first
     * element of dimension.
     * @returns Multiarray with `dimension` reduced using `callback`.
     */
    static readonly reduce: (dimension: number, M: MultiArray, callback: (previous: ElementType, current: ElementType, index?: number) => ElementType, initial?: ElementType) => ElementType;
    /**
     * Return the concatenation of N-D array objects, ARRAY1, ARRAY2, ...,
     * ARRAYN along `dimension` parameter (zero-based).
     * @param dimension Dimension of concatenation.
     * @param fname Function name (for error messages).
     * @param ARRAY Arrays to concatenate.
     * @returns Concatenated arrays along `dimension` parameter.
     */
    static readonly concatenate: (dimension: number, fname: string, ...ARRAY: MultiArray[]) => MultiArray;
    /**
     * Split the MultiArray in the last dimension.
     * @param M
     * @returns
     */
    private static splitLastDimension;
    /**
     * Calls `splitLastDimension` and recursively calls `evaluate` for each
     * result, concatenating on the last dimension, until the array is 2-D,
     * then then concatenates the elements row by row horizontally, then
     * concatenates the rows vertically.
     * @param M MultiArray object.
     * @param evaluator Evaluator instance.
     * @param local Local context (function evaluation).
     * @param fname Function name (context).
     * @returns Evaluated MultiArray object.
     */
    private static evaluateRecursive;
    /**
     * Wrapper to not pass the null array to `MultiArray.evaluatorRecursive`.
     * @param M MultiArray object.
     * @param evaluator Evaluator instance.
     * @param local Local context (function evaluation).
     * @param fname Function name (context).
     * @returns Evaluated MultiArray object.
     */
    static readonly evaluate: (M: MultiArray, evaluator?: Evaluator | null | undefined, local?: boolean, fname?: string) => MultiArray;
    /**
     * Get selected items from MultiArray by linear indices or subscripts.
     * @param M MultiArray.
     * @param id Identifier.
     * @param indexList Linear index or subscript.
     * @returns MultiArray of selected items.
     */
    static readonly getElements: (M: MultiArray, id: string, field: string[], indexList: (ComplexType | MultiArray)[]) => ElementType;
    /**
     * Get selected items from MultiArray by logical indexing.
     * @param M MultiArray.
     * @param id Identifier.
     * @param items Logical index.
     * @returns MultiArray of selected items.
     */
    static readonly getElementsLogical: (M: MultiArray, id: string, field: string[], items: MultiArray) => ElementType;
    /**
     * Set selected items from MultiArray by linear index or subscripts.
     * @param nameTable Name Table.
     * @param id Identifier.
     * @param args Linear indices or subscripts.
     * @param right Value to assign.
     */
    static readonly setElements: (nameTable: NameTable, id: string, field: string[], indexList: (ComplexType | MultiArray)[], right: MultiArray, input?: string, evaluator?: Evaluator) => void;
    /**
     * Set selected items from MultiArray by logical indexing.
     * @param nameTable Name Table.
     * @param id Identifier.
     * @param arg Logical index.
     * @param right Value to assign.
     */
    static readonly setElementsLogical: (nameTable: NameTable, id: string, field: string[], arg: ComplexType[], right: MultiArray) => void;
    /**
     * Factory function that creates MATLAB-compatible reduction functions
     * (e.g., sum, prod, min, max, all, any) using MultiArray.reduce.
     * @param callback Binary operation applied elementwise along dimension.
     * @param type
     * @param initial Optional initial value for reduction.
     * @returns A function (M, DIM?) -> ElementType or MultiArray
     */
    static readonly reduceFactory: (callback: ReduceCallbackOrComparisonType, type: ReduceType, initial?: ReduceInitialType) => ReduceHandlerType;
}
export { type ElementType, MultiArray };
declare const _default: {
    MultiArray: typeof MultiArray;
};
export default _default;