chores: add examples to doc_test.go

.github/workflows/ci.yaml

@@ -0,0 +1,67 @@
+name: CI
+
+on:
+  pull_request:
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out code into the Go module directory
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup Go
+        uses: actions/setup-go@v5
+        with:
+          go-version-file: go.mod
+
+      - name: Run lint check
+        uses: reviewdog/action-golangci-lint@v2
+        with:
+          reporter: github-pr-review
+          go_version_file: go.mod
+
+  test:
+    strategy:
+      matrix:
+        go-version: [oldstable, stable]
+        os: [ubuntu-latest, windows-latest, macos-latest]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - name: Check out code into the Go module directory
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup Go
+        uses: actions/setup-go@v5
+        with:
+          go-version-file: go.mod
+
+      - name: Run tests
+        run: go test -tags='!fuzz' -v -race -failfast -coverprofile="coverage.txt" -covermode=atomic ./...
+
+      - name: Codecov
+        if: matrix.os == 'ubuntu-latest' && matrix.go-version == 'stable'
+        uses: codecov/codecov-action@v4
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+
+  fuzz:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out code into the Go module directory
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup Go
+        uses: actions/setup-go@v5
+        with:
+          go-version-file: go.mod
+
+      - name: Run fuzz tests
+        shell: bash
+        run: make fuzz-all

.github/workflows/codecov.yaml

@@ -0,0 +1,28 @@
+name: CodeCov
+
+on:
+  push:
+    branches:
+      - master
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out code into the Go module directory
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup Go
+        uses: actions/setup-go@v5
+        with:
+          go-version-file: go.mod
+
+      - name: Run tests
+        run: go test -tags='!fuzz' -v -race -failfast -coverprofile="coverage.txt" -covermode=atomic ./...
+
+      - name: Codecov
+        uses: codecov/codecov-action@v4
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}

Makefile

@@ -5,18 +5,19 @@ lint:
 
 test:
 	# run all unit-tests, ignore fuzz tests
-	@go test -tags='!fuzz' -v -race -failfast -coverprofile=coverage.out -covermode=atomic ./...
+	@go test -tags='!fuzz' -v -race -failfast -coverprofile=coverage.txt -covermode=atomic ./...
 	@go tool cover -html=coverage.out
 
 fuzz:
 	$(eval fuzzName := $(filter-out $@,$(MAKECMDGOALS)))
 	@go test -tags='fuzz' -v -run=Fuzz -fuzz=$(fuzzName) -fuzztime=30s -timeout=10m
 
 fuzz-all:
-	echo "Run all fuzz tests"
-	for fuzz_test in $(shell go test -list "^Fuzz" $$fuzz_pkg | grep "^Fuzz"); do \
+	@echo "Run all fuzz tests"
+	$(eval fuzz_pkg := $(shell go test -list "^Fuzz" $$fuzz_pkg | grep "^Fuzz"))
+	for fuzz_test in $(fuzz_pkg); do \
 		echo "Fuzzing $$fuzz_test in $$fuzz_pkg ..."; \
-		go test -tags='fuzz' -run=Fuzz -fuzz=$$fuzz_test -fuzztime=120s $$fuzz_pkg -timeout=10m || exit 1; \
+		go test -tags='fuzz' -run=Fuzz -fuzz=$$fuzz_test -fuzztime=30s $$fuzz_pkg -timeout=10m || exit 1; \
 	done \
 
 bench:

README.md

@@ -14,16 +14,17 @@ go get github.com/quagmt/udecimal
 ## Features
 
 - **High Precision**: Supports up to 19 decimal places with no precision loss during arithmetic operations.
-- **Optimized for Speed**: Designed for high performance with zero memory allocation in most cases (see [benchmarks](#benchmarks) and [How it works](#how-it-works)).
+- **Optimized for Speed**: Designed for high performance with zero memory allocation in most cases (see [Benchmarks](benchmarks/BENCHMARKS.md) and [How it works](#how-it-works)).
 - **Panic-Free**: All errors are returned as values, ensuring no unexpected panics.
+- **Immutable**: All arithmetic operations return a new `Decimal` value, preserving the original value and safe for concurrent use.
 - **Versatile Rounding Methods**: Includes HALF AWAY FROM ZERO, HALF TOWARD ZERO, and Banker's rounding.
   <br/>
 
 **NOTE**: This library does not perform implicit rounding. If the result of an operation exceeds the maximum precision, extra digits are truncated. All rounding methods must be explicitly invoked. (see [Rounding Methods](#rounding-methods) for more details)
 
 ## Documentation
 
-- Checkout [documentation](#docs) and [FAQ](FAQ.md) for more information.
+- Checkout [documentation](#docs) for more information.
 
 ## Usage
 
@@ -70,9 +71,9 @@ func main() {
 
 ## Rounding Methods
 
-Rounding can be challenging and often confusing, as there are [numerous ways](https://www.mathsisfun.com/numbers/rounding-methods.html) to round a number. Each method has specific use cases, and developers frequently make mistakes or incorrect assumptions about rounding. For instance, round(1.5) might result in either 1 or 2, depending on the chosen rounding method.
+Rounding numbers can often be challenging and confusing due to the [variety of methods](https://www.mathsisfun.com/numbers/rounding-methods.html) available. Each method serves specific purposes, and it's common for developers to make mistakes or incorrect assumptions about how rounding should be performed. For example, the result of `round(1.45)` could be either 1.4 or 1.5, depending on the rounding method used.
 
-This issue is particularly critical in financial applications, where even minor rounding mistakes can be accumulated and result in significant financial losses. To prevent such mistakes, this library avoids implicit rounding and requires developers to explicitly invoke the rounding method. The supported rounding methods are:
+This issue is particularly critical in financial applications, where even minor rounding errors can accumulate and lead to significant financial losses. To mitigate such errors, this library intentionally avoids implicit rounding. If the result of an operation exceeds the maximum precision specified by developers beforehand, **extra digits are truncated**. Developers need to explicitly choose the rounding method they want to use. The supported rounding methods are:
 
 - [Banker's rounding](https://en.wikipedia.org/wiki/Rounding#Rounding_half_to_even) or round half to even
 - [Half away from zero](https://en.wikipedia.org/wiki/Rounding#Rounding_half_away_from_zero) (HAZ)
@@ -104,22 +105,22 @@ func main() {
 
 As mentioned above, this library is not always memory allocation free. To understand why, let's take a look at how the `Decimal` type is implemented.
 
-The `Decimal` type represents a fixed-point decimal number. It consists of three components: sign, coefficient, and scale. The number is represented as:
+The `Decimal` type represents a fixed-point decimal number. It consists of three components: sign, coefficient, and prec. The number is represented as:
 
 ```go
-// decimal value = (neg == true ? -1 : 1) * coef * 10^(-scale)
+// decimal value = (neg == true ? -1 : 1) * coef * 10^(-prec)
 type Decimal struct {
 	neg bool
 	coef bint
-	scale uint8 // 0 <= scale <= 19
+	prec uint8 // 0 <= prec <= 19
 }
 
 // Example:
 // 123.456 = 123456 * 10^-3
-// -> neg = false, coef = 123456, scale = 3
+// -> neg = false, coef = 123456, prec = 3
 
 // -123.456 = -123456 / 10^-3
-// -> neg = true, coef = 123456, scale = 3
+// -> neg = true, coef = 123456, prec = 3
 ```
 
 <br/>