From 9502eeef95047629678c66af75917a5e076b2224 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Ti=E1=BA=BFn=20Nguy=E1=BB=85n=20Kh=E1=BA=AFc?=
 <tien.nguyenkhac@icloud.com>
Date: Fri, 14 Jun 2024 21:56:16 +1200
Subject: [PATCH] docs: add example usage for `DenominatedNumber`

---
 .../docs/getting-started/number-utility.md    | 48 +++++++++++++++++++
 1 file changed, 48 insertions(+)
 create mode 100644 apps/docs/docs/getting-started/number-utility.md

diff --git a/apps/docs/docs/getting-started/number-utility.md b/apps/docs/docs/getting-started/number-utility.md
new file mode 100644
index 00000000..cb227a35
--- /dev/null
+++ b/apps/docs/docs/getting-started/number-utility.md
@@ -0,0 +1,48 @@
+---
+sidebar_position: 5
+---
+
+# Number utility
+
+To handle complexity around [planck unit](https://wiki.polkadot.network/docs/learn-DOT#the-planck-unit) used in Polkadot, a utility class [`DenominatedNumber`](/api/utils/class/DenominatedNumber) is provided by [`@reactive-dot/utils`](https://reactivedot.dev/api/utils).
+
+```ts
+import { DenominatedNumber } from "@reactive-dot/utils";
+
+// Denominated numbers are created with a planck value and a decimal places number
+
+const numberFromPlanck = new DenominatedNumber(10_000_000_000n, 10);
+
+console.log(numberFromPlanck.valueOf()); // 10
+
+// Denominated number can also be created from number instead of planck
+
+const numberFromNumber = DenominatedNumber.fromNumber(10, 10);
+
+console.log(numberFromNumber.planck); // 10000000000n
+
+// A string denomination can optionally be added for locale string conversion capability
+
+const numberWithDenomination = DenominatedNumber.fromNumber(10, 10, "DOT");
+
+console.log(numberWithDenomination.toLocaleString("en-NZ")); // DOT 10.00
+
+console.log(numberWithDenomination.toLocaleString("de-DE")); // 10,00 DOT
+
+// Arithmetics
+
+let dotAmount = DenominatedNumber.fromNumber(10, 10, "DOT");
+
+// Arithmetic operations can be performed using the number's planck value
+
+dotAmount = dotAmount.mapFromPlanck((planck) => planck + 5_000_000_000n);
+
+console.log(dotAmount.toLocaleString()); // DOT 10.50
+
+// Arithmetic operations can also be carried out with the number value
+// instead of planck if possible lost of precision is acceptable
+
+dotAmount = dotAmount.mapFromNumber((number) => (number * 2) / 4);
+
+console.log(dotAmount.toLocaleString()); // DOT 5.25
+```