@cj-tech-master/excelts 9.3.1 → 9.4.0

package/dist/esm/modules/formula/functions/engineering.js

@@ -6,147 +6,92 @@ import { checkError } from "./_shared.js";
 // ============================================================================
 // Base Conversion Functions
 // ============================================================================
-export const fnBIN2DEC = args => {
-    const err = checkError(args[0]);
-    if (err) {
-        return err;
-    }
-    const s = toStringRV(args[0]);
-    if (!/^[01]{1,10}$/.test(s)) {
-        return ERRORS.NUM;
-    }
-    // 10-bit two's complement
-    if (s.length === 10 && s[0] === "1") {
-        return rvNumber(parseInt(s.slice(1), 2) - 512);
-    }
-    return rvNumber(parseInt(s, 2));
-};
-export const fnDEC2BIN = args => {
-    const nRV = toNumberRV(args[0]);
+export const fnBIN2DEC = args => baseToDec(args, 2, /^[01]{1,10}$/);
+export const fnDEC2BIN = args => decToBase(args, 2, -512, 511);
+export const fnDEC2HEX = args => decToBase(args, 16, -549755813888, 549755813887);
+export const fnDEC2OCT = args => decToBase(args, 8, -536870912, 536870911);
+/**
+ * Shared implementation of `DEC2BIN`, `DEC2HEX`, `DEC2OCT`.
+ *
+ * Excel's three numeric-to-base converters differ only in the target
+ * base, the signed range they accept, and whether the output is
+ * uppercased (hex). The `places` semantics (1..10, validated only when
+ * supplied and the input is non-negative) are identical across all three.
+ *
+ * Factored here so the three converters share a single source of truth —
+ * when the Excel rules are refined (e.g. additional validations or a new
+ * `places` upper bound), all three stay in lockstep.
+ */
+function decToBase(args, base, minValue, maxValue) {
+    const nRV = toNumberRV(topLeft(args[0]));
     if (isError(nRV)) {
         return nRV;
     }
     // Excel's DEC→BASE family truncates toward zero, so negative fractions
     // become `0`, not `-1` as `Math.floor` would produce.
     const n = Math.trunc(nRV.value);
-    if (n < -512 || n > 511) {
+    if (n < minValue || n > maxValue) {
         return ERRORS.NUM;
     }
     // `places` is only meaningful when supplied and the input is non-negative.
-    // Excel restricts it to the [1, 10] range and returns #NUM! otherwise.
-    // For negative inputs Excel ignores `places` entirely, so we validate it
-    // only on the non-negative branch below.
+    // Excel restricts it to [1, 10] and returns #NUM! outside that range.
+    // Negative inputs ignore `places` entirely — we validate it only when
+    // we've confirmed the input is non-negative.
     const hasPlaces = args.length > 1 && args[1].kind !== RVKind.Blank;
-    const placesRV = hasPlaces ? toNumberRV(args[1]) : rvNumber(0);
+    const placesRV = hasPlaces ? toNumberRV(topLeft(args[1])) : rvNumber(0);
     if (isError(placesRV)) {
         return placesRV;
     }
     const places = Math.trunc(placesRV.value);
+    const toUpper = base === 16;
     if (n < 0) {
-        return rvString((n + 1024).toString(2));
+        const raw = (n + Math.pow(base, 10)).toString(base);
+        return rvString(toUpper ? raw.toUpperCase() : raw);
     }
     if (hasPlaces && (places < 1 || places > 10)) {
         return ERRORS.NUM;
     }
-    const result = n.toString(2);
-    return rvString(places > 0 ? result.padStart(places, "0") : result);
-};
-export const fnHEX2DEC = args => {
-    const err = checkError(args[0]);
-    if (err) {
-        return err;
-    }
-    const s = toStringRV(args[0]);
-    if (!/^[0-9A-Fa-f]{1,10}$/.test(s)) {
-        return ERRORS.NUM;
-    }
-    const num = parseInt(s, 16);
-    // 10-digit hex: 40-bit two's complement
-    if (s.length === 10 && parseInt(s[0], 16) >= 8) {
-        return rvNumber(num - Math.pow(16, 10));
-    }
-    return rvNumber(num);
-};
-export const fnDEC2HEX = args => {
-    const nRV = toNumberRV(args[0]);
-    if (isError(nRV)) {
-        return nRV;
-    }
-    // Excel's DEC→BASE family truncates toward zero, so negative fractions
-    // become `0`, not `-1` as `Math.floor` would produce.
-    const n = Math.trunc(nRV.value);
-    // Excel rejects anything outside the 40-bit signed range.
-    // Without this check, inputs like 1e14 produce a 13-digit hex string
-    // and inputs below -2^39 wrap into spurious positive values prefixed
-    // with `-`. See R6-P0-1.
-    if (n < -549755813888 || n > 549755813887) {
+    const raw = n.toString(base);
+    const result = toUpper ? raw.toUpperCase() : raw;
+    // When `places` is supplied but smaller than the natural representation,
+    // Excel returns `#NUM!` rather than silently ignoring the width. `padStart`
+    // alone would leave the wider result unchanged — a soft deviation.
+    if (hasPlaces && places > 0 && result.length > places) {
         return ERRORS.NUM;
     }
-    // Same places semantics as DEC2BIN: validate only when `places` is
-    // supplied and the input is non-negative; Excel ignores `places` for
-    // negative numbers.
-    const hasPlaces = args.length > 1 && args[1].kind !== RVKind.Blank;
-    const placesRV = hasPlaces ? toNumberRV(args[1]) : rvNumber(0);
-    if (isError(placesRV)) {
-        return placesRV;
-    }
-    const places = Math.trunc(placesRV.value);
-    if (n < 0) {
-        return rvString((n + Math.pow(16, 10)).toString(16).toUpperCase());
-    }
-    if (hasPlaces && (places < 1 || places > 10)) {
-        return ERRORS.NUM;
-    }
-    const result = n.toString(16).toUpperCase();
     return rvString(places > 0 ? result.padStart(places, "0") : result);
-};
-export const fnOCT2DEC = args => {
+}
+export const fnHEX2DEC = args => baseToDec(args, 16, /^[0-9A-Fa-f]{1,10}$/);
+export const fnOCT2DEC = args => baseToDec(args, 8, /^[0-7]{1,10}$/);
+/**
+ * Shared implementation of `BIN2DEC`, `OCT2DEC`, `HEX2DEC`.
+ *
+ * Each source base has the same "string of up to 10 digits, 10th digit
+ * sets the sign bit for two's-complement" semantics. The only
+ * differences are the allowed digit alphabet (passed as `pattern`) and
+ * the base (passed as `base`). The `isNegativeMsd` helper detects the
+ * sign bit by re-parsing the top digit; it works for binary (MSD=1),
+ * octal (MSD>=4) and hex (MSD>=8).
+ */
+function baseToDec(args, base, pattern) {
     const err = checkError(args[0]);
     if (err) {
         return err;
     }
-    const s = toStringRV(args[0]);
-    if (!/^[0-7]{1,10}$/.test(s)) {
+    const s = toStringRV(topLeft(args[0]));
+    if (!pattern.test(s)) {
         return ERRORS.NUM;
     }
-    const num = parseInt(s, 8);
-    if (s.length === 10 && parseInt(s[0]) >= 4) {
-        return rvNumber(num - Math.pow(8, 10));
+    const num = parseInt(s, base);
+    // 10-digit form triggers two's-complement interpretation. The sign bit
+    // is the top bit of the top digit — for binary that's the literal MSD,
+    // for octal it's `>= 4`, for hex it's `>= 8`. We compute the threshold
+    // from the base instead of hard-coding it.
+    if (s.length === 10 && parseInt(s[0], base) >= base / 2) {
+        return rvNumber(num - Math.pow(base, 10));
     }
     return rvNumber(num);
-};
-export const fnDEC2OCT = args => {
-    const nRV = toNumberRV(args[0]);
-    if (isError(nRV)) {
-        return nRV;
-    }
-    // Excel's DEC→BASE family truncates toward zero, so negative fractions
-    // become `0`, not `-1` as `Math.floor` would produce.
-    const n = Math.trunc(nRV.value);
-    // Excel's DEC2OCT range is the 30-bit signed range (-2^29 .. 2^29-1).
-    // Values outside this range are #NUM! in Excel; we silently wrapped
-    // into bogus sign-prefixed strings without this guard. See R6-P0-1.
-    if (n < -536870912 || n > 536870911) {
-        return ERRORS.NUM;
-    }
-    // Same places semantics as DEC2BIN: validate only when `places` is
-    // supplied and the input is non-negative; Excel ignores `places` for
-    // negative numbers.
-    const hasPlaces = args.length > 1 && args[1].kind !== RVKind.Blank;
-    const placesRV = hasPlaces ? toNumberRV(args[1]) : rvNumber(0);
-    if (isError(placesRV)) {
-        return placesRV;
-    }
-    const places = Math.trunc(placesRV.value);
-    if (n < 0) {
-        return rvString((n + Math.pow(8, 10)).toString(8));
-    }
-    if (hasPlaces && (places < 1 || places > 10)) {
-        return ERRORS.NUM;
-    }
-    const result = n.toString(8);
-    return rvString(places > 0 ? result.padStart(places, "0") : result);
-};
+}
 /**
  * Generic helper for the X2Y conversion family (BIN2HEX, HEX2BIN, …).
  *
@@ -162,13 +107,13 @@ function convertBase(args, parseNInput, format) {
     if (err) {
         return err;
     }
-    const s = toStringRV(args[0]);
+    const s = toStringRV(topLeft(args[0]));
     const n = parseNInput(s);
     if (typeof n !== "number") {
         return n;
     }
     const hasPlaces = args.length > 1 && args[1].kind !== RVKind.Blank;
-    const placesRV = hasPlaces ? toNumberRV(args[1]) : rvNumber(0);
+    const placesRV = hasPlaces ? toNumberRV(topLeft(args[1])) : rvNumber(0);
     if (isError(placesRV)) {
         return placesRV;
     }
@@ -207,6 +152,11 @@ function formatToBase(n, base, maxDigits, places, hasPlaces) {
         return ERRORS.NUM;
     }
     const result = n.toString(base).toUpperCase();
+    // `places` smaller than the natural representation is a #NUM! in Excel —
+    // `padStart` alone would silently emit the wider form.
+    if (hasPlaces && places > 0 && result.length > places) {
+        return ERRORS.NUM;
+    }
     return rvString(places > 0 ? result.padStart(places, "0") : result);
 }
 export const fnBIN2HEX = args => convertBase(args, parseBinInput, (n, places, hasPlaces) => formatToBase(n, 16, 10, places, hasPlaces));
@@ -462,11 +412,11 @@ function besselK(n, x) {
 }
 /** Common validation + dispatch for the four BESSEL* functions. */
 function bessel(args, compute, allowZeroX) {
-    const xRV = toNumberRV(args[0]);
+    const xRV = toNumberRV(topLeft(args[0]));
     if (isError(xRV)) {
         return xRV;
     }
-    const nRV = toNumberRV(args[1]);
+    const nRV = toNumberRV(topLeft(args[1]));
     if (isError(nRV)) {
         return nRV;
     }
@@ -491,22 +441,22 @@ export const fnBESSELI = args => bessel(args, besselI, true);
 export const fnBESSELK = args => bessel(args, besselK, false);
 export const fnBESSELY = args => bessel(args, besselY, false);
 export const fnDELTA = args => {
-    const n1 = toNumberRV(args[0]);
+    const n1 = toNumberRV(topLeft(args[0]));
     if (isError(n1)) {
         return n1;
     }
-    const n2 = args.length > 1 ? toNumberRV(args[1]) : rvNumber(0);
+    const n2 = args.length > 1 ? toNumberRV(topLeft(args[1])) : rvNumber(0);
     if (isError(n2)) {
         return n2;
     }
     return rvNumber(n1.value === n2.value ? 1 : 0);
 };
 export const fnGESTEP = args => {
-    const n = toNumberRV(args[0]);
+    const n = toNumberRV(topLeft(args[0]));
     if (isError(n)) {
         return n;
     }
-    const step = args.length > 1 ? toNumberRV(args[1]) : rvNumber(0);
+    const step = args.length > 1 ? toNumberRV(topLeft(args[1])) : rvNumber(0);
     if (isError(step)) {
         return step;
     }
@@ -588,22 +538,24 @@ function formatComplex(re, im, suffix = "i") {
     return re + imStr;
 }
 export const fnCOMPLEX = args => {
-    const re = toNumberRV(args[0]);
+    const re = toNumberRV(topLeft(args[0]));
     if (isError(re)) {
         return re;
     }
-    const im = toNumberRV(args[1]);
+    const im = toNumberRV(topLeft(args[1]));
     if (isError(im)) {
         return im;
     }
     let suffix = "i";
-    if (args.length > 2) {
+    if (args.length > 2 && args[2].kind !== RVKind.Blank) {
         const e2 = checkError(args[2]);
         if (e2) {
             return e2;
         }
-        suffix = toStringRV(args[2]);
+        suffix = toStringRV(topLeft(args[2]));
     }
+    // Blank 3rd arg → default "i". Previously a blank coerced to empty
+    // string then tripped the `suffix !== "i"` validation.
     if (suffix !== "i" && suffix !== "j") {
         return ERRORS.VALUE;
     }
@@ -614,7 +566,7 @@ export const fnIMREAL = args => {
     if (err) {
         return err;
     }
-    const c = parseComplex(toStringRV(args[0]));
+    const c = parseComplex(toStringRV(topLeft(args[0])));
     return c ? rvNumber(c[0]) : ERRORS.NUM;
 };
 export const fnIMAGINARY = args => {
@@ -622,7 +574,7 @@ export const fnIMAGINARY = args => {
     if (err) {
         return err;
     }
-    const c = parseComplex(toStringRV(args[0]));
+    const c = parseComplex(toStringRV(topLeft(args[0])));
     return c ? rvNumber(c[1]) : ERRORS.NUM;
 };
 export const fnIMABS = args => {
@@ -630,7 +582,7 @@ export const fnIMABS = args => {
     if (err) {
         return err;
     }
-    const c = parseComplex(toStringRV(args[0]));
+    const c = parseComplex(toStringRV(topLeft(args[0])));
     if (!c) {
         return ERRORS.NUM;
     }
@@ -641,7 +593,7 @@ export const fnIMARGUMENT = args => {
     if (err) {
         return err;
     }
-    const c = parseComplex(toStringRV(args[0]));
+    const c = parseComplex(toStringRV(topLeft(args[0])));
     if (!c) {
         return ERRORS.NUM;
     }
@@ -655,7 +607,7 @@ export const fnIMCONJUGATE = args => {
     if (err) {
         return err;
     }
-    const c = parseComplex(toStringRV(args[0]));
+    const c = parseComplex(toStringRV(topLeft(args[0])));
     if (!c) {
         return ERRORS.NUM;
     }
@@ -735,8 +687,8 @@ export const fnIMSUB = args => {
     if (e1) {
         return e1;
     }
-    const c1 = parseComplex(toStringRV(args[0]));
-    const c2 = parseComplex(toStringRV(args[1]));
+    const c1 = parseComplex(toStringRV(topLeft(args[0])));
+    const c2 = parseComplex(toStringRV(topLeft(args[1])));
     if (!c1 || !c2) {
         return ERRORS.NUM;
     }
@@ -771,8 +723,8 @@ export const fnIMDIV = args => {
     if (e1) {
         return e1;
     }
-    const c1 = parseComplex(toStringRV(args[0]));
-    const c2 = parseComplex(toStringRV(args[1]));
+    const c1 = parseComplex(toStringRV(topLeft(args[0])));
+    const c2 = parseComplex(toStringRV(topLeft(args[1])));
     if (!c1 || !c2) {
         return ERRORS.NUM;
     }
@@ -792,11 +744,11 @@ export const fnIMPOWER = args => {
     if (err) {
         return err;
     }
-    const c = parseComplex(toStringRV(args[0]));
+    const c = parseComplex(toStringRV(topLeft(args[0])));
     if (!c) {
         return ERRORS.NUM;
     }
-    const n = toNumberRV(args[1]);
+    const n = toNumberRV(topLeft(args[1]));
     if (isError(n)) {
         return n;
     }
@@ -810,7 +762,7 @@ export const fnIMSQRT = args => {
     if (err) {
         return err;
     }
-    const c = parseComplex(toStringRV(args[0]));
+    const c = parseComplex(toStringRV(topLeft(args[0])));
     if (!c) {
         return ERRORS.NUM;
     }
@@ -824,7 +776,7 @@ export const fnIMLN = args => {
     if (err) {
         return err;
     }
-    const c = parseComplex(toStringRV(args[0]));
+    const c = parseComplex(toStringRV(topLeft(args[0])));
     if (!c) {
         return ERRORS.NUM;
     }
@@ -839,7 +791,7 @@ export const fnIMLOG2 = args => {
     if (err) {
         return err;
     }
-    const c = parseComplex(toStringRV(args[0]));
+    const c = parseComplex(toStringRV(topLeft(args[0])));
     if (!c) {
         return ERRORS.NUM;
     }
@@ -855,7 +807,7 @@ export const fnIMLOG10 = args => {
     if (err) {
         return err;
     }
-    const c = parseComplex(toStringRV(args[0]));
+    const c = parseComplex(toStringRV(topLeft(args[0])));
     if (!c) {
         return ERRORS.NUM;
     }
@@ -871,7 +823,7 @@ export const fnIMEXP = args => {
     if (err) {
         return err;
     }
-    const c = parseComplex(toStringRV(args[0]));
+    const c = parseComplex(toStringRV(topLeft(args[0])));
     if (!c) {
         return ERRORS.NUM;
     }
@@ -883,7 +835,7 @@ export const fnIMSIN = args => {
     if (err) {
         return err;
     }
-    const c = parseComplex(toStringRV(args[0]));
+    const c = parseComplex(toStringRV(topLeft(args[0])));
     if (!c) {
         return ERRORS.NUM;
     }
@@ -894,7 +846,7 @@ export const fnIMCOS = args => {
     if (err) {
         return err;
     }
-    const c = parseComplex(toStringRV(args[0]));
+    const c = parseComplex(toStringRV(topLeft(args[0])));
     if (!c) {
         return ERRORS.NUM;
     }
@@ -1024,11 +976,11 @@ function validateBitOperand(v) {
     return v;
 }
 export const fnBITAND = args => {
-    const a = toNumberRV(args[0]);
+    const a = toNumberRV(topLeft(args[0]));
     if (isError(a)) {
         return a;
     }
-    const b = toNumberRV(args[1]);
+    const b = toNumberRV(topLeft(args[1]));
     if (isError(b)) {
         return b;
     }
@@ -1043,11 +995,11 @@ export const fnBITAND = args => {
     return rvNumber(bitAnd48(av, bv));
 };
 export const fnBITOR = args => {
-    const a = toNumberRV(args[0]);
+    const a = toNumberRV(topLeft(args[0]));
     if (isError(a)) {
         return a;
     }
-    const b = toNumberRV(args[1]);
+    const b = toNumberRV(topLeft(args[1]));
     if (isError(b)) {
         return b;
     }
@@ -1062,11 +1014,11 @@ export const fnBITOR = args => {
     return rvNumber(bitOr48(av, bv));
 };
 export const fnBITXOR = args => {
-    const a = toNumberRV(args[0]);
+    const a = toNumberRV(topLeft(args[0]));
     if (isError(a)) {
         return a;
     }
-    const b = toNumberRV(args[1]);
+    const b = toNumberRV(topLeft(args[1]));
     if (isError(b)) {
         return b;
     }
@@ -1081,11 +1033,11 @@ export const fnBITXOR = args => {
     return rvNumber(bitXor48(av, bv));
 };
 export const fnBITLSHIFT = args => {
-    const num = toNumberRV(args[0]);
+    const num = toNumberRV(topLeft(args[0]));
     if (isError(num)) {
         return num;
     }
-    const shift = toNumberRV(args[1]);
+    const shift = toNumberRV(topLeft(args[1]));
     if (isError(shift)) {
         return shift;
     }
@@ -1104,11 +1056,11 @@ export const fnBITLSHIFT = args => {
     return rvNumber(result);
 };
 export const fnBITRSHIFT = args => {
-    const num = toNumberRV(args[0]);
+    const num = toNumberRV(topLeft(args[0]));
     if (isError(num)) {
         return num;
     }
-    const shift = toNumberRV(args[1]);
+    const shift = toNumberRV(topLeft(args[1]));
     if (isError(shift)) {
         return shift;
     }