[release][docs] Update documents for the release of version 0.5.0 (#118)

This pull request updates documentation and examples to reflect the new
v0.5.0 release of DeciMojo, improves clarity for both English and
Chinese readers, and adds comprehensive usage examples for all major
types. The changes ensure consistency with the latest features, update
installation and compatibility instructions, and provide quick start
guides for `BigInt` and `Decimal128`.

**Documentation and Usage Examples:**
- Added detailed example files: `docs/examples_on_bigint.mojo` and
`docs/examples_on_decimal128.mojo` to demonstrate the construction,
arithmetic, conversions, and advanced features of `BigInt` and
`Decimal128`.
- Expanded and clarified the Chinese README (`docs/readme_zht.md`) with
a full table of contents, improved type descriptions, installation
instructions, and comprehensive quick start guides for `BigInt`,
`BigDecimal`, and `Decimal128`.
- Updated the English `README.md` to clarify installation steps, version
compatibility, and usage of type aliases, and to improve example
explanations.

**Release and Versioning Updates:**
- Updated the changelog (`docs/changelog.md`) to reflect the new release
date and summarize the new features and improvements in v0.5.0,
including enhanced math functions, performance optimizations, and
compatibility with Mojo v25.5.
- Updated package version requirements in `pixi.toml` and documentation
tables to require Mojo v25.5 for DeciMojo v0.5.0, ensuring users install
compatible versions.

**Citation and Metadata:**
- Updated citation and software metadata in the Chinese README to match
the new version and scope of the library.

**Other Improvements:**
- Improved and clarified footnotes and technical explanations in the
Chinese README, including details about internal representations and
division semantics.

These changes ensure that documentation, examples, and metadata are
up-to-date and provide clear guidance for both English and Chinese
users.

Author: forfudan

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

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.
 

docs/examples_on_bdec.mojo docs/examples_on_bigdecimal.mojodocs/examples_on_bdec.mojo renamed to docs/examples_on_bigdecimal.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))

docs/examples_on_bigint.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