docs: publish reproducible performance benchmarks

.github/workflows/test.yml

@@ -43,6 +43,11 @@ jobs:
           go -C docs test -race ./...
           go -C examples test ./...
 
+      - name: Verify generated README sections
+        run: |
+          go -C docs run ./readme
+          git diff --exit-code -- README.md docs/readme/benchmarks.txt
+
       - name: Require full library coverage
         run: test "$(go tool cover -func=coverage.txt | awk '/^total:/ {print $3}')" = "100.0%"
 

README.md

@@ -14,7 +14,7 @@
     <img src="https://img.shields.io/github/v/tag/goforj/str?label=version&sort=semver" alt="Latest tag">
     <a href="https://codecov.io/gh/goforj/str"><img src="https://codecov.io/github/goforj/str/graph/badge.svg?token=9KT46ZORP3" alt="Coverage"></a>
 <!-- test-count:embed:start -->
-    <img src="https://img.shields.io/badge/tests-264-brightgreen" alt="Tests">
+    <img src="https://img.shields.io/badge/tests-281-brightgreen" alt="Tests">
 <!-- test-count:embed:end -->
     <a href="https://goreportcard.com/report/github.com/goforj/str/v2"><img src="https://goreportcard.com/badge/github.com/goforj/str/v2" alt="Go Report Card"></a>
 </p>
@@ -129,6 +129,27 @@ filename := exportFilename("Q3 Sales & Returns — North America")
 
 `str` uses the standard library underneath and has no dependencies. Use whichever version makes the rules easiest to see.
 
+<!-- performance:embed:start -->
+
+## Performance
+
+These comparisons measure equivalent standard-library and `str` operations. Each cell reports the median of 10 samples as `ns/op · B/op · allocs/op`.
+
+Recorded with `go1.26.1` on `linux/arm64` using `-cpu=1` (`GOMAXPROCS=1`).
+
+| Workload | Standard library | `str` chain |
+| --- | ---: | ---: |
+| Trim | 3.2 ns/op · 0 B/op · 0 allocs/op | 3.2 ns/op · 0 B/op · 0 allocs/op |
+| ToLower | 61.2 ns/op · 32 B/op · 1 allocs/op | 63.0 ns/op · 32 B/op · 1 allocs/op |
+| NormalizeSpace (Fields + Join) | 191.6 ns/op · 208 B/op · 2 allocs/op | 185.2 ns/op · 80 B/op · 1 allocs/op |
+| Trim → ToLower | 71.8 ns/op · 32 B/op · 1 allocs/op | 69.3 ns/op · 32 B/op · 1 allocs/op |
+| ReplaceAll × 3 | 136.6 ns/op · 96 B/op · 3 allocs/op | 133.1 ns/op · 96 B/op · 3 allocs/op |
+
+Timing is machine-specific; use it to understand the scale of these operations, not as a universal speed claim. Treat small timing differences within the raw sample spread as noise. Allocation counts are less sensitive to machine speed and show how much heap work each composition performs. In these workloads, wrapping and unwrapping added no heap allocations; allocations came from transformations that produced new text. `NormalizeSpace` is algorithmically different: the standard-library composition builds a field slice before joining it, while `str` uses one builder pass.
+
+The [benchmark source](string_benchmark_test.go) and [committed raw output](docs/readme/benchmarks.txt) record exactly what ran, including the Go version and command. Refresh the measurements explicitly with `go -C docs run ./readme -record-benchmarks`; ordinary README generation only renders that frozen snapshot.
+<!-- performance:embed:end -->
+
 <!-- api:embed:start -->
 
 ## API index