commit 846977fe0f79967836bcea078f38c0c0df5a240b
parent a3c302580445ffc3ec00a6fbd0cc0b3e2a2a6b13
Author: Amit Dutta <amitdutta4255@gmail.com>
Date: Sun, 17 Aug 2025 19:50:56 +0530
Update README.md
Diffstat:
| M | README.md | | | 226 | +++++++++++++++++++++++++++++++++++++++++++++++-------------------------------- |
1 file changed, 134 insertions(+), 92 deletions(-)
diff --git a/README.md b/README.md
@@ -1,6 +1,12 @@
# Advanced Math Utilities
-A comprehensive Python package for various mathematical and financial calculations. This package includes modules for compound interest, number theory (prime checking, factorial, permutation, combination), string manipulation, matrix operations, and basic statistics (mean, median, mode).
+A comprehensive Python package for various mathematical and financial calculations. This package includes modules for:
+- **Finance**: Compound interest
+- **Number Theory**: Prime checking, factorial, permutation, combination
+- **String Manipulation**: String reversal
+- **Matrix Operations**: Addition, multiplication, transpose, determinant
+- **Statistics**: Mean, median, mode
+- **Geometry**: Area of triangle
[](https://pypi.org/project/adpkg/)
[](https://pypi.org/project/adpkg/)
@@ -10,8 +16,7 @@ A comprehensive Python package for various mathematical and financial calculatio
## 📦 Installation
-Install directly from PyPI:
-
+Install from PyPI:
```bash
pip install adpkg
```
@@ -25,36 +30,36 @@ python -m pip show adpkg
## 🚀 Usage
-Here are detailed module descriptions, parameters, return values, and examples.
+Here is the **detailed documentation** for each module and function, with examples, expected results, and edge cases.
---
### 💰 Finance Module (`finance.py`)
-**`interest(prime_amount, time_duration_str, number_of_times_interest_will_compound_per_year, rate_of_interest)`**
-
-Calculates the compound interest.
-
-**Parameters:**
-- `prime_amount` (float or int): Initial principal amount (P).
-- `time_duration_str` (str): Duration of investment, must be in short-hand formats:
- - `XyYm` (e.g., `5y6m`, `1y8m`)
- - `Xm` (e.g., `15m`, `6m`)
- - `Xy` (e.g., `5y`, `1y`)
-- `number_of_times_interest_will_compound_per_year` (int): Compounding frequency (2=half-yearly, 4=quarterly, 12=monthly, 365=daily).
-- `rate_of_interest` (float): Annual nominal rate in percentage.
+#### Function: `interest(prime_amount, time_duration_str, number_of_times_interest_will_compound_per_year, rate_of_interest)`
-**Returns:**
-- `float`: Compound interest amount (3 decimals).
-- `None`: If invalid.
+Calculates compound interest.
-**Example:**
+**Examples:**
```python
from adpkg import finance
-# $1000 at 5% compounded monthly for 1 year
-i = finance.interest(1000, "1y", 12, 5)
-print(f"Compound interest: ${i}")
+# 1 year, monthly compounding
+i1 = finance.interest(1000, "1y", 12, 5)
+print(i1) # 51.161
+
+# 5 years, quarterly compounding
+i2 = finance.interest(2000, "5y", 4, 7)
+print(i2) # 816.622
+
+# 2 years 6 months, daily compounding
+i3 = finance.interest(500, "2y6m", 365, 4.5)
+print(i3) # 61.446
+
+# Edge cases
+print(finance.interest(-1000, "1y", 12, 5)) # None (negative principal)
+print(finance.interest(1000, "abc", 12, 5)) # None (invalid time format)
+print(finance.interest(1000, "1y", 0, 5)) # None (zero compounding)
```
---
@@ -63,124 +68,163 @@ print(f"Compound interest: ${i}")
#### Number Theory
-**`check_prime(inp)`**
-- Input: integer
-- Returns: `1` (prime), `0` (not prime), `None` (invalid)
-
+##### `check_prime(inp)`
```python
from adpkg import adcustom
-print(adcustom.check_prime(17)) # 1
-print(adcustom.check_prime(10)) # 0
+print(adcustom.check_prime(17)) # 1
+print(adcustom.check_prime(10)) # 0
+print(adcustom.check_prime(-5)) # None
+print(adcustom.check_prime("a")) # None
```
-**`factorial(inp)`**
-- Input: integer ≥ 0
-- Returns: factorial
-
+##### `factorial(inp)`
```python
-print(adcustom.factorial(5)) # 120
+print(adcustom.factorial(5)) # 120
+print(adcustom.factorial(0)) # 1
+print(adcustom.factorial(-2)) # None
+print(adcustom.factorial("x"))# None
```
-**`permutation(total_item, chosen_item)`**
-- Input: n, k
-- Returns: P(n, k)
-
+##### `permutation(total_item, chosen_item)`
```python
-print(adcustom.permutation(5, 2)) # 20
+print(adcustom.permutation(5, 2)) # 20
+print(adcustom.permutation(6, 3)) # 120
+print(adcustom.permutation(4, -1)) # None
+print(adcustom.permutation("a", 2))# None
```
-**`combination(total_item, chosen_item)`**
-- Input: n, k
-- Returns: C(n, k)
-
+##### `combination(total_item, chosen_item)`
```python
-print(adcustom.combination(5, 2)) # 10
+print(adcustom.combination(5, 2)) # 10
+print(adcustom.combination(6, 3)) # 20
+print(adcustom.combination(4, -1)) # None
+print(adcustom.combination("a", 3)) # None
```
---
#### String Manipulation
-**`string_reverse(string)`**
-- Input: string
-- Returns: reversed string
-
+##### `string_reverse(string)`
```python
-print(adcustom.string_reverse("hello")) # 'olleh'
+print(adcustom.string_reverse("hello")) # 'olleh'
+print(adcustom.string_reverse("adpkg")) # 'gkpda'
+print(adcustom.string_reverse("")) # ''
+print(adcustom.string_reverse(123)) # None (invalid input)
```
---
#### Matrix Operations
-**`matrix_addition(matrix1, matrix2)`**
-- Adds two matrices
-- Returns: resulting matrix as string
+##### `matrix_addition(matrix1, matrix2)`
+```python
+mat1 = [[1, 2], [3, 4]]
+mat2 = [[5, 6], [7, 8]]
+print(adcustom.matrix_addition(mat1, mat2)) # [[6, 8], [10, 12]]
-**`matrix_multiplication(matrix1, matrix2)`**
-- Multiplies two matrices
-- Returns: product as string
+# Edge case: mismatched dimensions
+mat3 = [[1, 2, 3], [4, 5, 6]]
+print(adcustom.matrix_addition(mat1, mat3)) # None
+```
-**`matrix_transpose(matrix)`**
-- Transposes a matrix
-- Returns: result as string
+##### `matrix_multiplication(matrix1, matrix2)`
+```python
+print(adcustom.matrix_multiplication(mat1, mat2)) # [[19, 22], [43, 50]]
-**`determinant_value(matrix)`**
-- Calculates determinant (supports ≤3x3)
-- Returns: determinant value
+# Edge case: incompatible dimensions
+mat_bad = [[1, 2, 3]]
+print(adcustom.matrix_multiplication(mat1, mat_bad)) # None
+```
+##### `matrix_transpose(matrix)`
```python
-mat1 = [[1, 2], [3, 4]]
-mat2 = [[5, 6], [7, 8]]
+mat = [[1, 2, 3], [4, 5, 6]]
+print(adcustom.matrix_transpose(mat)) # [[1, 4], [2, 5], [3, 6]]
-print(adcustom.matrix_addition(mat1, mat2))
-print(adcustom.matrix_multiplication(mat1, mat2))
-print(adcustom.matrix_transpose(mat1))
-print(adcustom.determinant_value([[1, 2], [3, 4]]))
+# Edge case: empty matrix
+print(adcustom.matrix_transpose([])) # None
+```
+
+##### `determinant_value(matrix)`
+```python
+print(adcustom.determinant_value([[1, 2], [3, 4]])) # -2
+print(adcustom.determinant_value([[1, 2, 3], [0, 1, 4], [5, 6, 0]])) # 1
+
+# Edge case: >3x3 matrix
+big_mat = [[1, 2, 3, 4], [5, 6, 7, 8], [9, 10, 11, 12], [13, 14, 15, 16]]
+print(adcustom.determinant_value(big_mat)) # None
```
---
#### Statistics
-**`mean(inp_set)`**, **`median(inp_set)`**, **`mode(inp_set)`**
+##### `mean(inp_set)`
+```python
+data = [1, 2, 3, 4, 5]
+print(adcustom.mean(data)) # 3.0
+print(adcustom.mean([])) # None
+print(adcustom.mean("x")) # None
+```
+##### `median(inp_set)`
```python
-data = [1, 2, 2, 3, 4]
-print(adcustom.mean(data)) # 2.4
-print(adcustom.median(data)) # 2
-print(adcustom.mode(data)) # ([2], 2)
+data = [1, 3, 2, 5, 4]
+print(adcustom.median(data)) # 3
+
+data_even = [1, 2, 3, 4]
+print(adcustom.median(data_even)) # 2.5
+
+# Edge case: invalid input
+print(adcustom.median("abc")) # None
```
----
+##### `mode(inp_set)`
+```python
+data = [1, 2, 2, 3, 4, 4, 4, 5]
+print(adcustom.mode(data)) # ([4], 3)
-### 🔺 Triangle Module (`triangle.py`)
+single_mode = [10, 10, 20, 30]
+print(adcustom.mode(single_mode)) # ([10], 2)
-**`areaoftriangle(len_a, len_b, len_c, unit='')`**
+multi_mode = [1, 1, 2, 2, 3]
+print(adcustom.mode(multi_mode)) # ([1, 2], 2)
-Calculates the area using **Heron's Formula**.
+# Edge case: empty list
+print(adcustom.mode([])) # None
+```
+
+---
+### 🔺 Triangle Module (`triangle.py`)
+
+#### `areaoftriangle(len_a, len_b, len_c, unit='')`
```python
from adpkg import triangle
-print(triangle.areaoftriangle(3, 4, 5)) # 6.0
-print(triangle.areaoftriangle(3, 4, 5, "sq cm")) # '6.0 sq cm'
+print(triangle.areaoftriangle(3, 4, 5)) # 6.0
+print(triangle.areaoftriangle(3, 4, 5, "sq cm")) # '6.0 sq cm'
+print(triangle.areaoftriangle(7, 8, 9, "m^2")) # '26.833 m^2'
+
+# Edge cases
+print(triangle.areaoftriangle(1, 2, 3)) # None (degenerate triangle)
+print(triangle.areaoftriangle(-3, 4, 5)) # None (negative side)
+print(triangle.areaoftriangle("a", 4, 5)) # None (invalid input)
```
---
## 🧪 Running Tests
-The repo includes `test1.py`–`test5.py`, each focusing on specific modules.
+Tests available: `test1.py` – `test5.py`
-Run tests individually:
+Run one test:
```bash
python test1.py
-python test2.py
-python test3.py
```
-Run all with unittest:
+Run all:
```bash
python -m unittest discover -s . -p "test*.py"
```
@@ -189,19 +233,17 @@ python -m unittest discover -s . -p "test*.py"
## 🛠️ Contributing
-- Fork the repo
-- Create a branch
-- Add new utilities / bug fixes
-- Submit a pull request
-
-Please include **tests** for new features.
+- Fork repo
+- Create branch
+- Add feature + test
+- Submit PR
---
## 🗺️ Roadmap
-- ✅ Current: Number theory, finance, matrices, statistics, triangles
-- 🔜 Upcoming: Probability, calculus helpers, polynomial tools, advanced linear algebra
-- 📊 Long-term: Machine learning helpers, symbolic algebra, optimization functions
+- ✅ Implemented: Finance, number theory, strings, matrices, stats, triangles
+- 🔜 Coming: Probability, calculus, polynomials, advanced linear algebra
+- 📊 Future: Machine learning helpers, symbolic algebra, optimization
---
