@numio/bigmath 1.0.5 → 1.0.6

package/README.md

@@ -1,55 +1,45 @@
-# @numio/bigmath
-
-@numio/bigmath is an arbitrary-precision arithmetic library. This library
-provides functions for performing arithmetic operations (addition, subtraction,
-multiplication, and division) on numbers of arbitrary length. It addresses the
-limitations of JavaScript's built-in number type, which suffers from precision
-loss when dealing with very large or very small numbers, or numbers with more
-than 15 significant digits.
-
-## Key Features and Benefits
-
-- **Arbitrary Precision:** Handles numbers of any length, avoiding the
-  limitations of JavaScript's `Number` type. This allows for calculations with
-  extremely large or small numbers without loss of precision.
-- **No Precision Loss:** Eliminates precision errors that occur when using
-  numeric literals with more than 15 significant digits. The library ensures
-  accurate calculations even with very long numbers.
-- **Four Basic Operations:** Provides functions for addition (`add`),
-  subtraction (`sub`), multiplication (`mul`), and division (`div`).
-- **Decimal Handling:** Correctly handles decimal numbers and performs
-  calculations accurately, including scenarios involving negative numbers.
-- **Division Precision Control:** The `div` function allows you to specify the
-  number of digits after the decimal point for the result. The default precision
-  is 20 digits.
-- **Easy to Use:** The library provides simple and intuitive functions for
-  performing arithmetic operations.
-
-## How it Solves the Problem
-
-JavaScript's `Number` type uses a 64-bit floating-point representation (IEEE
-754), which can lead to precision issues when dealing with numbers that exceed
-its representable range or require more than 15 significant digits. This library
-likely uses a different representation internally (e.g., strings or arrays of
-digits) to store and manipulate numbers, effectively bypassing the limitations
-of the built-in `Number` type. This allows it to perform calculations on numbers
-of virtually unlimited size and maintain accuracy.
-
-## Use Cases
-
-This library is particularly useful in scenarios where precise calculations with
-large numbers are essential, such as:
-
-- **Financial applications:** Dealing with large sums of money or precise
-  interest calculations.
-- **Scientific computing:** Working with very large or small numbers in
-  scientific simulations.
-- **Cryptography:** Implementing cryptographic algorithms that require high
-  precision.
-- **Any application** where exceeding JavaScript's number limits is a concern.
+# @numio/bigmath: Precise Arithmetic Beyond JavaScript's Limits
+
+**Do you struggle with inaccurate calculations involving very large or very small numbers, or decimal numbers with high precision in JavaScript?**
+
+`@numio/bigmath` is your solution! This library provides a robust set of functions for performing **arbitrary-precision arithmetic**, effectively overcoming the limitations of JavaScript's built-in `Number` type. Say goodbye to unexpected rounding errors and precision loss when dealing with numbers that exceed 15 significant digits or involve complex decimal operations.
+
+## Why Choose @numio/bigmath?
+
+**Solve Precision Problems:**
+
+* **Handle Numbers of Any Size:** Perform calculations on integers and decimals of virtually unlimited length, without the risk of JavaScript's `Number` limitations.
+* **Eliminate Precision Loss:** Achieve accurate results even with numeric literals exceeding 15 significant digits, ensuring the integrity of your calculations.
+* **Precise Decimal Operations:** Execute addition, subtraction, multiplication, and division on decimal numbers with guaranteed accuracy, including scenarios with negative values.
+
+**Unlock Advanced Numerical Operations:**
+
+* **Control Division Precision:** Specify the exact number of digits after the decimal point for division results, with a default precision of 20 digits for high accuracy.
+* **Flexible Rounding:** Round numbers to the nearest integer or a specific number of decimal places with various rounding modes (up, down, half-up, half-down, half-even, half-odd) to meet your exact requirements.
+* **Round Based on Significant Figures:** Control rounding based on the number of significant figures, crucial for scientific and engineering applications.
+* **Chain Operations with Pipe:** Simplify complex calculations by chaining arithmetic operations in a readable and intuitive manner.
+* **Analyze Data Distribution:** Calculate quartiles (Q1, Q2, Q3) to understand the spread and central tendency of your numerical data, helping identify outliers and the shape of the distribution.
+* **Sort Numbers Accurately:** Sort arrays of numbers, including negative and decimal values, in ascending or descending order, correctly handling string representations of numbers that JavaScript's native sort might misinterpret.
+* **Calculate Central Tendency:** Easily compute the mean (average) of a set of numbers.
+* **Identify Extremes:** Find the maximum and minimum values within an array of numbers.
+
+## When is @numio/bigmath essential?
+
+This library is particularly invaluable in applications where numerical accuracy and the ability to handle large numbers are paramount:
+
+* **Financial Applications:** Accurate calculations for large sums of money, precise interest rates, and complex financial modeling.
+* **Scientific Computing:** Working with extremely large or small numbers in simulations, data analysis, and research.
+* **Cryptography:** Implementing cryptographic algorithms that rely on high-precision arithmetic.
+* **E-commerce and Payments:** Handling precise amounts and avoiding rounding errors in transactions.
+* **Data Analysis and Statistics:** Performing accurate statistical calculations on datasets with varying scales.
+* **Any Scenario Exceeding JavaScript's Number Limits:** Ensuring the reliability of your calculations when dealing with numbers beyond the safe integer limit or requiring more than 15 significant digits.
+
+With `@numio/bigmath`, you can confidently perform complex arithmetic operations with the assurance of accuracy, regardless of the size or precision of the numbers involved.
 
 ### Latest update
 
+Added sorting, min/max, mean.
+
 Added quartile functionality. When you might need it?
 Understanding Distribution. Quartiles (Q1, Q2, and Q3) split a dataset into four groups, each representing 25% of the data. 
 Identifying Outliers. They help visualize the shape and spread of the data, revealing whether it's skewed or symmetrical. 
@@ -210,7 +200,7 @@ pipe.add(addNums) // 6
   .div(divNums) // 6 / 4 = 1.5 
   .sub(subNums) // 1.5 - 0.2 - 0.3 = 1
   .mul(mulNums) // 1 * 2 * 5 * 0.2 = 2
-  .calc()
+  .calc() // convert end result to readable string
 ```
 
 ### Quartile
@@ -222,6 +212,45 @@ quartile(["0.001", "0.3", "0.4", "1"]) // { Q1: "0.1505", Q2: "0.35", Q3: "0.7"
 
 ```
 
+### Sort
+```javascript
+import { sort } from "@numio/bigmath";
+
+// native js sort for strings
+["1", "10", "11", "101", "11", "10", "1"].sort() // ["1", "1", "10", "10", "101", "11", "11"]
+
+// sort from "@numio/bigmath"
+sort(["1", "10", "11", "101", "11", "10", "1"]) // ["1", "1", "10", "10", "11", "11", "101"]
+
+// ASC sorting
+sort(["-0.1", "0.1", "-1"], "asc") // ["-1", "-0.1", "0.1"]
+
+// DESC sorting
+sort(["-0.1", "0.1", "-1"], "desc") // ["0.1", "-0.1", "1"]
+
+```
+
+### Mean 
+```javascript
+import { mean } from "@numio/bigmath";
+
+mean(["5", "4", "3", "2", "1", "0"]) // "2.5"
+mean(["0.5", "0.4", "0.3", "0.2", "0.1", "0"]) // "0.25"
+```
+
+### Max 
+```javascript
+import { max } from "@numio/bigmath";
+
+max(["2", "-1", "0.1"]) // 2;
+```
+
+### Min
+```javascript
+import { min } from "@numio/bigmath";
+
+min(["2", "-1", "0.1"]) // -1;
+```
 
 Does not have a limitation on the number of digits. You can use any length you'd
 like
@@ -239,7 +268,10 @@ const float = mul(
 ); // 0.00000000000000000000000000000000000000000000000000000000000000000000000000018
 ```
 
-Download from NPM - https://www.npmjs.com/package/@numio/bigmath\
-Download from JSR - https://jsr.io/@numio/bigmath\
-Home page - https://github.com/shpunter/numio-bigmath/blob/main/README.md\
+Download from NPM - https://www.npmjs.com/package/@numio/bigmath
+
+Download from JSR - https://jsr.io/@numio/bigmath
+
+Home page - https://github.com/shpunter/numio-bigmath/blob/main/README.md
+
 License - https://github.com/shpunter/numio-bigmath/blob/main/LICENSE

package/index.d.ts

@@ -5,4 +5,7 @@ import { div } from "./src/mathOperations/div/index.d.ts";
 import { round } from "./src/round/index.d.ts";
 import { pipe } from "./src/pipe/main.d.ts";
 import { quartile } from "./src/quartile/main.d.ts";
-export { add, div, mul, pipe, quartile, round, sub };
+import { sort } from "./src/sort/main.d.ts";
+import { mean } from "./src/mean/main.d.ts";
+import { min, max } from "./src/compare/main.d.ts";
+export { add, div, max, mean, min, mul, pipe, quartile, round, sort, sub };

package/index.js

@@ -5,4 +5,7 @@ import { div } from "./src/mathOperations/div/index.js";
 import { round } from "./src/round/index.js";
 import { pipe } from "./src/pipe/main.js";
 import { quartile } from "./src/quartile/main.js";
-export { add, div, mul, pipe, quartile, round, sub };
+import { sort } from "./src/sort/main.js";
+import { mean } from "./src/mean/main.js";
+import { min, max } from "./src/compare/main.js";
+export { add, div, max, mean, min, mul, pipe, quartile, round, sort, sub };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@numio/bigmath",
   "description": "@numio/bigmath is an arbitrary-precision arithmetic library. It can be used for basic operations with decimal numbers (integers and float)",
-  "version": "1.0.5",
+  "version": "1.0.6",
   "keywords": [
     "precision",
     "arithmetic",
@@ -33,7 +33,12 @@
     "Q1",
     "Q2",
     "Q3",
-    "round"
+    "round",
+    "min",
+    "max",
+    "sort",
+    "mean",
+    "significant figures"
   ],
   "repository": {
     "type": "git",

package/src/compare/main.d.ts

@@ -0,0 +1,7 @@
+import type { CompareRawFn, Max, MaxRawFn, Min, MinRawFn } from "./types.d.ts";
+export declare const compareRawFn: CompareRawFn;
+export declare const maxRawFn: MaxRawFn;
+export declare const minRawFn: MinRawFn;
+export declare const max: Max;
+export declare const min: Min;
+export declare const isGreater: (l: string, r: string) => boolean;

package/src/compare/main.js

@@ -0,0 +1,78 @@
+import { a2s, s2a } from "../shared/utils.js";
+export var compareRawFn = function (l, r) {
+    var _a;
+    var idx = 0;
+    var _b = [l, r], left = _b[0], right = _b[1];
+    var lIsNeg = l.isNegative, lIntLen = l.intLength;
+    var rIsNeg = r.isNegative, rIntLen = r.intLength;
+    var lenL = l.array.length;
+    var lenR = r.array.length;
+    var bothNeg = lIsNeg && rIsNeg;
+    var bothPos = !lIsNeg && !rIsNeg;
+    var bothIntPos = lIntLen > 0 && rIntLen > 0;
+    var bothIntNeg = lIntLen <= 0 && rIntLen <= 0;
+    if (lIsNeg && !rIsNeg)
+        return [r, false];
+    if (!lIsNeg && rIsNeg)
+        return [l, true];
+    if (bothPos && bothIntPos && lIntLen < rIntLen)
+        return [r, false];
+    if (bothPos && bothIntNeg && lIntLen < rIntLen)
+        return [r, false];
+    if (bothNeg && bothIntPos && lIntLen < rIntLen)
+        return [l, true];
+    if (bothNeg && bothIntNeg && lIntLen < rIntLen)
+        return [l, true];
+    if (bothNeg && bothIntNeg && lIntLen > rIntLen)
+        return [r, false];
+    if (bothNeg && bothIntPos && lIntLen > rIntLen)
+        return [r, false];
+    if (bothPos && bothIntPos && lIntLen > rIntLen)
+        return [l, true];
+    if (bothPos && bothIntNeg && lIntLen > rIntLen)
+        return [l, true];
+    if (bothNeg)
+        _a = [r, l], left = _a[0], right = _a[1];
+    while (idx < (lenL > lenR ? lenL : lenR)) {
+        var numL = left.array[idx];
+        var numR = right.array[idx];
+        if (!numL && bothPos)
+            return [r, false];
+        if (!numR && bothPos)
+            return [l, true];
+        if (!numL && bothNeg)
+            return [l, true];
+        if (!numR && bothNeg)
+            return [r, false];
+        if (numL !== numR) {
+            return numL > numR ? [l, true] : [r, false];
+        }
+        idx += 1;
+    }
+    return [l, true];
+};
+export var maxRawFn = function (array) {
+    var max = array[0];
+    for (var i = 1; i < array.length; i++) {
+        compareRawFn(max, array[i])[1] || (max = array[i]);
+    }
+    return max;
+};
+export var minRawFn = function (array) {
+    var min = array[0];
+    for (var i = 1; i < array.length; i++) {
+        compareRawFn(min, array[i])[1] && (min = array[i]);
+    }
+    return min;
+};
+export var max = function (strs) {
+    var array = strs.map(function (str) { return s2a(str); });
+    return a2s(maxRawFn(array));
+};
+export var min = function (strs) {
+    var array = strs.map(function (str) { return s2a(str); });
+    return a2s(minRawFn(array));
+};
+export var isGreater = function (l, r) {
+    return compareRawFn(s2a(l), s2a(r))[1];
+};

package/src/compare/types.d.ts

@@ -0,0 +1,6 @@
+import type { InputData } from "../types.d.ts";
+export type CompareRawFn = (left: InputData, right: InputData) => [InputData, boolean];
+export type Min = (strs: string[]) => string;
+export type Max = (strs: string[]) => string;
+export type MinRawFn = (array: InputData[]) => InputData;
+export type MaxRawFn = (array: InputData[]) => InputData;

package/src/mean/main.d.ts

@@ -0,0 +1,2 @@
+import type { Mean } from "./types.d.ts";
+export declare const mean: Mean;

package/src/mean/main.js

@@ -0,0 +1,4 @@
+import { pipe } from "../pipe/main.js";
+export var mean = function (array) {
+    return pipe.add(array).div([array.length.toString()]).calc();
+};

package/src/mean/types.d.ts

@@ -0,0 +1 @@
+export type Mean = (array: string[]) => string;

package/src/shared/utils.js

@@ -1,3 +1,6 @@
+var convert = function (isNegative, array) {
+    return (isNegative ? "-" : "") + String.fromCharCode.apply(String, array);
+};
 export var a2s = function (_a) {
     var array = _a.array, isFloat = _a.isFloat, isNegative = _a.isNegative, intLength = _a.intLength;
     var result = [];
@@ -21,14 +24,14 @@ export var a2s = function (_a) {
         }
         else {
             for (var i = 0; i < lastValuableIdx; i++) {
-                if (i === intLength)
-                    result.push(46);
+                i === intLength && result.push(46);
                 result.push(array[i]);
             }
         }
-        return (isNegative ? "-" : "") + String.fromCharCode.apply(String, result);
+        result.at(-1) === 46 && result.pop();
+        return convert(isNegative, result);
     }
-    return (isNegative ? "-" : "") + String.fromCharCode.apply(String, array).trim();
+    return convert(isNegative, array);
 };
 export var s2a = function (string) {
     var array = Array(0);

package/src/sort/constants.d.ts

@@ -0,0 +1,3 @@
+export declare const ASC: "asc";
+export declare const DESC: "desc";
+export declare const sortingArray: ("asc" | "desc")[];

package/src/sort/constants.js

@@ -0,0 +1,3 @@
+export var ASC = "asc";
+export var DESC = "desc";
+export var sortingArray = [ASC, DESC];

package/src/sort/main.d.ts

@@ -0,0 +1,2 @@
+import type { Sort } from "./types.d.ts";
+export declare const sort: Sort;

package/src/sort/main.js

@@ -0,0 +1,43 @@
+import { compareRawFn } from "../compare/main.js";
+import { a2s, s2a } from "../shared/utils.js";
+import { ASC } from "./constants.js";
+var heapify = function (array, len, i, sorting) {
+    var _a;
+    var idxL = 2 * i + 1;
+    var idxR = idxL + 1;
+    var idx = i;
+    if (sorting === ASC) {
+        if (idxL < len && compareRawFn(array[idxL], array[idx])[1])
+            idx = idxL;
+        if (idxR < len && compareRawFn(array[idxR], array[idx])[1])
+            idx = idxR;
+    }
+    else {
+        if (idxL < len && compareRawFn(array[idx], array[idxL])[1])
+            idx = idxL;
+        if (idxR < len && compareRawFn(array[idx], array[idxR])[1])
+            idx = idxR;
+    }
+    if (idx !== i) {
+        _a = [array[idx], array[i]], array[i] = _a[0], array[idx] = _a[1];
+        heapify(array, len, idx, sorting);
+    }
+};
+var sortRawFn = function (array, sorting) {
+    var _a;
+    var len = array.length;
+    for (var i = (len >> 1) - 1; i >= 0; i--) {
+        heapify(array, len, i, sorting);
+    }
+    for (var i = len - 1; i >= 0; i--) {
+        _a = [array[i], array[0]], array[0] = _a[0], array[i] = _a[1];
+        heapify(array, i, 0, sorting);
+    }
+    return array;
+};
+export var sort = function (array, sorting) {
+    if (sorting === void 0) { sorting = ASC; }
+    var inputDataArray = array.map(function (str) { return s2a(str); });
+    sortRawFn(inputDataArray, sorting);
+    return inputDataArray.map(function (input) { return a2s(input); });
+};

package/src/sort/types.d.ts

@@ -0,0 +1,6 @@
+import type { InputData } from "../types.d.ts";
+import type { sortingArray } from "./constants.d.ts";
+export type Sorting = typeof sortingArray[number];
+export type Sort = (array: string[], sorting?: Sorting) => string[];
+export type SortRawFn = (array: InputData[], sorting: Sorting) => InputData[];
+export type Heapify = (array: InputData[], len: number, i: number, sorting: Sorting) => void;