@rinxun/numeric-calculator 1.0.7-alpha.1 → 1.0.8

package/README.md

@@ -64,6 +64,7 @@ The instance supports chain operations.
 - `minus(operands: IOperand[]) => instance`
 - `times(operands: IOperand[]) => instance`
 - `divide(operands: IOperand[]) => instance`
+- `round(fractionDigits?: number) => number`
 - `toPrecision(precision?: number) => number`
 - `toFixed(fractionDigits?: number) => string`
 
@@ -141,6 +142,26 @@ const result = new NC(-1000).divide(100, '20', 2).toPrecision(); // -1000/100/20
 
 
 
+<h4>inst.round(fractionDigits?: number, options?: { snap?: boolean })</h4>
+
+``` typescript
+const result = new NC().round(3); // 0
+const result = new NC(5.255).round(2); // 5.26
+const result = new NC(7.65).times(16.5).round(2); // => 7.65 * 16.5 = 126.225 ≈ 126.23
+const result = new NC(26.05).times(16.5).round(2); // => 26.05 * 16.5 = 429.825 ≈ 429.83
+```
+
+`options.snap` (default `false`) makes rounding tolerant to binary floating-point representation dust. After plain float arithmetic upstream, a true `95.015` can arrive as `95.01499999999942`, and exact-decimal rounding of the *represented* value then rounds down, disagreeing with the true value. With `snap`, the amplified value is nudged by a few ULPs relative to its own magnitude before `Math.round`, so only values sitting exactly on a rounding boundary are affected — everything beyond a few ULPs of the boundary keeps its exact-decimal result, and there is no magic number to tune:
+
+``` typescript
+const dust = 2959.9649999999997; // true value 2959.965, distorted by float subtraction upstream
+const result = new NC(dust).round(2); // 2959.96 — exact decimal of the represented value
+const result = new NC(dust).round(2, { snap: true }); // 2959.97 — matches the true half-up value
+const result = new NC(719.6446).round(2, { snap: true }); // 719.64 — values beyond a few ULPs of the boundary are untouched
+```
+
+
+
 <h4>inst.toPrecision(precision?: number)</h4>
 
 ```typescript
@@ -175,4 +196,4 @@ const result = new NC(10).plus(new NC().times(2, 4), '6').divide(new NC(12).minu
 
 <h2>Changelog</h2>
 
-If you have recently updated, please read the [changelog](https://github.com/rinxun/numeric-calculator/releases) for details of what has changed.
+If you have recently updated, please read the [changelog](https://github.com/rinxun/numeric-calculator/releases) for details of what has changed.

package/index.d.ts

@@ -3,6 +3,17 @@ declare type IConfig = {
     fractionDigits?: number;
     enableCheckBoundary?: boolean;
 };
+declare type IRoundOptions = {
+    /**
+     * @description when true, nudges the amplified value by a few ULPs relative
+     * to its own magnitude before rounding, so that binary floating-point
+     * representation dust does not flip values sitting exactly on a rounding
+     * boundary. Use it when the input may come from plain float arithmetic
+     * upstream, e.g. a true 95.015 arriving as 95.01499999999942. Defaults to
+     * false, which keeps the exact-decimal behavior of the represented value.
+     */
+    snap?: boolean;
+};
 declare type IOperand = Calculator | number | string;
 /**
  * @description Calculate addition, subtaction, multiplication, division precisely, for tackling the precision issue
@@ -134,8 +145,9 @@ declare class Calculator {
     /**
      *
      * @param {number} fractionDigits default to 2, should be in the range 0 - 20
+     * @param {IRoundOptions} options rounding options, see {@link IRoundOptions.snap}
      * @returns {number} rounded result
      */
-    round(fractionDigits?: number): number;
+    round(fractionDigits?: number, options?: IRoundOptions): number;
 }
 export default Calculator;

package/index.js

@@ -323,13 +323,21 @@ var Calculator = /** @class */ (function () {
     /**
      *
      * @param {number} fractionDigits default to 2, should be in the range 0 - 20
+     * @param {IRoundOptions} options rounding options, see {@link IRoundOptions.snap}
      * @returns {number} rounded result
      */
-    Calculator.prototype.round = function (fractionDigits) {
+    Calculator.prototype.round = function (fractionDigits, options) {
         var magnification = Math.pow(10, fractionDigits || this._fractionDigits || 2);
         var amplifyingResult = this.processTimes(this._VALUE || 0, magnification);
         this.checkBoundary(amplifyingResult);
-        return this.processDivide(Math.round(amplifyingResult), magnification);
+        // Dust observed in real pipelines reaches a few dozen ULPs (each float op
+        // distorts by at most 0.5 ULP), so 64x headroom. This stays safely below
+        // half an amplified unit at any magnitude (it scales with the value), and
+        // assumes inputs are meaningful well beyond ULP precision.
+        var tolerance = (options === null || options === void 0 ? void 0 : options.snap)
+            ? Math.abs(amplifyingResult) * Number.EPSILON * 64
+            : 0;
+        return this.processDivide(Math.round(amplifyingResult + tolerance), magnification);
     };
     return Calculator;
 }());

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rinxun/numeric-calculator",
-  "version": "1.0.7-alpha.1",
+  "version": "1.0.8",
   "description": "Calculate addition, subtraction, multiplication, division precisely, for tackling the precision issue",
   "keywords": [
     "long",