@syncfusion/ej2-calculate 35.1.37

package/src/formulas/date-time-extra.js

@@ -0,0 +1,415 @@
+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 { FormulaModuleBase } from './formula-module-base';
+/**
+ * Additional date/time utilities: workdays, network days, week numbers, and calendar offsets.
+ *
+ * Registered functions: YEAR, WEEKNUM, TIMEVALUE, DAYS360, YEARFRAC, NETWORKDAYS, WORKDAY.
+ *
+ * @hidden
+ */
+var DateTimeExtraFormulas = /** @class */ (function (_super) {
+    __extends(DateTimeExtraFormulas, _super);
+    /**
+     * @hidden
+     * @param {FormulaOwner} owner - Formula registration owner ({@link BasicFormulas}).
+     */
+    function DateTimeExtraFormulas(owner) {
+        var _this = _super.call(this, owner) || this;
+        /** Formula definitions registered with {@link BasicFormulas}. */
+        _this.formulas = [
+            { formulaName: 'YEAR', category: 'Date & Time', description: 'Converts a serial number to a year.' },
+            { formulaName: 'WEEKNUM', category: 'Date & Time', description: 'Converts a serial number to a number representing where the week falls numerically within a year.' },
+            { formulaName: 'TIMEVALUE', category: 'Date & Time', description: 'Converts a time in the form of text to a serial number.' },
+            { formulaName: 'DAYS360', category: 'Date & Time', description: 'Calculates the number of days between two dates based on a 360-day year.' },
+            { formulaName: 'YEARFRAC', category: 'Date & Time', description: 'Returns the year fraction representing the number of whole days between start_date and end_date.' },
+            { formulaName: 'NETWORKDAYS', category: 'Date & Time', description: 'Returns the number of whole workdays between two dates.' },
+            { formulaName: 'WORKDAY', category: 'Date & Time', description: 'Returns the serial number of the date before or after a specified number of workdays.' }
+        ];
+        return _this;
+    }
+    DateTimeExtraFormulas.prototype.toSerial = function (arg) {
+        var errCollection = this.parent.getErrorStrings();
+        var value = this.parent.getValueFromArg(arg);
+        if (errCollection.indexOf(value) > -1) {
+            return value;
+        }
+        if (!this.parent.isCellReference(arg)) {
+            value = this.parent.removeTics(value);
+        }
+        if (value === '') {
+            return errCollection[CommonErrors.Value];
+        }
+        if (this.parent.isNumber(value)) {
+            return this.parent.parseFloat(value);
+        }
+        var parsed = this.parent.isDate(new Date(value));
+        if (parsed) {
+            return this.parent.toOADate(parsed);
+        }
+        return errCollection[CommonErrors.Value];
+    };
+    /**
+     * Converts a serial number to a year.
+     *
+     * Excel: `YEAR(...)`.
+     *
+     * @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('=YEAR(1)');
+     * ```
+     */
+    DateTimeExtraFormulas.prototype.ComputeYEAR = 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 !== 1) {
+            return this.parent.formulaErrorStrings[FormulasErrorsStrings.WrongNumberArguments];
+        }
+        var serial = this.toSerial(args[0]);
+        if (typeof serial === 'string') {
+            return serial;
+        }
+        if (serial < 0) {
+            return errCollection[CommonErrors.Num];
+        }
+        return this.parent.fromOADate(serial).getFullYear().toString();
+    };
+    /**
+     * Converts a serial number to a number representing where the week falls numerically within a year.
+     *
+     * Excel: `WEEKNUM(...)`.
+     *
+     * @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`.
+     */
+    DateTimeExtraFormulas.prototype.ComputeWEEKNUM = 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 < 1 || args.length > 2) {
+            return this.parent.formulaErrorStrings[FormulasErrorsStrings.WrongNumberArguments];
+        }
+        var serial = this.toSerial(args[0]);
+        if (typeof serial === 'string') {
+            return serial;
+        }
+        var returnType = 1;
+        if (args.length === 2 && args[1] !== '') {
+            var rt = this.resolveNumberArg(args[1]);
+            if (typeof rt === 'string') {
+                return rt;
+            }
+            returnType = Math.floor(rt);
+        }
+        var date = this.parent.fromOADate(serial);
+        var yearStart = new Date(date.getFullYear(), 0, 1);
+        var dayOffset = 0;
+        if (returnType === 2 || returnType === 11) {
+            dayOffset = 1; // week begins Monday
+        }
+        var startDow = (yearStart.getDay() + 7 - dayOffset) % 7;
+        var dayOfYear = Math.floor((date.getTime() - yearStart.getTime()) / 86400000);
+        var week = Math.floor((dayOfYear + startDow) / 7) + 1;
+        if (week < 1) {
+            return errCollection[CommonErrors.Num];
+        }
+        return week.toString();
+    };
+    /**
+     * Converts a time in the form of text to a serial number.
+     *
+     * Excel: `TIMEVALUE(...)`.
+     *
+     * @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`.
+     */
+    DateTimeExtraFormulas.prototype.ComputeTIMEVALUE = 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 !== 1) {
+            return this.parent.formulaErrorStrings[FormulasErrorsStrings.WrongNumberArguments];
+        }
+        var text = this.resolveTextArg(args[0]);
+        if (errCollection.indexOf(text) > -1) {
+            return text;
+        }
+        // eslint-disable-next-line security/detect-unsafe-regex
+        var match = text.trim().match(/^(\d{1,2}):(\d{2})(?::(\d{2}))?\s*(AM|PM)?$/i);
+        if (!match) {
+            var asDate = this.parent.isDate(new Date(text));
+            if (asDate) {
+                var serial = this.parent.toOADate(asDate, true);
+                return (serial - Math.floor(serial)).toString();
+            }
+            return errCollection[CommonErrors.Value];
+        }
+        var hours = parseInt(match[1], 10);
+        var minutes = parseInt(match[2], 10);
+        var seconds = match[3] ? parseInt(match[3], 10) : 0;
+        var ampm = match[4] ? match[4].toUpperCase() : '';
+        if (ampm === 'PM' && hours < 12) {
+            hours += 12;
+        }
+        if (ampm === 'AM' && hours === 12) {
+            hours = 0;
+        }
+        if (hours > 23 || minutes > 59 || seconds > 59) {
+            return errCollection[CommonErrors.Value];
+        }
+        return ((hours * 3600 + minutes * 60 + seconds) / 86400).toString();
+    };
+    /**
+     * Calculates the number of days between two dates based on a 360-day year.
+     *
+     * Excel: `DAYS360(...)`.
+     *
+     * @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`.
+     */
+    DateTimeExtraFormulas.prototype.ComputeDAYS360 = function () {
+        var args = [];
+        for (var _i = 0; _i < arguments.length; _i++) {
+            args[_i] = arguments[_i];
+        }
+        if (isNullOrUndefined(args) || args.length < 2 || args.length > 3) {
+            return this.parent.formulaErrorStrings[FormulasErrorsStrings.WrongNumberArguments];
+        }
+        var start = this.toSerial(args[0]);
+        var end = this.toSerial(args[1]);
+        if (typeof start === 'string') {
+            return start;
+        }
+        if (typeof end === 'string') {
+            return end;
+        }
+        var method = false;
+        if (args.length === 3 && args[2] !== '') {
+            var flag = this.parent.getValueFromArg(args[2]).toUpperCase();
+            method = flag === this.parent.trueValue || this.parent.parseFloat(flag) !== 0;
+        }
+        var d1 = this.parent.fromOADate(start);
+        var d2 = this.parent.fromOADate(end);
+        var y1 = d1.getFullYear();
+        var m1 = d1.getMonth() + 1;
+        var day1 = d1.getDate();
+        var y2 = d2.getFullYear();
+        var m2 = d2.getMonth() + 1;
+        var day2 = d2.getDate();
+        if (!method) {
+            if (day1 === 31) {
+                day1 = 30;
+            }
+            if (day2 === 31 && day1 === 30) {
+                day2 = 30;
+            }
+        }
+        else {
+            if (day1 === 31) {
+                day1 = 30;
+            }
+            if (day2 === 31) {
+                day2 = 30;
+            }
+        }
+        return ((y2 - y1) * 360 + (m2 - m1) * 30 + (day2 - day1)).toString();
+    };
+    /**
+     * Returns the year fraction representing the number of whole days between start_date and end_date.
+     *
+     * Excel: `YEARFRAC(...)`.
+     *
+     * @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`.
+     */
+    DateTimeExtraFormulas.prototype.ComputeYEARFRAC = function () {
+        var args = [];
+        for (var _i = 0; _i < arguments.length; _i++) {
+            args[_i] = arguments[_i];
+        }
+        if (isNullOrUndefined(args) || args.length < 2 || args.length > 3) {
+            return this.parent.formulaErrorStrings[FormulasErrorsStrings.WrongNumberArguments];
+        }
+        var start = this.toSerial(args[0]);
+        var end = this.toSerial(args[1]);
+        if (typeof start === 'string') {
+            return start;
+        }
+        if (typeof end === 'string') {
+            return end;
+        }
+        var basis = 0;
+        if (args.length === 3 && args[2] !== '') {
+            var b = this.resolveNumberArg(args[2]);
+            if (typeof b === 'string') {
+                return b;
+            }
+            basis = Math.floor(b);
+        }
+        var days = Math.abs(end - start);
+        switch (basis) {
+            case 0:
+                return (Math.abs(this.parent.parseFloat(this.ComputeDAYS360(args[0], args[1], 'FALSE'))) / 360).toString();
+            case 1: {
+                var avgYear = 365.25;
+                return (days / avgYear).toString();
+            }
+            case 2:
+                return (days / 360).toString();
+            case 3:
+                return (days / 365).toString();
+            case 4:
+                return (Math.abs(this.parent.parseFloat(this.ComputeDAYS360(args[0], args[1], 'TRUE'))) / 360).toString();
+            default:
+                return this.parent.getErrorStrings()[CommonErrors.Num];
+        }
+    };
+    DateTimeExtraFormulas.prototype.isWeekend = function (date) {
+        var dow = date.getDay();
+        return dow === 0 || dow === 6;
+    };
+    DateTimeExtraFormulas.prototype.holidaySet = function (arg) {
+        var set = new Set();
+        if (!arg || arg === '') {
+            return set;
+        }
+        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];
+            for (var i = 0; i < list.length; i++) {
+                var serial = this.toSerial(list[i]);
+                if (typeof serial === 'string') {
+                    if (errCollection.indexOf(serial) > -1) {
+                        return serial;
+                    }
+                    continue;
+                }
+                set.add(Math.floor(serial));
+            }
+        }
+        else {
+            var serial = this.toSerial(arg);
+            if (typeof serial === 'string') {
+                return serial;
+            }
+            set.add(Math.floor(serial));
+        }
+        return set;
+    };
+    /**
+     * Returns the number of whole workdays between two dates.
+     *
+     * Excel: `NETWORKDAYS(...)`.
+     *
+     * @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`.
+     */
+    DateTimeExtraFormulas.prototype.ComputeNETWORKDAYS = function () {
+        var args = [];
+        for (var _i = 0; _i < arguments.length; _i++) {
+            args[_i] = arguments[_i];
+        }
+        if (isNullOrUndefined(args) || args.length < 2 || args.length > 3) {
+            return this.parent.formulaErrorStrings[FormulasErrorsStrings.WrongNumberArguments];
+        }
+        var start = this.toSerial(args[0]);
+        var end = this.toSerial(args[1]);
+        if (typeof start === 'string') {
+            return start;
+        }
+        if (typeof end === 'string') {
+            return end;
+        }
+        var holidays = this.holidaySet(args[2]);
+        if (!(holidays instanceof Set)) {
+            return holidays;
+        }
+        var step = start <= end ? 1 : -1;
+        var count = 0;
+        for (var s = Math.floor(start); step > 0 ? s <= Math.floor(end) : s >= Math.floor(end); s += step) {
+            var d = this.parent.fromOADate(s);
+            if (!this.isWeekend(d) && !holidays.has(s)) {
+                count += step;
+            }
+        }
+        return count.toString();
+    };
+    /**
+     * Returns the serial number of the date before or after a specified number of workdays.
+     *
+     * Excel: `WORKDAY(...)`.
+     *
+     * @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`.
+     */
+    DateTimeExtraFormulas.prototype.ComputeWORKDAY = 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 > 3) {
+            return this.parent.formulaErrorStrings[FormulasErrorsStrings.WrongNumberArguments];
+        }
+        var start = this.toSerial(args[0]);
+        var daysArg = this.resolveNumberArg(args[1]);
+        if (typeof start === 'string') {
+            return start;
+        }
+        if (typeof daysArg === 'string') {
+            return daysArg;
+        }
+        var days = Math.trunc(daysArg);
+        var holidays = this.holidaySet(args[2]);
+        if (!(holidays instanceof Set)) {
+            return holidays;
+        }
+        var current = Math.floor(start);
+        var step = days >= 0 ? 1 : -1;
+        var remaining = Math.abs(days);
+        while (remaining > 0) {
+            current += step;
+            var d = this.parent.fromOADate(current);
+            if (!this.isWeekend(d) && !holidays.has(current)) {
+                remaining--;
+            }
+            if (current < 0) {
+                return errCollection[CommonErrors.Num];
+            }
+        }
+        return current.toString();
+    };
+    return DateTimeExtraFormulas;
+}(FormulaModuleBase));
+export { DateTimeExtraFormulas };

package/src/formulas/date-time-intl.d.ts

@@ -0,0 +1,57 @@
+import { IBasicFormula } from '../common/index';
+import { FormulaOwner } from './formula-owner';
+import { FormulaModuleBase } from './formula-module-base';
+/**
+ * Locale-aware and ECMA date functions including DATEDIF and custom-weekend WORKDAY/NETWORKDAYS variants.
+ *
+ * Registered functions: DATEDIF, NETWORKDAYS.INTL, WORKDAY.INTL.
+ *
+ * @hidden
+ */
+export declare class DateTimeIntlFormulas extends FormulaModuleBase {
+    /** Formula definitions registered with {@link BasicFormulas}. */
+    formulas: IBasicFormula[];
+    /**
+     * @hidden
+     * @param {FormulaOwner} owner - Formula registration owner ({@link BasicFormulas}).
+     */
+    constructor(owner: FormulaOwner);
+    private toSerial;
+    private holidaySet;
+    private weekendMask;
+    private isWeekendMask;
+    /**
+     * Calculates the number of days, months, or years between two dates.
+     *
+     * Excel: `DATEDIF(...)`.
+     *
+     * @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('=DATEDIF(DATE(2020,1,1),DATE(2024,1,1),"Y")');
+     * ```
+     */
+    ComputeDATEDIF(...args: string[]): string | number;
+    private isLeapYear;
+    /**
+     * Returns workdays between dates for a custom weekend.
+     *
+     * Excel: `NETWORKDAYS.INTL(...)`.
+     *
+     * @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`.
+     */
+    ['ComputeNETWORKDAYS.INTL'](...args: string[]): string | number;
+    /**
+     * Returns the date before or after a number of workdays with a custom weekend.
+     *
+     * Excel: `WORKDAY.INTL(...)`.
+     *
+     * @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`.
+     */
+    ['ComputeWORKDAY.INTL'](...args: string[]): string | number;
+}