forfudan · forfudan · Aug 6, 2025 · Aug 6, 2025 · Aug 6, 2025 · Aug 6, 2025
diff --git a/README.md b/README.md
@@ -37,17 +37,19 @@ This repository includes [TOMLMojo](https://github.com/forfudan/decimojo/tree/ma
 
 DeciMojo is available in the [modular-community](https://repo.prefix.dev/modular-community) package repository. You can install it using any of these methods:
 
-From the `pixi` CLI, simply run ```pixi add decimojo```. This fetches the latest version and makes it immediately available for import.
+1. From the `pixi` CLI, run the command ```pixi add decimojo```. This fetches the latest version and makes it immediately available for import.
 
-For projects with a `mojoproject.toml`file, add the dependency:
+1. In the `mojoproject.toml` file of your project, add the following dependency:
 
-```toml
-decimojo = "==0.5.0"
-```
+    ```toml
+    decimojo = "==0.5.0"
+    ```
+
+    Then run `pixi install` to download and install the package.
 
-Then run `pixi install` to download and install the package.
+1. For the latest development version in the `main` branch, clone [this GitHub repository](https://github.com/forfudan/decimojo) and build the package locally using the command `pixi run package`.
 
-For the latest development version, clone the [GitHub repository](https://github.com/forfudan/decimojo) and build the package locally.
+The following table summarizes the package versions and their corresponding Mojo versions:
 
 | `decimojo` | `mojo`        | package manager |
 | ---------- | ------------- | --------------- |
@@ -56,7 +58,7 @@ For the latest development version, clone the [GitHub repository](https://github
 | v0.3.0     | ==25.2        | magic           |
 | v0.3.1     | >=25.2, <25.4 | pixi            |
 | v0.4.x     | ==25.4        | pixi            |
-| v0.5.0     | ==25.4        | pixi            |
+| v0.5.0     | ==25.5        | pixi            |
 
 ## Quick start
 
@@ -77,7 +79,7 @@ This will import the following types or aliases into your namespace:
 
 ---
 
-Here are some examples showcasing the arbitrary-precision feature of the `BigDecimal` type (`BDec`). For some mathematical operations, the default precision (number of significant digits) is set to `36`. You can change the precision by passing the `precision` argument to the function. This default precision will be configurable globally in future when Mojo supports global variables.
+Here are some examples showcasing the arbitrary-precision feature of the `BigDecimal` type (aliases: `BDec` and `Decimal`). For some mathematical operations, the default precision (number of significant digits) is set to `36`. You can change the precision by passing the `precision` argument to the function. This default precision will be configurable globally in future when Mojo supports global variables.
 
 ```mojo
 from decimojo.prelude import *
@@ -186,7 +188,7 @@ fn main() raises:
     print(a.is_zero())                             # Check for zero: False
 
     # === Type Conversions ===
-    print(a.to_str())                              # To string: "12345678901234567890"
+    print(String(a))                               # To string: "12345678901234567890"
 
     # === Sign Handling ===
     print(-a)                                      # Negation: -12345678901234567890

diff --git a/docs/changelog.md b/docs/changelog.md
@@ -2,9 +2,9 @@
 
 This is a list of RELEASED changes for the DeciMojo Package.
 
-## 20250801 (v0.5.0)
+## 20250806 (v0.5.0)
 
-DeciMojo v0.5.0 introduces significant enhancements to the `BigDecimal` and `BigUInt` types, including new mathematical functions and performance optimizations. The release adds **trigonometric functions** for `BigDecimal`, implements the **Chudnovsky algorithm** for computing π, implements the **Karatsuba multiplication algorithm** and **Burnikel-Ziegler fast division algorithm** for `BigUInt`. In-place subtraction is now supported for `BigUInt`, and SIMD is utilized for arithmetic operations. The `Decimal` type is renamed to `Decimal128` to reflect its 128-bit fixed precision. The release also includes improved error handling, optimized type conversions, and comprehensive documentation updates.
+DeciMojo v0.5.0 introduces significant enhancements to the `BigDecimal` and `BigUInt` types, including new mathematical functions and performance optimizations. The release adds **trigonometric functions** for `BigDecimal`, implements the **Chudnovsky algorithm** for computing π, and implements the **Karatsuba multiplication algorithm** and **Burnikel-Ziegler division algorithm** for `BigUInt`. In-place operations, slice operations, and SIMD operations are now supported for `BigUInt` arithmetic. The `Decimal` type is renamed to `Decimal128` to reflect its 128-bit fixed precision. The release also includes improved error handling, optimized type conversions, refactored testing suites, and documentation updates.
 
 DeciMojo v0.5.0 is compatible with Mojo v25.5.
 

diff --git a/docs/examples_on_bdec.mojo → docs/examples_on_bigdecimal.mojo b/docs/examples_on_bdec.mojo → docs/examples_on_bigdecimal.mojo
diff --git a/docs/examples_on_bigint.mojo b/docs/examples_on_bigint.mojo
@@ -0,0 +1,40 @@
+from decimojo.prelude import *
+
+
+fn main() raises:
+    # === Construction ===
+    var a = BigInt("12345678901234567890")  # From string
+    var b = BInt(12345)  # From integer
+
+    # === Basic Arithmetic ===
+    print(a + b)  # Addition: 12345678901234580235
+    print(a - b)  # Subtraction: 12345678901234555545
+    print(a * b)  # Multiplication: 152415787814108380241050
+
+    # === Division Operations ===
+    print(a // b)  # Floor division: 999650944609516
+    print(a.truncate_divide(b))  # Truncate division: 999650944609516
+    print(a % b)  # Modulo: 9615
+
+    # === Power Operation ===
+    print(BInt(2).power(10))  # Power: 1024
+    print(BInt(2) ** 10)  # Power (using ** operator): 1024
+
+    # === Comparison ===
+    print(a > b)  # Greater than: True
+    print(a == BInt("12345678901234567890"))  # Equality: True
+    print(a.is_zero())  # Check for zero: False
+
+    # === Type Conversions ===
+    print(String(a))  # To string: "12345678901234567890"
+
+    # === Sign Handling ===
+    print(-a)  # Negation: -12345678901234567890
+    print(
+        abs(BInt("-12345678901234567890"))
+    )  # Absolute value: 12345678901234567890
+    print(a.is_negative())  # Check if negative: False
+
+    # === Extremely large numbers ===
+    # 3600 digits // 1800 digits
+    print(BInt("123456789" * 400) // BInt("987654321" * 200))
diff --git a/docs/examples_on_decimal128.mojo b/docs/examples_on_decimal128.mojo
@@ -0,0 +1,61 @@
+from decimojo.prelude import *
+
+
+fn main() raises:
+    # === Construction ===
+    var a = Dec128("123.45")  # From string
+    var b = Dec128(123)  # From integer
+    var c = Dec128(123, 2)  # Integer with scale (1.23)
+    var d = Dec128.from_float(3.14159)  # From floating-point
+
+    # === Basic Arithmetic ===
+    print(a + b)  # Addition: 246.45
+    print(a - b)  # Subtraction: 0.45
+    print(a * b)  # Multiplication: 15184.35
+    print(a / b)  # Division: 1.0036585365853658536585365854
+
+    # === Rounding & Precision ===
+    print(a.round(1))  # Round to 1 decimal place: 123.5
+    print(a.quantize(Dec128("0.01")))  # Format to 2 decimal places: 123.45
+    print(a.round(0, RoundingMode.ROUND_DOWN))  # Round down to integer: 123
+
+    # === Comparison ===
+    print(a > b)  # Greater than: True
+    print(a == Dec128("123.45"))  # Equality: True
+    print(a.is_zero())  # Check for zero: False
+    print(Dec128("0").is_zero())  # Check for zero: True
+
+    # === Type Conversions ===
+    print(Float64(a))  # To float: 123.45
+    print(a.to_int())  # To integer: 123
+    print(a.to_str())  # To string: "123.45"
+    print(a.coefficient())  # Get coefficient: 12345
+    print(a.scale())  # Get scale: 2
+
+    # === Mathematical Functions ===
+    print(Dec128("2").sqrt())  # Square root: 1.4142135623730950488016887242
+    print(Dec128("100").root(3))  # Cube root: 4.641588833612778892410076351
+    print(Dec128("2.71828").ln())  # Natural log: 0.9999993273472820031578910056
+    print(Dec128("10").log10())  # Base-10 log: 1
+    print(
+        Dec128("16").log(Dec128("2"))
+    )  # Log base 2: 3.9999999999999999999999999999
+    print(Dec128("10").exp())  # e^10: 22026.465794806716516957900645
+    print(Dec128("2").power(10))  # Power: 1024
+
+    # === Sign Handling ===
+    print(-a)  # Negation: -123.45
+    print(abs(Dec128("-123.45")))  # Absolute value: 123.45
+    print(Dec128("123.45").is_negative())  # Check if negative: False
+
+    # === Special Values ===
+    print(Dec128.PI())  # π constant: 3.1415926535897932384626433833
+    print(Dec128.E())  # e constant: 2.7182818284590452353602874714
+    print(Dec128.ONE())  # Value 1: 1
+    print(Dec128.ZERO())  # Value 0: 0
+    print(Dec128.MAX())  # Maximum value: 79228162514264337593543950335
+
+    # === Convenience Methods ===
+    print(Dec128("123.400").is_integer())  # Check if integer: False
+    print(a.number_of_significant_digits())  # Count significant digits: 5
+    print(Dec128("12.34").to_str_scientific())  # Scientific notation: 1.234E+1