@utiliread/primitives 1.0.0-146 → 1.0.0-147

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@utiliread/primitives",
-  "version": "1.0.0-146",
+  "version": "1.0.0-147",
   "source": "src/index.ts",
   "main": "dist/index.js",
   "module": "dist/index.mjs",

package/src/number-formatter.spec.ts

@@ -547,3 +547,24 @@ describe("toLocaleFixed", () => {
         );
     });
 });
+
+describe("zero", () => {
+    it("should format zero with precision as number of decimals", () => {
+        expect(NumberFormatter.toPrecision(0, 0)).to.equal("0");
+        expect(NumberFormatter.toPrecision(0, 1)).to.equal("0.0");
+        expect(NumberFormatter.toPrecision(0, 2)).to.equal("0.00");
+        expect(NumberFormatter.toFixed(0, 0)).to.equal("0");
+        expect(NumberFormatter.toFixed(0, 2)).to.equal("0.00");
+    });
+
+    it("should limit the decimals of zero to maxDecimals", () => {
+        expect(NumberFormatter.toFixed(0, 3, 2)).to.equal("0.00");
+        expect(NumberFormatter.toFixed(0, 3, 0)).to.equal("0");
+        expect(NumberFormatter.toFixed(0, 1, 2)).to.equal("0.0");
+    });
+
+    it("should not throw for a non-zero value with precision 0", () => {
+        expect(NumberFormatter.toFixed(5, 0)).to.equal("5");
+        expect(NumberFormatter.toFixed(0.4, 0)).to.equal("0.4");
+    });
+});

package/src/number-formatter.ts

@@ -10,15 +10,8 @@ export interface Parts {
 
 class Formatter {
     public toPrecision(value: number, precision: number, maxDecimals?: number) {
-        const absValue = Math.abs(value);
-        const noOfIntegerDigits = Math.round(absValue).toString().length;
-
-        // Adjust precision to maxDecimals
-        if (maxDecimals !== undefined) {
-            precision = Math.min(precision, noOfIntegerDigits + maxDecimals);
-        }
-
         if (value === 0) {
+            // By convention the precision of zero is its number of decimals.
             // (0).toPrecision(1) == "0"
             // (0).toPrecision(2) == "0.0"
             // (0).toPrecision(3) == "0.00"
@@ -26,9 +19,24 @@ class Formatter {
             // Formatter.toPrecision(0, 0) == "0"
             // Formatter.toPrecision(0, 1) == "0.0"
             // Formatter.toPrecision(0, 2) == "0.00"
-            return value.toPrecision(precision + 1);
+            const decimals =
+                maxDecimals !== undefined
+                    ? Math.min(precision, maxDecimals)
+                    : precision;
+            return (0).toPrecision(Math.max(decimals, 0) + 1);
         }
 
+        const absValue = Math.abs(value);
+        const noOfIntegerDigits = Math.round(absValue).toString().length;
+
+        // Adjust precision to maxDecimals
+        if (maxDecimals !== undefined) {
+            precision = Math.min(precision, noOfIntegerDigits + maxDecimals);
+        }
+
+        // A precision of 0 is only valid for zero, use at least one significant digit for any other value
+        precision = Math.max(precision, 1);
+
         if (absValue < 1) {
             return value.toPrecision(precision);
         }

package/src/precision-number.spec.ts

@@ -3,9 +3,12 @@ import { expect } from "chai";
 
 describe("new", () => {
     it("should create 0", () => {
+        // The precision of zero is its number of decimals
         const number = new PrecisionNumber(0);
         expect(number.value).to.equal(0);
-        expect(number.precision).to.equal(1);
+        expect(number.precision).to.equal(0);
+        expect(number.decimals).to.equal(0);
+        expect(number.toFixed()).to.equal("0");
     });
 
     it("should create 0.5", () => {
@@ -17,7 +20,8 @@ describe("new", () => {
     it("should create 0.05", () => {
         const number = new PrecisionNumber(0.05);
         expect(number.value).to.equal(0.05);
-        expect(number.precision).to.equal(2);
+        expect(number.precision).to.equal(1);
+        expect(number.decimals).to.equal(2);
     });
 
     it("should create 1.05", () => {
@@ -43,13 +47,40 @@ describe("parse", () => {
     it("should parse '0'", () => {
         const number = PrecisionNumber.parse("0");
         expect(number.value).to.equal(0);
-        expect(number.precision).to.equal(1);
+        expect(number.precision).to.equal(0);
+        expect(number.toFixed()).to.equal("0");
     });
 
     it("should parse '0.0'", () => {
         const number = PrecisionNumber.parse("0.0");
         expect(number.value).to.equal(0);
         expect(number.precision).to.equal(1);
+        expect(number.toFixed()).to.equal("0.0");
+    });
+
+    it("should parse '0.00'", () => {
+        const number = PrecisionNumber.parse("0.00");
+        expect(number.value).to.equal(0);
+        expect(number.precision).to.equal(2);
+        expect(number.toFixed()).to.equal("0.00");
+    });
+
+    it("should parse '0.'", () => {
+        const number = PrecisionNumber.parse("0.");
+        expect(number.value).to.equal(0);
+        expect(number.precision).to.equal(1);
+    });
+
+    it("should parse '-0.0'", () => {
+        const number = PrecisionNumber.parse("-0.0");
+        expect(number.value).to.equal(0);
+        expect(number.precision).to.equal(1);
+    });
+
+    it("should parse '000.00'", () => {
+        const number = PrecisionNumber.parse("000.00");
+        expect(number.value).to.equal(0);
+        expect(number.precision).to.equal(2);
     });
 
     it("should parse '1'", () => {
@@ -175,6 +206,54 @@ describe("plus", () => {
             new PrecisionNumber(1024, 3),
             new PrecisionNumber(1024, 3),
         ],
+        // "0" is the additive identity
+        [
+            new PrecisionNumber(0, 0),
+            new PrecisionNumber(1.25, 3),
+            new PrecisionNumber(1.25, 3),
+        ],
+        [
+            new PrecisionNumber(1.25, 3),
+            new PrecisionNumber(0, 0),
+            new PrecisionNumber(1.25, 3),
+        ],
+        [
+            new PrecisionNumber(0, 1),
+            new PrecisionNumber(1.26, 3),
+            new PrecisionNumber(1.26, 2),
+        ],
+        // Zero results have the number of decimals as precision
+        [
+            new PrecisionNumber(-1, 1),
+            new PrecisionNumber(1, 1),
+            new PrecisionNumber(0, 0),
+        ],
+        [
+            new PrecisionNumber(-1, 2),
+            new PrecisionNumber(1, 2),
+            new PrecisionNumber(0, 1),
+        ],
+        [
+            new PrecisionNumber(-1.25, 3),
+            new PrecisionNumber(1.25, 3),
+            new PrecisionNumber(0, 2),
+        ],
+        [
+            new PrecisionNumber(1.4, 2),
+            new PrecisionNumber(-1, 1),
+            new PrecisionNumber(0, 0),
+        ],
+        [
+            new PrecisionNumber(0, 2),
+            new PrecisionNumber(0, 1),
+            new PrecisionNumber(0, 1),
+        ],
+        // Sub-1 values
+        [
+            new PrecisionNumber(0.0625, 3),
+            new PrecisionNumber(-0.03125, 1),
+            new PrecisionNumber(0.03125, 1),
+        ],
     ];
 
     it("should plus correctly", () => {
@@ -203,6 +282,21 @@ describe("minus", () => {
             new PrecisionNumber(0, 1),
             new PrecisionNumber(123, 2),
         ],
+        [
+            new PrecisionNumber(0, 0),
+            new PrecisionNumber(123, 2),
+            new PrecisionNumber(-123, 2),
+        ],
+        [
+            new PrecisionNumber(123, 3),
+            new PrecisionNumber(123, 3),
+            new PrecisionNumber(0, 0),
+        ],
+        [
+            new PrecisionNumber(1.5, 2),
+            new PrecisionNumber(1.5, 2),
+            new PrecisionNumber(0, 1),
+        ],
     ];
 
     it("should minus correctly", () => {
@@ -214,6 +308,43 @@ describe("minus", () => {
     });
 });
 
+describe("zero", () => {
+    it("should not leave floating point noise", () => {
+        const result = new PrecisionNumber(0.3, 1)
+            .minus(new PrecisionNumber(0.1, 1))
+            .minus(new PrecisionNumber(0.2, 1));
+        expect(result.value).to.equal(0);
+        expect(result.precision).to.equal(1);
+        expect(result.toFixed()).to.equal("0.0");
+    });
+
+    it("should format zero with its number of decimals", () => {
+        expect(new PrecisionNumber(0, 0).toFixed()).to.equal("0");
+        expect(new PrecisionNumber(0, 1).toFixed()).to.equal("0.0");
+        expect(new PrecisionNumber(0, 2).toFixed()).to.equal("0.00");
+        expect(new PrecisionNumber(0, 0).toPrecision()).to.equal("0");
+        expect(new PrecisionNumber(0, 2).toPrecision()).to.equal("0.00");
+    });
+});
+
+describe("decimals", () => {
+    it("should get the number of decimals", () => {
+        expect(new PrecisionNumber(0, 0).decimals).to.equal(0);
+        expect(new PrecisionNumber(0, 2).decimals).to.equal(2);
+        expect(new PrecisionNumber(0.003, 1).decimals).to.equal(3);
+        expect(new PrecisionNumber(0.07, 1).decimals).to.equal(2);
+        expect(new PrecisionNumber(0.099, 1).decimals).to.equal(1);
+        expect(new PrecisionNumber(0.0999, 2).decimals).to.equal(2);
+        expect(new PrecisionNumber(0.1, 3).decimals).to.equal(3);
+        expect(new PrecisionNumber(100, 1).decimals).to.equal(-2);
+        expect(new PrecisionNumber(100, 4).decimals).to.equal(1);
+    });
+
+    it("should keep sub-1 values in valueOf", () => {
+        expect(PrecisionNumber.parse(".06").valueOf()).to.equal(0.06);
+    });
+});
+
 describe("toString", () => {
     it("should return a rounded version in toFixed", () => {
         expect(new PrecisionNumber(2474.581, 6).toFixed()).to.equal("2474.58");

package/src/precision-number.ts

@@ -4,16 +4,22 @@ import {
     localeDecimalSeparator,
 } from "./number-formatter";
 
+/**
+ * A number with a number of significant digits (`precision`).
+ *
+ * Convention for zero (which has no significant digits): the precision is the number of decimals.
+ * "0" has precision 0, "0.0" has precision 1, "0.00" has precision 2, etc.
+ * A precision of 0 is therefore only valid for the value 0 and must NOT be interpreted as "no precision",
+ * i.e. use `precision === undefined` and not `!precision` to test for a missing precision.
+ *
+ * This is the same convention as `PrecisionDouble` in C#.
+ */
 export class PrecisionNumber {
     public value: number;
     public precision: number;
 
     public get decimals() {
-        if (this.value > -1 && this.value < 1) {
-            return this.precision;
-        } else {
-            return this.precision - getNumberOfIntegralDigits(this.value);
-        }
+        return getNoOfDecimalPlaces(this.value, this.precision);
     }
 
     constructor(value: number, precision?: number) {
@@ -34,7 +40,8 @@ export class PrecisionNumber {
         const value = parseFloat(normalized);
         const precision =
             value === 0
-                ? 1
+                ? // The precision of zero is its number of decimals, "0" => 0, "0.0" => 1
+                  (normalized.split(".", 2)[1]?.length ?? 0)
                 : normalized
                       .replace(".", "")
                       .replace("+", "")
@@ -48,21 +55,35 @@ export class PrecisionNumber {
     }
 
     plus(rhs: PrecisionNumber) {
-        // The result should have the same number of decimal places as the minimum of the two inputs
         const lhs = this;
+
+        // "0" (without decimals) is the additive identity
+        if (isIntegerZero(lhs)) {
+            return rhs;
+        } else if (isIntegerZero(rhs)) {
+            return lhs;
+        }
+
+        // The result should have the same number of decimal places as the minimum of the two inputs
         const value = lhs.value + rhs.value;
         const decimals = Math.min(lhs.decimals, rhs.decimals);
-        const precision = getPrecision(value, decimals);
-        return new PrecisionNumber(value, precision);
+        return fromResult(value, decimals);
     }
 
     minus(rhs: PrecisionNumber) {
-        // The result should have the same number of decimal places as the minimum of the two inputs
         const lhs = this;
+
+        // "0" (without decimals) is the additive identity
+        if (isIntegerZero(lhs)) {
+            return new PrecisionNumber(-rhs.value, rhs.precision);
+        } else if (isIntegerZero(rhs)) {
+            return lhs;
+        }
+
+        // The result should have the same number of decimal places as the minimum of the two inputs
         const value = lhs.value - rhs.value;
         const decimals = Math.min(lhs.decimals, rhs.decimals);
-        const precision = getPrecision(value, decimals);
-        return new PrecisionNumber(value, precision);
+        return fromResult(value, decimals);
     }
 
     valueOf() {
@@ -96,16 +117,101 @@ export class PrecisionNumber {
     }
 }
 
+function isIntegerZero(number: PrecisionNumber) {
+    return number.value === 0 && number.precision === 0;
+}
+
+/**
+ * Create the result of an addition or subtraction having `decimals` decimal places.
+ * A result that is zero at that number of decimal places (e.g. floating point noise from 0.3 - 0.1 - 0.2) becomes an exact zero.
+ */
+function fromResult(value: number, decimals: number) {
+    if (decimals >= 0 && Math.abs(value) * Math.pow(10, decimals) < 0.5) {
+        return new PrecisionNumber(0, decimals);
+    }
+    return new PrecisionNumber(value, getPrecision(value, decimals));
+}
+
+/**
+ * Get the precision of `number` having `decimals` decimal places.
+ *
+ * Number Decimals Precision
+ * 0      0        0 ("0")
+ * 0      2        2 ("0.00")
+ * 0.05   2        1
+ * 0.12   2        2
+ * 100    1        4
+ * 100    0        3
+ * 100    -1       2
+ * 100    <= -2    1
+ */
 function getPrecision(number: number, decimals?: number) {
     decimals ??= number.toString().split(".", 2)[1]?.length ?? 0;
 
-    if (number == 0) {
-        return 1;
-    } else if (number > -1 && number < 1) {
+    if (number === 0) {
+        // The precision of zero is its number of decimals
+        return Math.max(decimals, 0);
+    }
+
+    const abs = Math.abs(number);
+    if (abs < 1) {
+        // Leading zeros after the decimal separator are not significant
+        return Math.max(decimals - getNoOfLeadingZeros(abs), 1);
+    }
+
+    return Math.max(getNumberOfIntegralDigits(number) + decimals, 1);
+}
+
+/**
+ * Get the number of decimal places of `number` having `precision` significant digits.
+ *
+ * Number Precision Decimals
+ * 0      2         2 ("0.00")
+ * 0.099  1         1 (0.1)
+ * 0.07   1         2
+ * 0.1    2         2
+ * 100    1         -2
+ * 100    3         0
+ * 100    4         1
+ */
+function getNoOfDecimalPlaces(number: number, precision: number) {
+    if (number === 0) {
+        // The precision of zero is its number of decimals
+        return precision;
+    }
+
+    const abs = Math.abs(number);
+    if (abs < 1) {
+        // Leading zeros after the decimal separator are not significant
+        const leadingZeros = getNoOfLeadingZeros(abs);
+        let decimals = precision + leadingZeros;
+
+        // Rounding may carry into the next order of magnitude, e.g. 0.099 at precision 1 is 0.1
+        if (
+            leadingZeros > 0 &&
+            Math.round(abs * Math.pow(10, decimals)) >= Math.pow(10, precision)
+        ) {
+            decimals--;
+        }
+
         return decimals;
-    } else {
-        return Math.max(getNumberOfIntegralDigits(number) + decimals, 1);
     }
+
+    return precision - getNumberOfIntegralDigits(number);
+}
+
+/**
+ * Get the number of zeros between the decimal separator and the first significant digit of `abs` where 0 < `abs` < 1,
+ * e.g. 0.5 => 0, 0.05 => 1, 0.005 => 2
+ */
+function getNoOfLeadingZeros(abs: number) {
+    let leadingZeros = 0;
+    let scaled = abs * 10;
+    while (scaled < 1) {
+        scaled *= 10;
+        leadingZeros++;
+    }
+    return leadingZeros;
 }
 
 function getNumberOfIntegralDigits(number: number) {