Merge pull request #48 from marius-bughiu/feature/celerity-dictionary-enumeration

Add struct enumerators and Keys/Values to CelerityDictionary

Author: marius-bughiu

CHANGELOG.md

@@ -6,7 +6,9 @@ All notable changes to Celerity are documented here. This project follows [Keep
 
 ### Added
 
-- `IntDictionary.GetEnumerator()`, `IntDictionary.Keys`, and `IntDictionary.Values` — struct-based, allocation-free enumeration over an `IntDictionary<TValue, THasher>`. `Keys` and `Values` expose `KeyCollection` / `ValueCollection` readonly structs, each with their own struct enumerator, so `foreach (var kvp in map)` / `foreach (int k in map.Keys)` / `foreach (var v in map.Values)` do not box. The out-of-band zero-key entry is yielded first. The enumerators track a `_version` counter and throw `InvalidOperationException` on `MoveNext` / `Reset` if the dictionary is mutated mid-enumeration, matching BCL `Dictionary<,>` semantics. First step toward implementing `IReadOnlyDictionary<int, TValue>` (#10). `CelerityDictionary` will get the equivalent surface in a follow-up.
+- `CelerityDictionary.GetEnumerator()`, `CelerityDictionary.Keys`, and `CelerityDictionary.Values` — struct-based, allocation-free enumeration over a `CelerityDictionary<TKey, TValue, THasher>`, mirroring the `IntDictionary` surface added earlier in 1.1.0. `Keys` and `Values` expose `KeyCollection` / `ValueCollection` readonly structs, each with their own struct enumerator, so `foreach (var kvp in map)` / `foreach (var k in map.Keys)` / `foreach (var v in map.Values)` do not box. The out-of-band default-key entry is yielded first — including `null` for reference-type keys. The enumerators track a `_version` counter and throw `InvalidOperationException` on `MoveNext` / `Reset` if the dictionary is mutated mid-enumeration, matching BCL `Dictionary<,>` semantics. Completes issue #10 and unblocks `IReadOnlyDictionary<TKey, TValue>` (#9).
+- `CelerityDictionaryEnumerationTests` — mirror of `IntDictionaryEnumerationTests` covering empty / single / many-entry enumeration, default-key-first ordering for both value-type and reference-type (`null`) keys, `Remove` / `Clear` / resize survival, mutation-during-enumeration detection on insert / overwrite / default-key-insert / remove / clear, `Reset` reuse, `Keys.Count` / `Values.Count` tracking, and `IEnumerable<T>` interface parity.
+- `IntDictionary.GetEnumerator()`, `IntDictionary.Keys`, and `IntDictionary.Values` — struct-based, allocation-free enumeration over an `IntDictionary<TValue, THasher>`. `Keys` and `Values` expose `KeyCollection` / `ValueCollection` readonly structs, each with their own struct enumerator, so `foreach (var kvp in map)` / `foreach (int k in map.Keys)` / `foreach (var v in map.Values)` do not box. The out-of-band zero-key entry is yielded first. The enumerators track a `_version` counter and throw `InvalidOperationException` on `MoveNext` / `Reset` if the dictionary is mutated mid-enumeration, matching BCL `Dictionary<,>` semantics. First step toward implementing `IReadOnlyDictionary<int, TValue>` (#10).
 - `Int32Murmur3Hasher` in `Celerity.Hashing` — Murmur3 32-bit finalizer ("fmix32") for `int` keys. Struct hasher, `AggressiveInlining`. Provides excellent avalanche properties; prefer over `Int32WangNaiveHasher` when key distribution is clustered or adversarial. Maps `0 → 0` (fixed point of fmix32).
 - `Int64WangHasher` in `Celerity.Hashing` — Thomas Wang 64-bit integer hash for `long` keys. Struct hasher, `AggressiveInlining`. Faster than `Int64Murmur3Hasher` while providing better avalanche than a simple XOR-fold; prefer when throughput matters more than adversarial collision resistance. Invertible (bijective on `ulong`) so truncation to 32 bits is the only source of collisions.
 - `Int32Murmur3HasherTests` — exact anchor values for key extremes, determinism, high-bit avalanche check, 1000-value distinctness sweep, and integration tests driving `CelerityDictionary` and `CeleritySet` including the `default(int)` out-of-band slot.

ISSUES.md

@@ -210,7 +210,7 @@ Both constructors now throw `ArgumentOutOfRangeException` for `capacity < 0`, `l
 ## Backlog (post-0.2.0)
 
 - **#9** — Implement `IReadOnlyDictionary<TKey, TValue>` (1.1.0). Requires `Keys`, `Values`, and `GetEnumerator()` first.
-- **#10** — Add `Keys` / `Values` / `GetEnumerator()` (1.1.0). Status: `in-progress in 1.1.0` — `IntDictionary` done (allocation-free struct enumerators, zero-key is yielded first, BCL-style mid-enumeration mutation detection). `CelerityDictionary` still to do.
+- **#10** — Add `Keys` / `Values` / `GetEnumerator()` (1.1.0). Status: `fixed in 1.1.0` — both `IntDictionary` and `CelerityDictionary` now ship allocation-free struct enumerators with `KeyCollection` / `ValueCollection` views. The out-of-band default-key entry (zero-key for `IntDictionary`, `default(TKey)` for `CelerityDictionary`, including `null` for reference-type keys) is yielded first. Mutating the dictionary mid-enumeration throws `InvalidOperationException` on the next `MoveNext` / `Reset`, enforced by a per-instance `_version` counter. Implementing `IReadOnlyDictionary<TKey, TValue>` on top of these is now unblocked (#9).
 - **#11** — Add `Add` / `TryAdd` with duplicate-throwing semantics (0.3.0). Status: `fixed in 0.3.0`.
 - **#12** — `Int32Murmur3Hasher`, `Int64WangHasher`, `GuidHasher`, `UInt32Hasher`, `UInt64Hasher` (0.4.0). Status: `fixed in 1.1.0` — `UInt32Hasher`, `UInt64Hasher`, `GuidHasher`, `Int32Murmur3Hasher`, and `Int64WangHasher` all complete.
 - **#13** — `DefaultHasher<T>` fallback to `EqualityComparer<T>.Default.GetHashCode()`. Status: `fixed in 1.1.0`.

docs/api/collections.md

@@ -35,6 +35,8 @@ Creates a new dictionary. `capacity` is rounded up to the next power of two. `lo
 | Property | Type | Description |
 |----------|------|-------------|
 | `Count`  | `int` | Number of key/value pairs in the dictionary. |
+| `Keys`   | `KeyCollection` | Allocation-free enumerable view over the keys. |
+| `Values` | `ValueCollection` | Allocation-free enumerable view over the values. |
 
 ### Indexer
 
@@ -94,6 +96,14 @@ public void Clear()
 
 Removes all entries. The underlying array capacity is preserved.
 
+#### GetEnumerator
+
+```csharp
+public Enumerator GetEnumerator()
+```
+
+Returns a struct enumerator that yields `KeyValuePair<TKey, TValue?>`. The out-of-band default-key entry is yielded first if present. Mutating the dictionary during enumeration throws `InvalidOperationException` from the next `MoveNext` / `Reset` call, matching BCL `Dictionary<,>` semantics. Iteration order is unspecified and may change between versions.
+
 ### Default-key handling
 
 `default(TKey)` (which is `null` for reference types, `0` for `int`, `Guid.Empty` for `Guid`, etc.) cannot be stored in the regular probe table because it doubles as the empty-slot sentinel. Celerity handles this transparently via a dedicated `_hasDefaultKey` flag and a separate value slot, so callers never need to worry about it.
@@ -110,6 +120,13 @@ dict[0]  = "zero is fine";
 
 if (dict.TryGetValue(42, out var val))
     Console.WriteLine(val); // "hello"
+
+// Zero-allocation enumeration (struct enumerator):
+foreach (var kvp in dict)
+    Console.WriteLine($"{kvp.Key} -> {kvp.Value}");
+
+foreach (int key in dict.Keys) { /* ... */ }
+foreach (var value in dict.Values) { /* ... */ }
 ```
 
 ---