From 7e67c3fcf9d12e33397d6d4ee737abc0a2eba84f Mon Sep 17 00:00:00 2001
From: Dominik Krenn <dominik.krenn@1tool.com>
Date: Wed, 5 Nov 2025 08:05:21 +0100
Subject: [PATCH] added readme for module

---
 mathstream/README.md | 67 ++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 67 insertions(+)
 create mode 100644 mathstream/README.md

diff --git a/mathstream/README.md b/mathstream/README.md
new file mode 100644
index 0000000..46471bc
--- /dev/null
+++ b/mathstream/README.md
@@ -0,0 +1,67 @@
+# Mathstream Library
+
+`mathstream` offers streamed, string-based arithmetic for very large integers that you may not want to load entirely into memory. Instead of parsing numbers into Python `int` values, you work with digit files on disk via `StreamNumber` and call math operations that operate chunk-by-chunk.
+
+## Quick Start
+
+```bash
+python -m venv venv
+source venv/bin/activate
+pip install -e .
+```
+
+Create digit files anywhere you like (the examples below use `instance/log`), then construct `StreamNumber` objects, and call the helpers:
+
+```python
+from mathstream import StreamNumber, add, sub, mul, div, pow
+
+a = StreamNumber("instance/log/huge.txt")
+b = StreamNumber("instance/log/tiny.txt")
+e = StreamNumber("instance/log/exponent.txt")
+
+print("sum =", "".join(add(a, b).stream()))
+print("difference =", "".join(sub(a, b).stream()))
+print("product =", "".join(mul(a, b).stream()))
+print("quotient =", "".join(div(a, b).stream()))
+print("power =", "".join(pow(a, e).stream()))
+```
+
+Each arithmetic call writes its result back into `instance/log` (configurable via `mathstream.number.LOG_DIR`) so you can stream the digits later or reuse them in further operations.
+
+## Core Concepts
+
+- **StreamNumber(path)** – Wraps a digit text file. The file may include an optional leading sign (`+` or `-`). Whitespace is ignored; digits must otherwise be contiguous.
+- **`.stream(chunk_size)`** – Yields strings of digits with the provided chunk size. Operations in `mathstream.engine` consume these streams to avoid loading the entire number at once.
+- **Automatic staging** – Outputs are stored under `LOG_DIR` with hashes based on input file paths, letting you compose operations without manual bookkeeping.
+- **Sign-aware** – Addition, subtraction, multiplication, division (`//` behavior), and exponentiation (non-negative exponents) all respect operand sign. Division follows Python’s floor division rules.
+- **Utilities** – `clear_logs()` wipes prior staged results so you can start fresh.
+
+## Example Script
+
+`test.py` in the repository root demonstrates a minimal workflow:
+
+1. Writes sample operands to `tests/*.txt`.
+2. Calls every arithmetic primitive.
+3. Asserts that the streamed outputs match known values (helpful for quick regression checks).
+
+Run it via:
+
+```bash
+python test.py
+```
+
+## Extending
+
+- To hook into other storage backends, implement your own `StreamNumber` variant with the same `.stream()` interface.
+- Need modulo or gcd? Compose the existing primitives (e.g., repeated subtraction or using `div` + remainder tracking inside `_divide_abs`) or add new helpers following the same streamed pattern.
+- For more control over output locations, override `LOG_DIR` before using the operations:
+
+```python
+from mathstream import engine
+from pathlib import Path
+
+engine.LOG_DIR = Path("/tmp/my_mathstage")
+engine.clear_logs()
+```
+
+With these building blocks, you can manipulate arbitrarily large integers while keeping memory usage constant. Happy streaming!