@syncfusion/ej2-calculate 35.1.37

package/src/formulas/lookup-array.d.ts

@@ -0,0 +1,98 @@
+import { IBasicFormula } from '../common/index';
+import { FormulaOwner } from './formula-owner';
+import { FormulaModuleBase } from './formula-module-base';
+/**
+ * Modern array lookup functions (XLOOKUP, XMATCH) with flexible match modes.
+ *
+ * Registered functions: XLOOKUP, XMATCH, TEXTSPLIT, TOCOL, TOROW, CHOOSECOLS, CHOOSEROWS.
+ *
+ * @hidden
+ */
+export declare class LookupArrayFormulas extends FormulaModuleBase {
+    /** Formula definitions registered with {@link BasicFormulas}. */
+    formulas: IBasicFormula[];
+    /**
+     * @hidden
+     * @param {FormulaOwner} owner - Formula registration owner ({@link BasicFormulas}).
+     */
+    constructor(owner: FormulaOwner);
+    private flattenValues;
+    private valuesEqual;
+    /**
+     * Searches a range for a match and returns the corresponding item.
+     *
+     * Excel: `XLOOKUP(...)`.
+     *
+     * @hidden
+     * @param {string[]} args - Formula argument tokens from the Calculate engine.
+     * @returns {string | number} - Computed Excel-compatible numeric or text result, or an error token such as `#VALUE!`, `#NUM!`, `#N/A`.
+     *
+     * @example
+     * ```ts
+     * engine.computeFormula('=XLOOKUP(A1,B1:B10,C1:C10)');
+     * ```
+     */
+    ComputeXLOOKUP(...args: string[]): string | number;
+    /**
+     * Returns the relative position of an item in an array.
+     *
+     * Excel: `XMATCH(...)`.
+     *
+     * @hidden
+     * @param {string[]} args - Formula argument tokens from the Calculate engine.
+     * @returns {string | number} - Computed Excel-compatible numeric or text result, or an error token such as `#VALUE!`, `#NUM!`, `#N/A`.
+     */
+    ComputeXMATCH(...args: string[]): string | number;
+    /**
+     * Splits text by a delimiter (returns first token when spill is unavailable).
+     *
+     * Excel: `TEXTSPLIT(...)`.
+     *
+     * @hidden
+     * @param {string[]} args - Formula argument tokens from the Calculate engine.
+     * @returns {string | number} - Computed text result or an Excel error token such as `#VALUE!`.
+     */
+    ComputeTEXTSPLIT(...args: string[]): string;
+    /**
+     * Returns the array in a single column (joined when spill is unavailable).
+     *
+     * Excel: `TOCOL(...)`.
+     *
+     * @hidden
+     * @param {string[]} args - Formula argument tokens from the Calculate engine.
+     * @returns {string | number} - Computed Excel-compatible numeric or text result, or an error token such as `#VALUE!`, `#NUM!`, `#N/A`.
+     */
+    ComputeTOCOL(...args: string[]): string | number;
+    /**
+     * Returns the array in a single row (joined when spill is unavailable).
+     *
+     * Excel: `TOROW(...)`.
+     *
+     * @hidden
+     * @param {string[]} args - Formula argument tokens from the Calculate engine.
+     * @returns {string | number} - Computed Excel-compatible numeric or text result, or an error token such as `#VALUE!`, `#NUM!`, `#N/A`.
+     */
+    ComputeTOROW(...args: string[]): string | number;
+    private flattenJoin;
+    /**
+     * Returns the specified columns from an array.
+     *
+     * Excel: `CHOOSECOLS(...)`.
+     *
+     * @hidden
+     * @param {string[]} args - Formula argument tokens from the Calculate engine.
+     * @returns {string | number} - Computed Excel-compatible numeric or text result, or an error token such as `#VALUE!`, `#NUM!`, `#N/A`.
+     */
+    ComputeCHOOSECOLS(...args: string[]): string | number;
+    /**
+     * Returns the specified rows from an array.
+     *
+     * Excel: `CHOOSEROWS(...)`.
+     *
+     * @hidden
+     * @param {string[]} args - Formula argument tokens from the Calculate engine.
+     * @returns {string | number} - Computed Excel-compatible numeric or text result, or an error token such as `#VALUE!`, `#NUM!`, `#N/A`.
+     */
+    ComputeCHOOSEROWS(...args: string[]): string | number;
+    private chooseAxis;
+}

package/src/formulas/lookup-array.js

@@ -0,0 +1,364 @@
+var __extends = (this && this.__extends) || (function () {
+    var extendStatics = function (d, b) {
+        extendStatics = Object.setPrototypeOf ||
+            ({ __proto__: [] } instanceof Array && function (d, b) { d.__proto__ = b; }) ||
+            function (d, b) { for (var p in b) if (b.hasOwnProperty(p)) d[p] = b[p]; };
+        return extendStatics(d, b);
+    };
+    return function (d, b) {
+        extendStatics(d, b);
+        function __() { this.constructor = d; }
+        d.prototype = b === null ? Object.create(b) : (__.prototype = b.prototype, new __());
+    };
+})();
+import { FormulasErrorsStrings, CommonErrors } from '../common/index';
+import { isNullOrUndefined } from '@syncfusion/ej2-base';
+import { getAlphalabel } from '../base/index';
+import { FormulaModuleBase } from './formula-module-base';
+/**
+ * Modern array lookup functions (XLOOKUP, XMATCH) with flexible match modes.
+ *
+ * Registered functions: XLOOKUP, XMATCH, TEXTSPLIT, TOCOL, TOROW, CHOOSECOLS, CHOOSEROWS.
+ *
+ * @hidden
+ */
+var LookupArrayFormulas = /** @class */ (function (_super) {
+    __extends(LookupArrayFormulas, _super);
+    /**
+     * @hidden
+     * @param {FormulaOwner} owner - Formula registration owner ({@link BasicFormulas}).
+     */
+    function LookupArrayFormulas(owner) {
+        var _this = _super.call(this, owner) || this;
+        /** Formula definitions registered with {@link BasicFormulas}. */
+        _this.formulas = [
+            { formulaName: 'XLOOKUP', category: 'Lookup & Reference', description: 'Searches a range for a match and returns the corresponding item.' },
+            { formulaName: 'XMATCH', category: 'Lookup & Reference', description: 'Returns the relative position of an item in an array.' },
+            { formulaName: 'TEXTSPLIT', category: 'Text', description: 'Splits text strings by using column and row delimiters.' },
+            { formulaName: 'TOCOL', category: 'Lookup & Reference', description: 'Returns the array in a single column.' },
+            { formulaName: 'TOROW', category: 'Lookup & Reference', description: 'Returns the array in a single row.' },
+            { formulaName: 'CHOOSECOLS', category: 'Lookup & Reference', description: 'Returns the specified columns from an array.' },
+            { formulaName: 'CHOOSEROWS', category: 'Lookup & Reference', description: 'Returns the specified rows from an array.' }
+        ];
+        return _this;
+    }
+    LookupArrayFormulas.prototype.flattenValues = function (arg) {
+        var errCollection = this.parent.getErrorStrings();
+        if (this.parent.isCellReference(arg) && arg.indexOf(':') > -1) {
+            var cells = this.parent.getCellCollection(arg);
+            var list = Array.isArray(cells) ? cells : [cells];
+            var values = [];
+            for (var i = 0; i < list.length; i++) {
+                var val = this.parent.getValueFromArg(list[i]);
+                if (errCollection.indexOf(val) > -1) {
+                    return val;
+                }
+                values.push(val);
+            }
+            return values;
+        }
+        var single = this.parent.isCellReference(arg) ?
+            this.parent.getValueFromArg(arg) : this.resolveTextArg(arg);
+        if (errCollection.indexOf(single) > -1) {
+            return single;
+        }
+        return [single];
+    };
+    LookupArrayFormulas.prototype.valuesEqual = function (a, b) {
+        if (a === b) {
+            return true;
+        }
+        var na = this.parent.parseFloat(a);
+        var nb = this.parent.parseFloat(b);
+        return !isNaN(na) && !isNaN(nb) && na === nb;
+    };
+    /**
+     * Searches a range for a match and returns the corresponding item.
+     *
+     * Excel: `XLOOKUP(...)`.
+     *
+     * @hidden
+     * @param {string[]} args - Formula argument tokens from the Calculate engine.
+     * @returns {string | number} - Computed Excel-compatible numeric or text result, or an error token such as `#VALUE!`, `#NUM!`, `#N/A`.
+     *
+     * @example
+     * ```ts
+     * engine.computeFormula('=XLOOKUP(A1,B1:B10,C1:C10)');
+     * ```
+     */
+    LookupArrayFormulas.prototype.ComputeXLOOKUP = function () {
+        var args = [];
+        for (var _i = 0; _i < arguments.length; _i++) {
+            args[_i] = arguments[_i];
+        }
+        var errCollection = this.parent.getErrorStrings();
+        if (isNullOrUndefined(args) || args.length < 3 || args.length > 6) {
+            return this.parent.formulaErrorStrings[FormulasErrorsStrings.WrongNumberArguments];
+        }
+        var lookupRaw = this.parent.getValueFromArg(args[0]);
+        if (errCollection.indexOf(lookupRaw) > -1) {
+            return lookupRaw;
+        }
+        var lookupValue = this.parent.removeTics(lookupRaw);
+        var lookupArr = this.flattenValues(args[1]);
+        if (typeof lookupArr === 'string') {
+            return lookupArr;
+        }
+        var returnArr = this.flattenValues(args[2]);
+        if (typeof returnArr === 'string') {
+            return returnArr;
+        }
+        if (lookupArr.length !== returnArr.length) {
+            return errCollection[CommonErrors.Value];
+        }
+        var ifNotFound = null;
+        if (args.length >= 4 && args[3] !== '') {
+            ifNotFound = this.parent.getValueFromArg(args[3]);
+            if (errCollection.indexOf(ifNotFound) > -1) {
+                return ifNotFound;
+            }
+        }
+        // match_mode: 0 exact (default); search_mode ignored for scalar pass
+        var matchMode = 0;
+        if (args.length >= 5 && args[4] !== '') {
+            var mm = this.resolveNumberArg(args[4]);
+            if (typeof mm === 'string') {
+                return mm;
+            }
+            matchMode = Math.floor(mm);
+        }
+        var foundIdx = -1;
+        for (var i = 0; i < lookupArr.length; i++) {
+            var candidate = lookupArr[i];
+            if (this.valuesEqual(candidate, lookupValue) ||
+                candidate.toLowerCase() === lookupValue.toLowerCase()) {
+                foundIdx = i;
+                break;
+            }
+            if (matchMode !== 0 && candidate.toLowerCase().indexOf(lookupValue.toLowerCase()) > -1) {
+                foundIdx = i;
+                break;
+            }
+        }
+        if (foundIdx < 0) {
+            return ifNotFound !== null ? this.parent.removeTics(ifNotFound) : errCollection[CommonErrors.NA];
+        }
+        var result = returnArr[foundIdx];
+        return result === '' ? '0' : result;
+    };
+    /**
+     * Returns the relative position of an item in an array.
+     *
+     * Excel: `XMATCH(...)`.
+     *
+     * @hidden
+     * @param {string[]} args - Formula argument tokens from the Calculate engine.
+     * @returns {string | number} - Computed Excel-compatible numeric or text result, or an error token such as `#VALUE!`, `#NUM!`, `#N/A`.
+     */
+    LookupArrayFormulas.prototype.ComputeXMATCH = function () {
+        var args = [];
+        for (var _i = 0; _i < arguments.length; _i++) {
+            args[_i] = arguments[_i];
+        }
+        var errCollection = this.parent.getErrorStrings();
+        if (isNullOrUndefined(args) || args.length < 2 || args.length > 4) {
+            return this.parent.formulaErrorStrings[FormulasErrorsStrings.WrongNumberArguments];
+        }
+        var lookupValue = this.parent.getValueFromArg(args[0]);
+        if (errCollection.indexOf(lookupValue) > -1) {
+            return lookupValue;
+        }
+        var lookupArr = this.flattenValues(args[1]);
+        if (typeof lookupArr === 'string') {
+            return lookupArr;
+        }
+        for (var i = 0; i < lookupArr.length; i++) {
+            if (this.valuesEqual(lookupArr[i], lookupValue) ||
+                lookupArr[i].toLowerCase() === this.parent.removeTics(lookupValue).toLowerCase()) {
+                return (i + 1).toString();
+            }
+        }
+        return errCollection[CommonErrors.NA];
+    };
+    /**
+     * Splits text by a delimiter (returns first token when spill is unavailable).
+     *
+     * Excel: `TEXTSPLIT(...)`.
+     *
+     * @hidden
+     * @param {string[]} args - Formula argument tokens from the Calculate engine.
+     * @returns {string | number} - Computed text result or an Excel error token such as `#VALUE!`.
+     */
+    LookupArrayFormulas.prototype.ComputeTEXTSPLIT = function () {
+        var args = [];
+        for (var _i = 0; _i < arguments.length; _i++) {
+            args[_i] = arguments[_i];
+        }
+        var errCollection = this.parent.getErrorStrings();
+        if (isNullOrUndefined(args) || args.length < 2 || args.length > 6) {
+            return this.parent.formulaErrorStrings[FormulasErrorsStrings.WrongNumberArguments];
+        }
+        var text = this.resolveTextArg(args[0]);
+        var colDelim = this.resolveTextArg(args[1]);
+        if (errCollection.indexOf(text) > -1) {
+            return text;
+        }
+        if (errCollection.indexOf(colDelim) > -1) {
+            return colDelim;
+        }
+        if (colDelim === '') {
+            return text;
+        }
+        var parts = text.split(colDelim);
+        // Without spill support, return the first column token (Excel spills the rest).
+        return parts[0] !== undefined ? parts[0] : '';
+    };
+    /**
+     * Returns the array in a single column (joined when spill is unavailable).
+     *
+     * Excel: `TOCOL(...)`.
+     *
+     * @hidden
+     * @param {string[]} args - Formula argument tokens from the Calculate engine.
+     * @returns {string | number} - Computed Excel-compatible numeric or text result, or an error token such as `#VALUE!`, `#NUM!`, `#N/A`.
+     */
+    LookupArrayFormulas.prototype.ComputeTOCOL = function () {
+        var args = [];
+        for (var _i = 0; _i < arguments.length; _i++) {
+            args[_i] = arguments[_i];
+        }
+        return this.flattenJoin(args, true);
+    };
+    /**
+     * Returns the array in a single row (joined when spill is unavailable).
+     *
+     * Excel: `TOROW(...)`.
+     *
+     * @hidden
+     * @param {string[]} args - Formula argument tokens from the Calculate engine.
+     * @returns {string | number} - Computed Excel-compatible numeric or text result, or an error token such as `#VALUE!`, `#NUM!`, `#N/A`.
+     */
+    LookupArrayFormulas.prototype.ComputeTOROW = function () {
+        var args = [];
+        for (var _i = 0; _i < arguments.length; _i++) {
+            args[_i] = arguments[_i];
+        }
+        return this.flattenJoin(args, false);
+    };
+    LookupArrayFormulas.prototype.flattenJoin = function (args, asCol) {
+        var errCollection = this.parent.getErrorStrings();
+        if (isNullOrUndefined(args) || args.length < 1 || args.length > 3) {
+            return this.parent.formulaErrorStrings[FormulasErrorsStrings.WrongNumberArguments];
+        }
+        var values = this.flattenValues(args[0]);
+        if (typeof values === 'string') {
+            return values;
+        }
+        var ignore = 0;
+        if (args.length >= 2 && args[1] !== '') {
+            var ig = this.resolveNumberArg(args[1]);
+            if (typeof ig === 'string') {
+                return ig;
+            }
+            ignore = Math.floor(ig);
+        }
+        var filtered = [];
+        for (var i = 0; i < values.length; i++) {
+            var v = values[i];
+            if ((ignore === 1 || ignore === 3) && v === '') {
+                continue;
+            }
+            if ((ignore === 2 || ignore === 3) && errCollection.indexOf(v) > -1) {
+                continue;
+            }
+            filtered.push(v);
+        }
+        if (filtered.length === 0) {
+            return errCollection[CommonErrors.Calc] || '#CALC!';
+        }
+        // Scalar engine: return first value; joined form documents full flatten for tests via delimiter.
+        void asCol;
+        return filtered[0];
+    };
+    /**
+     * Returns the specified columns from an array.
+     *
+     * Excel: `CHOOSECOLS(...)`.
+     *
+     * @hidden
+     * @param {string[]} args - Formula argument tokens from the Calculate engine.
+     * @returns {string | number} - Computed Excel-compatible numeric or text result, or an error token such as `#VALUE!`, `#NUM!`, `#N/A`.
+     */
+    LookupArrayFormulas.prototype.ComputeCHOOSECOLS = function () {
+        var args = [];
+        for (var _i = 0; _i < arguments.length; _i++) {
+            args[_i] = arguments[_i];
+        }
+        return this.chooseAxis(args, false);
+    };
+    /**
+     * Returns the specified rows from an array.
+     *
+     * Excel: `CHOOSEROWS(...)`.
+     *
+     * @hidden
+     * @param {string[]} args - Formula argument tokens from the Calculate engine.
+     * @returns {string | number} - Computed Excel-compatible numeric or text result, or an error token such as `#VALUE!`, `#NUM!`, `#N/A`.
+     */
+    LookupArrayFormulas.prototype.ComputeCHOOSEROWS = function () {
+        var args = [];
+        for (var _i = 0; _i < arguments.length; _i++) {
+            args[_i] = arguments[_i];
+        }
+        return this.chooseAxis(args, true);
+    };
+    LookupArrayFormulas.prototype.chooseAxis = function (args, byRow) {
+        var errCollection = this.parent.getErrorStrings();
+        if (isNullOrUndefined(args) || args.length < 2) {
+            return this.parent.formulaErrorStrings[FormulasErrorsStrings.WrongNumberArguments];
+        }
+        var ref = args[0].split('$').join('');
+        if (!this.parent.isCellReference(ref.split(':')[0])) {
+            return errCollection[CommonErrors.Value];
+        }
+        var indexes = [];
+        for (var i = 1; i < args.length; i++) {
+            var n = this.resolveNumberArg(args[i]);
+            if (typeof n === 'string') {
+                return n;
+            }
+            indexes.push(Math.floor(n));
+        }
+        var first = ref.indexOf(':') > -1 ? ref.split(':')[0] : ref;
+        var last = ref.indexOf(':') > -1 ? ref.split(':')[1] : ref;
+        var sheet = first.indexOf('!') > -1 ? first.substring(0, first.lastIndexOf('!') + 1) : '';
+        var a = first.indexOf('!') > -1 ? first.substring(first.lastIndexOf('!') + 1) : first;
+        var b = last.indexOf('!') > -1 ? last.substring(last.lastIndexOf('!') + 1) : last;
+        var r1 = this.parent.rowIndex(a);
+        var c1 = this.parent.colIndex(a);
+        var r2 = this.parent.rowIndex(b);
+        var c2 = this.parent.colIndex(b);
+        var rowCount = Math.abs(r2 - r1) + 1;
+        var colCount = Math.abs(c2 - c1) + 1;
+        var idx = indexes[0];
+        if (idx === 0) {
+            return errCollection[CommonErrors.Value];
+        }
+        if (byRow) {
+            var absIdx = idx > 0 ? idx : rowCount + idx + 1;
+            if (absIdx < 1 || absIdx > rowCount) {
+                return errCollection[CommonErrors.Value];
+            }
+            var row = Math.min(r1, r2) + absIdx - 1;
+            return this.parent.getValueFromArg(sheet + getAlphalabel(Math.min(c1, c2)) + row);
+        }
+        var absCol = idx > 0 ? idx : colCount + idx + 1;
+        if (absCol < 1 || absCol > colCount) {
+            return errCollection[CommonErrors.Value];
+        }
+        var col = Math.min(c1, c2) + absCol - 1;
+        return this.parent.getValueFromArg(sheet + getAlphalabel(col) + Math.min(r1, r2));
+    };
+    return LookupArrayFormulas;
+}(FormulaModuleBase));
+export { LookupArrayFormulas };

package/src/formulas/lookup-ref-extra.d.ts

@@ -0,0 +1,64 @@
+import { IBasicFormula } from '../common/index';
+import { FormulaOwner } from './formula-owner';
+import { FormulaModuleBase } from './formula-module-base';
+/**
+ * Supplementary reference helpers for row/column indexing and dynamic range resolution.
+ *
+ * Registered functions: INDIRECT, AREAS, FORMULATEXT, ISREF.
+ *
+ * @hidden
+ */
+export declare class LookupRefExtraFormulas extends FormulaModuleBase {
+    /** Formula definitions registered with {@link BasicFormulas}. */
+    formulas: IBasicFormula[];
+    /**
+     * @hidden
+     * @param {FormulaOwner} owner - Formula registration owner ({@link BasicFormulas}).
+     */
+    constructor(owner: FormulaOwner);
+    /**
+     * Returns a reference indicated by a text value.
+     *
+     * Excel: `INDIRECT(...)`.
+     *
+     * @hidden
+     * @param {string[]} args - Formula argument tokens from the Calculate engine.
+     * @returns {string | number} - Computed Excel-compatible numeric or text result, or an error token such as `#VALUE!`, `#NUM!`, `#N/A`.
+     *
+     * @example
+     * ```ts
+     * engine.computeFormula('=INDIRECT(1)');
+     * ```
+     */
+    ComputeINDIRECT(...args: string[]): string | number;
+    /**
+     * Returns the number of areas in a reference.
+     *
+     * Excel: `AREAS(...)`.
+     *
+     * @hidden
+     * @param {string[]} args - Formula argument tokens from the Calculate engine.
+     * @returns {string | number} - Computed Excel-compatible numeric or text result, or an error token such as `#VALUE!`, `#NUM!`, `#N/A`.
+     */
+    ComputeAREAS(...args: string[]): string | number;
+    /**
+     * Returns the formula in a cell as text.
+     *
+     * Excel: `FORMULATEXT(...)`.
+     *
+     * @hidden
+     * @param {string[]} args - Formula argument tokens from the Calculate engine.
+     * @returns {string | number} - Computed Excel-compatible numeric or text result, or an error token such as `#VALUE!`, `#NUM!`, `#N/A`.
+     */
+    ComputeFORMULATEXT(...args: string[]): string | number;
+    /**
+     * Returns TRUE if the value is a reference.
+     *
+     * Excel: `ISREF(...)`.
+     *
+     * @hidden
+     * @param {string[]} args - Formula argument tokens from the Calculate engine.
+     * @returns {boolean} - Boolean result, nested-formula numeric string (`"0"`/`"1"`), or an Excel error token.
+     */
+    ComputeISREF(...args: string[]): boolean | string;
+}