Merge pull request #43 from marius-bughiu/feature/unsigned-hashers

Add UInt32Hasher and UInt64Hasher

Author: marius-bughiu

CHANGELOG.md

@@ -6,6 +6,9 @@ All notable changes to Celerity are documented here. This project follows [Keep
 
 ### Added
 
+- `UInt32Hasher` in `Celerity.Hashing` — Wang/Jenkins-style bit-mixer for `uint` keys. Struct hasher, `AggressiveInlining`. Counterpart to `Int32WangNaiveHasher`.
+- `UInt64Hasher` in `Celerity.Hashing` — Murmur3 `fmix64` finalizer for `ulong` keys. Struct hasher, `AggressiveInlining`. Counterpart to `Int64Murmur3Hasher`.
+- `UInt32HasherTests` and `UInt64HasherTests` — exact-value cases (including values crossing the sign bit), determinism, avalanche on the top bit, and a 1000-value distinctness sweep for the 64-bit mixer.
 - `DefaultHasher<T>` in `Celerity.Hashing` — a general-purpose `IHashProvider<T>` that delegates to `EqualityComparer<T>.Default.GetHashCode()`. Use it when no specialized hasher exists for a type (e.g. `Guid`, custom structs, or reference types). It is a struct, so the JIT devirtualizes the outer call on the probe path; the inner `EqualityComparer<T>` dispatch is unavoidable but acceptable for non-hot-path types.
 - XML doc comments added to `IHashProvider<T>`, `Int32WangNaiveHasher`, `Int64Murmur3Hasher`, and `StringFnV1AHasher`. All public hasher types now carry full XML documentation.
 - `DefaultHasherTests` — verifies BCL contract equivalence for int, string, and Guid keys; determinism across calls and struct instances; and integration tests confirming `DefaultHasher<T>` satisfies the hasher constraints on `CeleritySet<T,THasher>`, `IntSet<THasher>`, and `CelerityDictionary<TKey,TValue,THasher>`.

ROADMAP.md

@@ -49,7 +49,7 @@ The next release rounds out the `Celerity.Collections` package with missing coll
 
 ### Hashers
 
-- Add `Int32Murmur3Hasher`, `Int64WangHasher`, `GuidHasher`, `UInt32Hasher`, `UInt64Hasher`. (#24)
+- Add `Int32Murmur3Hasher`, `Int64WangHasher`, `GuidHasher`, `UInt32Hasher`, `UInt64Hasher`. (#24) — `UInt32Hasher` and `UInt64Hasher` `done`; the others still `planned`.
 - Add `DefaultHasher<T>` fallback to `EqualityComparer<T>.Default.GetHashCode()`.
 
 ### Infrastructure

src/Celerity.Tests/Hashing/UInt32HasherTests.cs

@@ -0,0 +1,51 @@
+using Celerity.Hashing;
+
+namespace Celerity.Tests.Hashing;
+
+public class UInt32HasherTests
+{
+    private readonly UInt32Hasher _hasher = new UInt32Hasher();
+
+    [Theory]
+    [InlineData(0u, 0)]
+    [InlineData(1u, 1)]
+    [InlineData(16u, 16)]
+    [InlineData(65536u, 65537)]
+    [InlineData(uint.MaxValue, -65536)]     // 0xFFFFFFFF ^ 0x0000FFFF = 0xFFFF0000
+    [InlineData(0x80000000u, -2147450880)]  // 0x80000000 ^ 0x00008000 = 0x80008000
+    public void Hash_ReturnsExpected(uint input, int expected)
+    {
+        int result = _hasher.Hash(input);
+        Assert.Equal(expected, result);
+    }
+
+    [Fact]
+    public void Hash_IsDeterministic()
+    {
+        uint value = 12345u;
+        int result1 = _hasher.Hash(value);
+        int result2 = _hasher.Hash(value);
+        Assert.Equal(result1, result2);
+    }
+
+    [Fact]
+    public void Hash_DoesNotThrow()
+    {
+        uint[] testValues =
+        {
+            0u,
+            1u,
+            uint.MaxValue,
+            0x7FFFFFFFu,
+            0x80000000u,
+            123456789u,
+            987654321u,
+        };
+
+        foreach (uint val in testValues)
+        {
+            var exception = Record.Exception(() => _hasher.Hash(val));
+            Assert.Null(exception);
+        }
+    }
+}

src/Celerity.Tests/Hashing/UInt64HasherTests.cs

@@ -0,0 +1,69 @@
+using Celerity.Hashing;
+
+namespace Celerity.Tests.Hashing;
+
+public class UInt64HasherTests
+{
+    private readonly UInt64Hasher _hasher = new UInt64Hasher();
+
+    [Fact]
+    public void Hash_Zero_ReturnsZero()
+    {
+        // Murmur3 fmix64 maps 0 -> 0 (each stage is a no-op on the zero state).
+        Assert.Equal(0, _hasher.Hash(0UL));
+    }
+
+    [Fact]
+    public void Hash_IsDeterministic()
+    {
+        ulong value = 0xDEADBEEFCAFEBABEUL;
+        int result1 = _hasher.Hash(value);
+        int result2 = _hasher.Hash(value);
+        Assert.Equal(result1, result2);
+    }
+
+    [Fact]
+    public void Hash_DistinctInputs_ProduceDistinctResultsForSmallRange()
+    {
+        // Murmur3 fmix64 is a bijection on 64 bits; truncating to 32 bits on a
+        // small sequential range should still produce distinct hashes with
+        // overwhelming probability. A collision here would indicate a broken
+        // mixer rather than an expected birthday-paradox event.
+        var seen = new HashSet<int>();
+        for (ulong i = 0; i < 1000; i++)
+        {
+            Assert.True(seen.Add(_hasher.Hash(i)),
+                $"Unexpected collision at input {i}.");
+        }
+    }
+
+    [Fact]
+    public void Hash_HighBits_InfluenceResult()
+    {
+        // Avalanche check: two inputs that differ only in their top bit
+        // should produce different 32-bit hashes.
+        int low = _hasher.Hash(1UL);
+        int high = _hasher.Hash(1UL | (1UL << 63));
+        Assert.NotEqual(low, high);
+    }
+
+    [Fact]
+    public void Hash_DoesNotThrow()
+    {
+        ulong[] testValues =
+        {
+            0UL,
+            1UL,
+            ulong.MaxValue,
+            0x7FFFFFFFFFFFFFFFUL,
+            0x8000000000000000UL,
+            0xDEADBEEFCAFEBABEUL,
+        };
+
+        foreach (ulong val in testValues)
+        {
+            var exception = Record.Exception(() => _hasher.Hash(val));
+            Assert.Null(exception);
+        }
+    }
+}

src/Celerity/Hashing/UInt32Hasher.cs

@@ -0,0 +1,22 @@
+using System.Runtime.CompilerServices;
+
+namespace Celerity.Hashing;
+
+/// <summary>
+/// A fast hash provider for <see cref="uint"/> keys using a Wang/Jenkins-style
+/// integer bit-mixer.
+/// </summary>
+/// <remarks>
+/// This is the <see cref="uint"/> counterpart to <see cref="Int32WangNaiveHasher"/>.
+/// It folds the high bits of the value into the low bits (<c>key ^ (key &gt;&gt; 16)</c>),
+/// then reinterprets the 32-bit result as a signed integer. Prefer this when
+/// key distribution is already reasonably uniform and latency matters more than
+/// collision resistance; use a full Murmur3 finalizer for clustered or
+/// adversarial inputs.
+/// </remarks>
+public struct UInt32Hasher : IHashProvider<uint>
+{
+    /// <inheritdoc/>
+    [MethodImpl(MethodImplOptions.AggressiveInlining)]
+    public int Hash(uint key) => (int)(key ^ (key >> 16));
+}

src/Celerity/Hashing/UInt64Hasher.cs

@@ -0,0 +1,42 @@
+using System.Runtime.CompilerServices;
+
+namespace Celerity.Hashing;
+
+/// <summary>
+/// A high-quality hash provider for <see cref="ulong"/> keys using the
+/// Murmur3 64-bit finalizer ("fmix64").
+/// </summary>
+/// <remarks>
+/// This is the <see cref="ulong"/> counterpart to <see cref="Int64Murmur3Hasher"/>.
+/// Every input bit affects every output bit, making it a good choice for
+/// clustered or adversarial key distributions. The 64-bit result is truncated
+/// to 32 bits by taking the lower half and reinterpreting it as a signed int.
+/// </remarks>
+public struct UInt64Hasher : IHashProvider<ulong>
+{
+    private const ulong C1 = 0xff51afd7ed558ccdUL;
+    private const ulong C2 = 0xc4ceb9fe1a85ec53UL;
+
+    /// <inheritdoc/>
+    [MethodImpl(MethodImplOptions.AggressiveInlining)]
+    public int Hash(ulong key)
+    {
+        // XOR with its shifted self.
+        key ^= key >> 33;
+
+        // Multiply by a large odd constant.
+        key *= C1;
+
+        // XOR again with its shifted self.
+        key ^= key >> 33;
+
+        // Multiply by another large odd constant.
+        key *= C2;
+
+        // Final XOR.
+        key ^= key >> 33;
+
+        // Take the lower 32 bits as the final hash value.
+        return (int)key;
+    }
+}