docs: add benchmarks to README and python generator script

3 files changed, 52 insertions, 0 deletions

diff --git a/.gitignore b/.gitignore
index eb2b1c5..261d30b 100644
--- a/.gitignore
+++ b/.gitignore
@@ -22,3 +22,7 @@ configure~
 examples/bench
 examples/parser
 tests/test
+
+examples/large.csv
+examples/wide.csv
+examples/quoted.csv
diff --git a/README.md b/README.md
index 4f2789a..ff8f15a 100644
--- a/README.md
+++ b/README.md
@@ -67,3 +67,21 @@ int main() {
 ```
 
 See the `examples/` directory for more advanced use cases.
+
+## Benchmarks
+
+The library is highly optimized for throughput, avoiding internal buffering and memory allocations while parsing. We include a benchmarking tool (`examples/bench`) and several test datasets to measure parsing performance.
+
+Recent benchmark results (run locally on an Apple Silicon machine):
+
+| Dataset | File Size | Description | Throughput |
+|---------|-----------|-------------|------------|
+| `iris.csv` | 4 KB | Small, standard dataset | ~440 MB/s |
+| `large.csv` | 7.6 MB | 100,000 rows, 10 columns (simple text/numbers) | ~1.3 GB/s |
+| `wide.csv` | 6.6 MB | 1,000 rows, 1,000 columns | ~1.3 GB/s |
+| `quoted.csv` | 23.8 MB | 100,000 rows, 10 columns with quoted strings & newlines | ~1.4 GB/s |
+
+You can run these benchmarks yourself using:
+```bash
+$ ./examples/bench examples/large.csv 100
+```
diff --git a/examples/generate_benchmarks.py b/examples/generate_benchmarks.py
new file mode 100755
index 0000000..14b531c
--- /dev/null
+++ b/examples/generate_benchmarks.py
@@ -0,0 +1,30 @@
+#!/usr/bin/env python3
+import csv
+import random
+
+def generate_large():
+    print("Generating large.csv (100,000 rows, 10 columns)...")
+    with open("large.csv", "w", newline="") as f:
+        writer = csv.writer(f)
+        for _ in range(100000):
+            writer.writerow(["cell" + str(random.randint(0, 1000)) for _ in range(10)])
+
+def generate_wide():
+    print("Generating wide.csv (1,000 rows, 1,000 columns)...")
+    with open("wide.csv", "w", newline="") as f:
+        writer = csv.writer(f)
+        for _ in range(1000):
+            writer.writerow(["cell" + str(random.randint(0, 100)) for _ in range(1000)])
+
+def generate_quoted():
+    print("Generating quoted.csv (100,000 rows, 10 columns with quotes and newlines)...")
+    with open("quoted.csv", "w", newline="") as f:
+        writer = csv.writer(f)
+        for _ in range(100000):
+            writer.writerow(["\"quoted, string\n" + str(random.randint(0, 1000)) + "\"" for _ in range(10)])
+
+if __name__ == "__main__":
+    generate_large()
+    generate_wide()
+    generate_quoted()
+    print("Done!")