Add toString()

bpierre · Sep 24, 2023 · c78ac78 · c78ac78
1 parent 0edde1b
commit c78ac78
Show file tree

Hide file tree

Showing 4 changed files with 58 additions and 5 deletions.
diff --git a/README.md b/README.md
@@ -416,6 +416,27 @@ toNumber(value, { digits: 1 }); // 123456.8
 toNumber(value, 1); // 123456.8 (alias for { digits: 1 })
 ```
 
+### `toString(value, optionsOrDigits)`
+
+Converts the `Dnum` data structure into a `string`, without any formatting. [This might result in a loss of precision](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number#number_encoding) depending on how large the number is.
+
+| Name                       | Description                                                                                                                                                                                               | Type                                         |
+| -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------- |
+| `value`                    | The number to convert into a `string`                                                                                                                                                                     | `Dnum`                                       |
+| `options.digits`           | Number of digits to keep after the decimal point. Setting `options` to a number acts as an alias for this option (see example below). Defaults to the number of decimals in the `Dnum` passed to `value`. | `string`                                     |
+| `options.decimalsRounding` | Method used to round to `digits` decimals (defaults to `"ROUND_HALF"`).                                                                                                                                   | `"ROUND_HALF" \| "ROUND_UP" \| "ROUND_DOWN"` |
+| returns                    | Result value                                                                                                                                                                                              | `string`                                     |
+
+```ts
+let value = [123456789000000000000000n, 18];
+
+toString(value); // "123456.789"
+toString(value, { digits: 1 }); // "123456.8"
+toString(value, 1); // "123456.8" (alias for { digits: 1 })
+```
+
+Note that if you want to format the number for display purposes, you should probably use `format()` instead. If you need to convert the number into a JSON-compatible string without any precision loss, use `toJSON()` instead.
+
 ### `toJSON(value)`
 
 Converts the `Dnum` data structure into a JSON-compatible string. This function is provided because `JSON.stringify()` doesn’t work with `BigInt` data types.

diff --git a/src/api.ts b/src/api.ts
@@ -10,6 +10,7 @@ import {
   toJSON,
   toNumber,
   toParts,
+  toString,
 } from "./dnum";
 import { format } from "./formatting";
 import {
@@ -61,4 +62,5 @@ export {
   toJSON,
   toNumber,
   toParts,
+  toString,
 };
diff --git a/src/dnum.ts b/src/dnum.ts
@@ -213,11 +213,16 @@ export function toParts(
 export function toNumber(
   value: Dnum,
   optionsOrDigits: Parameters<typeof toParts>[1],
+) {
+  return Number(toString(value, optionsOrDigits));
+}
+
+export function toString(
+  value: Dnum,
+  optionsOrDigits: Parameters<typeof toParts>[1],
 ) {
   const [whole, fraction] = toParts(value, optionsOrDigits);
-  return Number(
-    (value[0] >= 0n ? "" : "-")
-      + whole
-      + (fraction ? `.${fraction}` : ""),
-  );
+  return (value[0] >= 0n ? "" : "-")
+    + whole
+    + (fraction ? `.${fraction}` : "");
 }
diff --git a/test/all.test.ts b/test/all.test.ts
@@ -22,6 +22,7 @@ import {
   toJSON,
   toNumber,
   toParts,
+  toString,
 } from "../src";
 import { setValueDecimals } from "../src/dnum";
 import { formatSign } from "../src/formatting";
@@ -674,6 +675,30 @@ describe("toNumber()", () => {
   });
 });
 
+describe("toString()", () => {
+  it("works", () => {
+    expect(toString([123456n, 2], 2)).toBe("1234.56");
+    expect(toString([123456n, 2], 1)).toBe("1234.6");
+    expect(toString([123456n, 0], 0)).toBe("123456");
+    expect(toString([123400n, 2], 2)).toBe("1234");
+    expect(toString([-123400n, 2], 2)).toBe("-1234");
+  });
+  it("works with greater digits than decimals", () => {
+    expect(toString([123400n, 2], 3)).toBe("1234");
+  });
+  it("works with negative values and smaller digits than decimals", () => {
+    expect(toString([-123400n, 4], 2)).toBe("-12.34");
+  });
+  it("works with very large numbers", () => {
+    expect(toString(
+      [-123400932870192873098321798321798731298713298n, 4],
+      2,
+    )).toBe(
+      "-12340093287019287309832179832179873129871.33",
+    );
+  });
+});
+
 describe("from()", () => {
   it("works with strings", () => {
     expect(from("12345.29387", 18)).toEqual([12345293870000000000000n, 18]);