@numio/bigmath 2.0.1 → 2.1.0

package/README.md

@@ -21,6 +21,8 @@
 * **Round Based on Significant Figures:** Control rounding based on the number of significant figures, crucial for scientific and engineering applications.
 * **Calculate Roots:**
     * **Calculate Square Root (`sqrt`):** Compute the square root of a number with arbitrary precision. You can also specify the desired precision of the result.
+    * **NEW! Calculate Cube Root (`cbrt`):** Determine the cube root of a number with arbitrary precision, allowing you to specify the desired accuracy.
+
 * **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):** Understand the spread and central tendency of your numerical data, helping identify outliers and the shape of the distribution.
@@ -29,9 +31,12 @@
 * **Compare Numbers:**
     * **Check for Equality (`isEqual`):** Accurately determine if two arbitrary-precision numbers are equal.
     * **Check if Left is Greater (`isLeftGreater`):** Precisely compare two arbitrary-precision numbers to see if the left operand is greater than the right.
+    * **NEW! Check if Left is Greater or Equal (`isLeftGreaterOrEqual`):** Precisely compare two arbitrary-precision numbers to determine if the left operand is greater than or equal to the right.
 * **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.
+* **NEW! Calculate Absolute Value (`abs`):** Determine the non-negative value of a number, regardless of its sign.
+* **NEW! Convert Number to Another Base (`toBase`):** Seamlessly convert numbers between decimal, hexadecimal (HEX), binary, and octal representations.
 
 ## When is @numio/bigmath essential?
 
@@ -208,18 +213,24 @@ round("1.000119", { decimals: 2, sigFig: true }); // 1
 ### Pipe
 
 ```javascript
-import { pipe } from "@numio/bigmath";
+import { Pipe } from "@numio/bigmath";
 
 const addNums = ["1", "2", "3"];
 const subNums = ["0.2", "0.3"];
 const divNums = ["4"];
 const mulNums = ["2", "5", "0.2"];
 
-pipe.add(addNums) // 6
+new 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() // convert end result to readable string
+
+new Pipe().sub(["1", "5"]) // 1 - 5 = -4
+  .abs() // 4 - returns absolute value
+
+new Pipe().add(["10", "5"]) // 11 + 5 = 15
+  .resultToBase(16) // f - returns result converted to base 16
 ```
 
 ### Quartile
@@ -289,6 +300,16 @@ isLeftGreater({left: "0.1", right: "0.1"}) // false;
 isLeftGreater({left: "0.1", right: "-0.1"}) // true;
 ```
 
+### IsLeftGreaterOrEqual
+```javascript
+import { isLeftGreaterOrEqual } from "@numio/bigmath";
+
+isLeftGreaterOrEqual({left: "0.1", right: "2"}) // false;
+isLeftGreaterOrEqual({left: "2", right: "0.1"}) // true;
+isLeftGreaterOrEqual({left: "0.1", right: "0.1"}) // true;
+isLeftGreaterOrEqual({left: "0.1", right: "-0.1"}) // true;
+```
+
 ### MAD - Median Absolute Deviation
 ```javascript
 import { MAD } from "@numio/bigmath";
@@ -315,12 +336,46 @@ sqrt("3", "0.01") // 1.732;
 sqrt("3", "0.000000000000000000001") // 1.732050807568877293527;
 ```
 
+### CBRT - cube root of a number
+```javascript
+import { cbrt } from "@numio/bigmath";
+
+cbrt("37") // 3;
+cbrt("1000") // 10;
+cbrt("15"), // 2.4662120743305
+
+// you can change precision of a result (second parameter), 
+cbrt("15", "0.001") // 2.466
+```
+
+### ABS - absolute value
+```javascript
+import { abs } from "@numio/bigmath";
+
+abs("-1") // 1;
+abs("1") // 1;
+```
+
+### toBase - convert number to another base
+```javascript
+import { toBase } from "@numio/bigmath";
+
+toBase({ value: "11", toBase: 16 }) // b
+// 0x - HEX
+toBase({ value: "0xb", toBase: 10 }) // 11
+// 0b - binary
+toBase({ value: "0b101", toBase: 10 }) // 5
+toBase({ value: "0b1101", toBase: 16 }) // d
+// 0o - octal
+toBase({ value: "0o11", toBase: 10 }) // 9
+```
+
 Does not have a limitation on the number of digits. You can use any length you'd
 like
 
 ```javascript
 // NO precision loss using numeric literals with more than 15 significant digits.
-const int = sub(
+const int = add(
   "999999999999999999999999999999999999999999999999999999999999999",
   "2",
 ); // "1000000000000000000000000000000000000000000000000000000000000001"

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": "2.0.1",
+  "version": "2.1.0",
   "keywords": [
     "precision",
     "arithmetic",

package/src/abs/main.d.ts

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

package/src/abs/main.js

@@ -0,0 +1,6 @@
+import { bi2s, s2bi } from "../shared/utils.js";
+import { absInner } from "./utils.js";
+export const abs = (value) => {
+    const [bi, fpe] = absInner(s2bi(value));
+    return bi2s(bi, fpe);
+};

package/src/abs/types.d.ts

@@ -0,0 +1,3 @@
+import type { BI } from "../shared/types.d.ts";
+export type Abs = (value: string) => string;
+export type AbsInner = (value: BI) => BI;

package/src/abs/utils.d.ts

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

package/src/abs/utils.js

@@ -0,0 +1,3 @@
+export const absInner = ([bi, fpe]) => {
+    return [bi < 0n ? bi * -1n : bi, fpe];
+};

package/src/cbrt/main.d.ts

@@ -0,0 +1,3 @@
+import type { Cbrt } from "./types.d.ts";
+/** Find cube root of a number */
+export declare const cbrt: Cbrt;

package/src/cbrt/main.js

@@ -0,0 +1,9 @@
+import { round } from "../round/main.js";
+import { bi2s, s2bi } from "../shared/utils.js";
+import { cbrtInner } from "./utils.js";
+/** Find cube root of a number */
+export const cbrt = (value, precision) => {
+    const valueInner = s2bi(value);
+    const [[bi, fpe], decimals] = cbrtInner(valueInner, precision ? s2bi(precision) : undefined);
+    return round(bi2s(bi, fpe), { decimals });
+};

package/src/cbrt/types.d.ts

@@ -0,0 +1,3 @@
+import type { BI } from "../shared/types.d.ts";
+export type CbrtInner = (value: BI, prec?: BI, max?: number) => [BI, number];
+export type Cbrt = (value: string, precision?: string) => string;

package/src/cbrt/utils.d.ts

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

package/src/cbrt/utils.js

@@ -0,0 +1,22 @@
+import { isLeftGreaterInner } from "../compare/utils.js";
+import { divInner } from "../operations/div/utils.js";
+import { PipeInner } from "../pipe/utils.js";
+import { calcInner } from "../shared/utils.js";
+export const cbrtInner = (value, prec = [1n, 13], max = 100) => {
+    let guess = value;
+    for (let i = 0; i < max; i++) {
+        const mul = calcInner([guess, guess], (a, b) => a * b);
+        const nextGuess = new PipeInner().add([
+            calcInner([guess, [2n, 0]], (a, b) => a * b),
+            divInner([value, mul], 20),
+        ]).div([[3n, 0]]).calc();
+        let [bi, fpe] = new PipeInner().sub([nextGuess, guess]).calc();
+        if (bi < 0n)
+            bi *= -1n;
+        if (isLeftGreaterInner({ left: prec, right: [bi, fpe] })) {
+            return [nextGuess, prec[1]];
+        }
+        guess = nextGuess;
+    }
+    return [guess, prec[1]];
+};

package/src/compare/main.d.ts

@@ -1,9 +1,11 @@
-import type { IsEqual, IsLeftGreater, Max, Min } from "./types.d.ts";
+import type { IsEqual, IsLeftGreater, IsLeftGreaterOrEqual, Max, Min } from "./types.d.ts";
 /** This function returns max value. */
 export declare const max: Max;
 /** This function returns min value. */
 export declare const min: Min;
 /** This function returns if left value is greater than right value */
 export declare const isLeftGreater: IsLeftGreater;
+/** This function returns if left value is greater than right value */
+export declare const isLeftGreaterOrEqual: IsLeftGreaterOrEqual;
 /** This function returns if left and right values are equal */
 export declare const isEqual: IsEqual;

package/src/compare/main.js

@@ -1,5 +1,5 @@
 import { bi2s, s2bi } from "../shared/utils.js";
-import { isEqualInner, isLeftGreaterInner, maxInner, minInner, } from "./utils.js";
+import { isEqualInner, isLeftGreaterInner, isLeftGreaterOrEqualInner, maxInner, minInner, } from "./utils.js";
 /** This function returns max value. */
 export const max = (array) => {
     const arrayInner = array.map((str) => s2bi(str));
@@ -16,6 +16,10 @@ export const min = (array) => {
 export const isLeftGreater = ({ left, right }) => {
     return isLeftGreaterInner({ left: s2bi(left), right: s2bi(right) });
 };
+/** This function returns if left value is greater than right value */
+export const isLeftGreaterOrEqual = ({ left, right }) => {
+    return isLeftGreaterOrEqualInner({ left: s2bi(left), right: s2bi(right) });
+};
 /** This function returns if left and right values are equal */
 export const isEqual = ({ left, right }) => {
     return isEqualInner({ left: s2bi(left), right: s2bi(right) });

package/src/compare/types.d.ts

@@ -1,16 +1,24 @@
 import type { BI } from "../shared/types.d.ts";
 export type Min = (strs: string[]) => string;
 export type Max = Min;
-export type IsLeftGreater = (attr: {
+export type IsLeftGreater = (arg: {
+    left: string;
+    right: string;
+}) => boolean;
+export type IsEqual = (arg: {
+    left: string;
+    right: string;
+}) => boolean;
+export type IsLeftGreaterOrEqual = (arg: {
     left: string;
     right: string;
 }) => boolean;
-export type IsEqual = IsLeftGreater;
 export type CompareInner = (left: BI, right: BI) => [BI, number];
 export type MinInner = (array: BI[]) => BI;
 export type MaxInner = MinInner;
-export type IsEqualInner = (attr: {
+export type IsEqualInner = (arg: {
     left: BI;
     right: BI;
 }) => boolean;
 export type IsLeftGreaterInner = IsEqualInner;
+export type IsLeftGreaterOrEqualInner = IsEqualInner;

package/src/compare/utils.d.ts

@@ -1,6 +1,7 @@
-import type { CompareInner, IsEqualInner, IsLeftGreaterInner, MaxInner, MinInner } from "./types.d.ts";
+import type { CompareInner, IsEqualInner, IsLeftGreaterInner, IsLeftGreaterOrEqualInner, MaxInner, MinInner } from "./types.d.ts";
 export declare const maxInner: MaxInner;
 export declare const minInner: MinInner;
 export declare const compareInner: CompareInner;
 export declare const isEqualInner: IsEqualInner;
 export declare const isLeftGreaterInner: IsLeftGreaterInner;
+export declare const isLeftGreaterOrEqualInner: IsLeftGreaterOrEqualInner;

package/src/compare/utils.js

@@ -73,3 +73,6 @@ export const isEqualInner = ({ left, right }) => {
 export const isLeftGreaterInner = ({ left, right }) => {
     return compareInner(left, right)[1] > 0;
 };
+export const isLeftGreaterOrEqualInner = ({ left, right }) => {
+    return compareInner(left, right)[1] >= 0;
+};

package/src/pipe/main.d.ts

@@ -1,12 +1,13 @@
 import type { BI2S } from "../shared/types.d.ts";
+/** Using this function you can chain operations (add, sub, div, mul). */
 export declare class Pipe {
     #private;
-    constructor();
+    constructor(value?: string);
     add(array: string[]): Pipe;
     sub(array: string[]): Pipe;
     div(array: string[], limit?: number): Pipe;
     mul(array: string[]): Pipe;
+    abs(): Pipe;
     calc(): ReturnType<BI2S>;
+    resultToBase(radix: number): string;
 }
-/** Using this function you can chain operations (add, sub, div, mul). */
-export declare const pipe: Pipe;

package/src/pipe/main.js

@@ -1,20 +1,23 @@
-var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (receiver, state, kind, f) {
-    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
-    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
-    return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
-};
 var __classPrivateFieldSet = (this && this.__classPrivateFieldSet) || function (receiver, state, value, kind, f) {
     if (kind === "m") throw new TypeError("Private method is not writable");
     if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a setter");
     if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot write private member to an object whose class did not declare it");
     return (kind === "a" ? f.call(receiver, value) : f ? f.value = value : state.set(receiver, value)), value;
 };
+var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (receiver, state, kind, f) {
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
+    return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
+};
 var _Pipe_result;
 import { bi2s, calcInner, s2bi } from "../shared/utils.js";
 import { divInner } from "../operations/div/utils.js";
+import { absInner } from "../abs/utils.js";
+/** Using this function you can chain operations (add, sub, div, mul). */
 export class Pipe {
-    constructor() {
+    constructor(value) {
         _Pipe_result.set(this, void 0);
+        value && (__classPrivateFieldSet(this, _Pipe_result, s2bi(value), "f"));
     }
     add(array) {
         const arrayInner = array.map((str) => s2bi(str));
@@ -36,14 +39,29 @@ export class Pipe {
         __classPrivateFieldSet(this, _Pipe_result, calcInner(arrayInner, (a, b) => a * b, __classPrivateFieldGet(this, _Pipe_result, "f")), "f");
         return this;
     }
+    abs() {
+        if (!__classPrivateFieldGet(this, _Pipe_result, "f")) {
+            throw new Error("Cannot calculate the absolute value of an undefined.");
+        }
+        __classPrivateFieldSet(this, _Pipe_result, absInner(__classPrivateFieldGet(this, _Pipe_result, "f")), "f");
+        return this;
+    }
     calc() {
+        if (!__classPrivateFieldGet(this, _Pipe_result, "f")) {
+            throw new Error("Cannot calculate based on an undefined input.");
+        }
+        const [bi, fpe] = __classPrivateFieldGet(this, _Pipe_result, "f");
+        return bi2s(bi, fpe);
+    }
+    resultToBase(radix) {
         var _a;
-        const [bi, fpe] = (_a = __classPrivateFieldGet(this, _Pipe_result, "f")) !== null && _a !== void 0 ? _a : [0n, 0];
-        const result = bi2s(bi, fpe);
-        __classPrivateFieldSet(this, _Pipe_result, undefined, "f");
-        return result;
+        if (!__classPrivateFieldGet(this, _Pipe_result, "f")) {
+            throw new Error(`Cannot convert an undefined result to base ${radix}.`);
+        }
+        if (__classPrivateFieldGet(this, _Pipe_result, "f")[1] > 0) {
+            throw new Error(`Cannot convert non integer result to base ${radix}.`);
+        }
+        return (_a = __classPrivateFieldGet(this, _Pipe_result, "f")) === null || _a === void 0 ? void 0 : _a[0].toString(radix);
     }
 }
 _Pipe_result = new WeakMap();
-/** Using this function you can chain operations (add, sub, div, mul). */
-export const pipe = new Pipe();

package/src/sqrt/main.js

@@ -2,9 +2,8 @@ import { round } from "../round/main.js";
 import { bi2s, s2bi } from "../shared/utils.js";
 import { sqrtInner } from "./utils.js";
 /** Find square root of a number */
-export const sqrt = (str, precision) => {
-    const inputInner = s2bi(str);
-    const [[bi, fpe], decimals] = sqrtInner(inputInner, precision ? s2bi(precision) : undefined);
-    const outputStr = bi2s(bi, fpe);
-    return round(outputStr, { decimals });
+export const sqrt = (value, precision) => {
+    const valueInner = s2bi(value);
+    const [[bi, fpe], decimals] = sqrtInner(valueInner, precision ? s2bi(precision) : undefined);
+    return round(bi2s(bi, fpe), { decimals });
 };

package/src/sqrt/types.d.ts

@@ -1,3 +1,3 @@
 import type { BI } from "../shared/types.d.ts";
-export type SqrtInner = (input: BI, prec?: BI, max?: number) => [BI, number];
-export type Sqrt = (str: string, precision?: string) => string;
+export type SqrtInner = (value: BI, prec?: BI, max?: number) => [BI, number];
+export type Sqrt = (value: string, precision?: string) => string;

package/src/sqrt/utils.js

@@ -1,14 +1,12 @@
 import { isLeftGreaterInner } from "../compare/utils.js";
 import { PipeInner } from "../pipe/utils.js";
-const halfInner = [5n, 1];
-const precDef = [1n, 13];
-export const sqrtInner = (input, prec = precDef, max = 100) => {
-    let guess = input;
+export const sqrtInner = (value, prec = [1n, 13], max = 100) => {
+    let guess = value;
     for (let i = 0; i < max; i++) {
         const nextGuess = new PipeInner()
-            .div([input, guess])
+            .div([value, guess])
             .add([guess])
-            .mul([halfInner])
+            .mul([[5n, 1]])
             .calc();
         let [bi, fpe] = new PipeInner().sub([nextGuess, guess]).calc();
         if (bi < 0n)

package/src/toBase/main.d.ts

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

package/src/toBase/main.js

@@ -0,0 +1,3 @@
+export const toBase = ({ value, toBase }) => {
+    return BigInt(value).toString(toBase);
+};

package/src/toBase/types.d.ts

@@ -0,0 +1,4 @@
+export type ToBase = (arg: {
+    value: string;
+    toBase: number;
+}) => string;