feat: add Swap and Clear methods

[millerjp]

feat: add Swap and Clear methods

Summary

sync.Map gained Swap in Go 1.20 and Clear in Go 1.23. The fork wraps neither. Add both as methods on SyncMap[K, V], matching the stdlib signatures and contracts exactly. Unit tests ship in the same PR; benchmarks land in #12 and BDD scenarios in #13.

Requirements

1. Add func (m *SyncMap[K, V]) Swap(key K, value V) (previous V, loaded bool) in syncmap.go. Wraps sync.Map.Swap. Return the typed zero V if loaded == false.
2. Add func (m *SyncMap[K, V]) Clear() in syncmap.go. Wraps sync.Map.Clear. Removes all entries.
3. Godoc on both methods follows the style established by docs: add doc.go and rewrite godoc on every exported symbol #11.
4. Add unit tests in syncmap_test.go:
   • TestSwap — subtests: absent_returns_zero_V_loaded_false_and_stores, present_returns_old_loaded_true_and_overwrites, zero_V_distinguished_from_absent (critical — use SyncMap[string, int]).
   • TestClear — subtests: empty_map_noop, populated_map_becomes_empty, subsequent_Store_works.
   • Concurrency subtest: TestSwapContention — 100 goroutines same key; count loaded==false via atomic.Int32; assert exactly one.
5. Coverage must not regress. New methods contribute to the 95% total that test: rewrite unit tests to external package with testify/goleak; coverage ≥95% #10 already enforced.
6. CHANGELOG entry is deferred to feat: add top-level CompareAndSwap and CompareAndDelete functions #14 — no CHANGELOG change in this PR.
7. Apache 2.0 header and no AI-attribution tokens in new code (enforced by CI).

Acceptance Criteria

1. grep -nE 'func \(m \*SyncMap\[K, V\]\) Swap\(' syncmap.go returns exactly one match.
2. grep -nE 'func \(m \*SyncMap\[K, V\]\) Clear\(' syncmap.go returns exactly one match.
3. go doc github.com/axonops/syncmap Swap prints non-empty godoc; same for Clear.
4. go test -race -run 'TestSwap|TestClear|TestSwapContention' -count=10 ./... passes stably over 10 repetitions.
5. make coverage reports ≥95% including the new methods.
6. make check passes end-to-end.
7. CI on the PR — green.

Testing Requirements

• Unit tests as enumerated above, in syncmap_test.go.
• -count=10 repetition on the concurrency test.
• make check green.
• CI green.
• Benchmarks for Swap and Clear are owned by feat!: rename Items to Values #12 and may be deferred — not blocking here.
• BDD scenarios for Swap and Clear are owned by feat: add Swap and Clear methods #13 and may be deferred — not blocking here.

Documentation Requirements

• Godoc on both methods — see AC chore: add .gitignore, Makefile, and .golangci.yml #3.
• CHANGELOG entry — see Req ci: add GitHub Actions CI workflow (#5) #6.
• README API reference addition lives in feat: add top-level CompareAndSwap and CompareAndDelete functions #14 (or is amended there if feat: add top-level CompareAndSwap and CompareAndDelete functions #14 has already merged).

Dependencies

• Blocked by: test: rewrite unit tests to external package with testify/goleak; coverage ≥95% #10 (test scaffolding must be in place to receive new tests cleanly).
• Blocks: none.

Labels

• enhancement
• P1