@utiliread/primitives 1.0.0-146 → 1.0.0-148

package/src/precision-number.ts

@@ -1,123 +1,229 @@
-import {
-    NumberFormatter,
-    invariantDecimalSeparator,
-    localeDecimalSeparator,
-} from "./number-formatter";
-
-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);
-        }
-    }
-
-    constructor(value: number, precision?: number) {
-        this.value = value;
-        this.precision = precision ?? getPrecision(value);
-    }
-
-    static parse(input: string) {
-        let normalized = input
-            .trim()
-            .replace(",", ".")
-            .replace(localeDecimalSeparator, invariantDecimalSeparator);
-
-        if (normalized.endsWith(invariantDecimalSeparator)) {
-            normalized += "0";
-        }
-
-        const value = parseFloat(normalized);
-        const precision =
-            value === 0
-                ? 1
-                : normalized
-                      .replace(".", "")
-                      .replace("+", "")
-                      .replace("-", "")
-                      .replace(/^0+/, "").length;
-        return new PrecisionNumber(value, precision);
-    }
-
-    abs() {
-        return new PrecisionNumber(Math.abs(this.value), this.precision);
-    }
-
-    plus(rhs: PrecisionNumber) {
-        // The result should have the same number of decimal places as the minimum of the two inputs
-        const lhs = this;
-        const value = lhs.value + rhs.value;
-        const decimals = Math.min(lhs.decimals, rhs.decimals);
-        const precision = getPrecision(value, decimals);
-        return new PrecisionNumber(value, precision);
-    }
-
-    minus(rhs: PrecisionNumber) {
-        // The result should have the same number of decimal places as the minimum of the two inputs
-        const lhs = this;
-        const value = lhs.value - rhs.value;
-        const decimals = Math.min(lhs.decimals, rhs.decimals);
-        const precision = getPrecision(value, decimals);
-        return new PrecisionNumber(value, precision);
-    }
-
-    valueOf() {
-        const scale = Math.pow(10, this.decimals);
-        const integer = Math.round(this.value * scale);
-        const value = integer / scale;
-        return value;
-    }
-
-    toString() {
-        return this.valueOf().toString();
-    }
-
-    toFixed() {
-        return NumberFormatter.toFixed(this.valueOf(), this.precision);
-    }
-
-    toPrecision() {
-        return NumberFormatter.toPrecision(this.valueOf(), this.precision);
-    }
-
-    toLocaleFixed() {
-        return NumberFormatter.toLocaleFixed(this.valueOf(), this.precision);
-    }
-
-    toLocalePrecision() {
-        return NumberFormatter.toLocalePrecision(
-            this.valueOf(),
-            this.precision,
-        );
-    }
-}
-
-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) {
-        return decimals;
-    } else {
-        return Math.max(getNumberOfIntegralDigits(number) + decimals, 1);
-    }
-}
-
-function getNumberOfIntegralDigits(number: number) {
-    const abs = Math.abs(number);
-    if (abs < 10) return 1;
-    if (abs < 100) return 2;
-    if (abs < 1000) return 3;
-    if (abs < 10000) return 4;
-    if (abs < 100000) return 5;
-    if (abs < 1000000) return 6;
-    if (abs < 10000000) return 7;
-    if (abs < 100000000) return 8;
-    if (abs < 1000000000) return 9;
-    return Math.floor(Math.log10(abs) + 1);
-}
+import {
+    NumberFormatter,
+    invariantDecimalSeparator,
+    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() {
+        return getNoOfDecimalPlaces(this.value, this.precision);
+    }
+
+    constructor(value: number, precision?: number) {
+        this.value = value;
+        this.precision = precision ?? getPrecision(value);
+    }
+
+    static parse(input: string) {
+        let normalized = input
+            .trim()
+            .replace(",", ".")
+            .replace(localeDecimalSeparator, invariantDecimalSeparator);
+
+        if (normalized.endsWith(invariantDecimalSeparator)) {
+            normalized += "0";
+        }
+
+        const value = parseFloat(normalized);
+        const precision =
+            value === 0
+                ? // The precision of zero is its number of decimals, "0" => 0, "0.0" => 1
+                  (normalized.split(".", 2)[1]?.length ?? 0)
+                : normalized
+                      .replace(".", "")
+                      .replace("+", "")
+                      .replace("-", "")
+                      .replace(/^0+/, "").length;
+        return new PrecisionNumber(value, precision);
+    }
+
+    abs() {
+        return new PrecisionNumber(Math.abs(this.value), this.precision);
+    }
+
+    plus(rhs: PrecisionNumber) {
+        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);
+        return fromResult(value, decimals);
+    }
+
+    minus(rhs: PrecisionNumber) {
+        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);
+        return fromResult(value, decimals);
+    }
+
+    valueOf() {
+        const scale = Math.pow(10, this.decimals);
+        const integer = Math.round(this.value * scale);
+        const value = integer / scale;
+        return value;
+    }
+
+    toString() {
+        return this.valueOf().toString();
+    }
+
+    toFixed() {
+        return NumberFormatter.toFixed(this.valueOf(), this.precision);
+    }
+
+    toPrecision() {
+        return NumberFormatter.toPrecision(this.valueOf(), this.precision);
+    }
+
+    toLocaleFixed() {
+        return NumberFormatter.toLocaleFixed(this.valueOf(), this.precision);
+    }
+
+    toLocalePrecision() {
+        return NumberFormatter.toLocalePrecision(
+            this.valueOf(),
+            this.precision,
+        );
+    }
+}
+
+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) {
+        // 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;
+    }
+
+    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) {
+    const abs = Math.abs(number);
+    if (abs < 10) return 1;
+    if (abs < 100) return 2;
+    if (abs < 1000) return 3;
+    if (abs < 10000) return 4;
+    if (abs < 100000) return 5;
+    if (abs < 1000000) return 6;
+    if (abs < 10000000) return 7;
+    if (abs < 100000000) return 8;
+    if (abs < 1000000000) return 9;
+    return Math.floor(Math.log10(abs) + 1);
+}

package/src/register-convention.spec.ts

@@ -1,52 +1,52 @@
-import { RegisterConvention } from "./register-convention";
-import { expect } from "chai";
-
-describe("getAggregate", () => {
-    it("instant register is instant", () => {
-        const result = RegisterConvention.getAggregate("flowTemperature");
-        expect(result).to.equal("instant");
-    });
-
-    it("avg register is avg", () => {
-        const result = RegisterConvention.getAggregate("avgFlowTemperature");
-        expect(result).to.equal("avg");
-    });
-});
-
-describe("toInstant", () => {
-    it("should convert instant", () => {
-        const registerId = RegisterConvention.toInstant("flowTemperature");
-        expect(registerId).to.equal("flowTemperature");
-    });
-
-    it("should convert aggregate", () => {
-        const registerId = RegisterConvention.toInstant("avgFlowTemperature");
-        expect(registerId).to.equal("flowTemperature");
-    });
-});
-
-describe("toAggregate", () => {
-    it("should convert instant to aggregate", () => {
-        const registerId = RegisterConvention.toAggregate(
-            "flowTemperature",
-            "avg",
-        );
-        expect(registerId).to.equal("avgFlowTemperature");
-    });
-
-    it("should convert aggregate to same aggregate", () => {
-        const registerId = RegisterConvention.toAggregate(
-            "avgFlowTemperature",
-            "avg",
-        );
-        expect(registerId).to.equal("avgFlowTemperature");
-    });
-
-    it("should convert aggregate to other aggregate", () => {
-        const registerId = RegisterConvention.toAggregate(
-            "avgFlowTemperature",
-            "min",
-        );
-        expect(registerId).to.equal("minFlowTemperature");
-    });
-});
+import { RegisterConvention } from "./register-convention";
+import { expect } from "chai";
+
+describe("getAggregate", () => {
+    it("instant register is instant", () => {
+        const result = RegisterConvention.getAggregate("flowTemperature");
+        expect(result).to.equal("instant");
+    });
+
+    it("avg register is avg", () => {
+        const result = RegisterConvention.getAggregate("avgFlowTemperature");
+        expect(result).to.equal("avg");
+    });
+});
+
+describe("toInstant", () => {
+    it("should convert instant", () => {
+        const registerId = RegisterConvention.toInstant("flowTemperature");
+        expect(registerId).to.equal("flowTemperature");
+    });
+
+    it("should convert aggregate", () => {
+        const registerId = RegisterConvention.toInstant("avgFlowTemperature");
+        expect(registerId).to.equal("flowTemperature");
+    });
+});
+
+describe("toAggregate", () => {
+    it("should convert instant to aggregate", () => {
+        const registerId = RegisterConvention.toAggregate(
+            "flowTemperature",
+            "avg",
+        );
+        expect(registerId).to.equal("avgFlowTemperature");
+    });
+
+    it("should convert aggregate to same aggregate", () => {
+        const registerId = RegisterConvention.toAggregate(
+            "avgFlowTemperature",
+            "avg",
+        );
+        expect(registerId).to.equal("avgFlowTemperature");
+    });
+
+    it("should convert aggregate to other aggregate", () => {
+        const registerId = RegisterConvention.toAggregate(
+            "avgFlowTemperature",
+            "min",
+        );
+        expect(registerId).to.equal("minFlowTemperature");
+    });
+});

package/src/register-convention.ts

@@ -1,70 +1,70 @@
-import type { RegisterDefinition } from "./register-definition";
-import { AggregateId } from "./aggregate-id";
-import type { RegisterId } from "./register-id";
-import { getRegisterId } from "./register-utils";
-
-export const aggregatePrefixes: { [aggregateId in AggregateId]: string } = {
-    instant: "",
-    diff: "diff",
-    min: "min",
-    max: "max",
-    avg: "avg",
-    sum: "sum",
-    cnt: "cnt",
-    ssq: "ssq",
-};
-
-class Convention {
-    public getAggregate(register: RegisterId | RegisterDefinition) {
-        const registerId = getRegisterId(register);
-        // Brute force all prefixes - if none of them, then it must be instant.
-        for (const aggregateString of Object.keys(aggregatePrefixes)) {
-            const aggregate = <AggregateId>aggregateString;
-            const prefix = aggregatePrefixes[aggregate];
-            if (prefix.length && isPrefix(registerId, prefix)) {
-                // Not instant - it was any of the others.
-                return aggregate;
-            }
-        }
-        return "instant";
-    }
-
-    toInstant(register: RegisterId | RegisterDefinition) {
-        const registerId = getRegisterId(register);
-        for (const prefix of Object.values(aggregatePrefixes)) {
-            if (prefix.length && isPrefix(registerId, prefix)) {
-                const tail = registerId.substr(prefix.length);
-                return <RegisterId>(tail[0].toLowerCase() + tail.substr(1));
-            }
-        }
-        return registerId;
-    }
-
-    toAggregate(
-        register: RegisterId | RegisterDefinition,
-        aggregate: AggregateId,
-    ) {
-        const instantRegisterId = this.toInstant(register);
-        if (aggregate === "instant") {
-            return instantRegisterId;
-        }
-        const prefix = aggregatePrefixes[aggregate];
-        return <RegisterId>(
-            (prefix +
-                instantRegisterId[0].toUpperCase() +
-                instantRegisterId.substr(1))
-        );
-    }
-}
-
-export function isPrefix(registerId: RegisterId, prefix: string) {
-    return (
-        registerId.startsWith(prefix) && isUppercase(registerId[prefix.length])
-    );
-}
-
-function isUppercase(input: string) {
-    return input.toUpperCase() === input;
-}
-
-export const RegisterConvention = new Convention();
+import type { RegisterDefinition } from "./register-definition";
+import { AggregateId } from "./aggregate-id";
+import type { RegisterId } from "./register-id";
+import { getRegisterId } from "./register-utils";
+
+export const aggregatePrefixes: { [aggregateId in AggregateId]: string } = {
+    instant: "",
+    diff: "diff",
+    min: "min",
+    max: "max",
+    avg: "avg",
+    sum: "sum",
+    cnt: "cnt",
+    ssq: "ssq",
+};
+
+class Convention {
+    public getAggregate(register: RegisterId | RegisterDefinition) {
+        const registerId = getRegisterId(register);
+        // Brute force all prefixes - if none of them, then it must be instant.
+        for (const aggregateString of Object.keys(aggregatePrefixes)) {
+            const aggregate = <AggregateId>aggregateString;
+            const prefix = aggregatePrefixes[aggregate];
+            if (prefix.length && isPrefix(registerId, prefix)) {
+                // Not instant - it was any of the others.
+                return aggregate;
+            }
+        }
+        return "instant";
+    }
+
+    toInstant(register: RegisterId | RegisterDefinition) {
+        const registerId = getRegisterId(register);
+        for (const prefix of Object.values(aggregatePrefixes)) {
+            if (prefix.length && isPrefix(registerId, prefix)) {
+                const tail = registerId.substr(prefix.length);
+                return <RegisterId>(tail[0].toLowerCase() + tail.substr(1));
+            }
+        }
+        return registerId;
+    }
+
+    toAggregate(
+        register: RegisterId | RegisterDefinition,
+        aggregate: AggregateId,
+    ) {
+        const instantRegisterId = this.toInstant(register);
+        if (aggregate === "instant") {
+            return instantRegisterId;
+        }
+        const prefix = aggregatePrefixes[aggregate];
+        return <RegisterId>(
+            (prefix +
+                instantRegisterId[0].toUpperCase() +
+                instantRegisterId.substr(1))
+        );
+    }
+}
+
+export function isPrefix(registerId: RegisterId, prefix: string) {
+    return (
+        registerId.startsWith(prefix) && isUppercase(registerId[prefix.length])
+    );
+}
+
+function isUppercase(input: string) {
+    return input.toUpperCase() === input;
+}
+
+export const RegisterConvention = new Convention();

package/src/register-definition.ts

@@ -1,23 +1,23 @@
-import type { AggregateId } from "./aggregate-id";
-import type { MeasureId } from "./measure-id";
-import type { RegisterId } from "./register-id";
-import type { UnitId } from "./unit-id";
-
-export interface RegisterDefinition {
-    /// The id of the register
-    id: RegisterId;
-    /// The register measure
-    measure: MeasureId;
-    /// The aggregate of the register
-    aggregate: AggregateId;
-    /// The possible register units
-    units: ReadonlyArray<UnitId>;
-    /// Whether the register can only be resolved by "present value".
-    immediate?: true;
-    /// An optional concise register name.
-    /// Only used for custom registers as locales exist for standard registers.
-    name?: string;
-    /// An optional register description.
-    /// Only used for custom registers as locales exist for standard registers.
-    description?: string;
-}
+import type { AggregateId } from "./aggregate-id";
+import type { MeasureId } from "./measure-id";
+import type { RegisterId } from "./register-id";
+import type { UnitId } from "./unit-id";
+
+export interface RegisterDefinition {
+    /// The id of the register
+    id: RegisterId;
+    /// The register measure
+    measure: MeasureId;
+    /// The aggregate of the register
+    aggregate: AggregateId;
+    /// The possible register units
+    units: ReadonlyArray<UnitId>;
+    /// Whether the register can only be resolved by "present value".
+    immediate?: true;
+    /// An optional concise register name.
+    /// Only used for custom registers as locales exist for standard registers.
+    name?: string;
+    /// An optional register description.
+    /// Only used for custom registers as locales exist for standard registers.
+    description?: string;
+}