Add support for custom hash functions via context type (#13)

* feat: context support for hash_set

* chore: add tests

* chore: feature update to readme

* fix: add context example to readme

* fix: self ref and test context rename

* fix: improve max_load_percentage handling

* chore: improve sizeOf tests

* fix: example in readme

Author: thevilledev

README.md

@@ -59,6 +59,7 @@ This implementation gives credit and acknowledgement to the [Zig language](https
     * pop
   * Fully documented and robustly tested - in progress
   * Performance aware to minimize unecessary allocs/iteration internally
+  * Custom hash function support
   * "string" support - coming soon
   * Benchmarks - coming soon
 #
@@ -116,6 +117,37 @@ Output of `A | B` - the union of A and B (order is not guaranteed)
 
 #
 
+#### Custom Hash Function
+
+To use a custom hash function, you can use the following types:
+
+- `HashSetUnmanagedWithContext`
+- `HashSetManagedWithContext`
+
+Example:
+
+```zig
+    const SimpleHasher = struct {
+        const Self = @This();
+        pub fn hash(_: Self, key: u32) u64 {
+            return @as(u64, key) *% 0x517cc1b727220a95;
+        }
+        pub fn eql(_: Self, a: u32, b: u32) bool {
+            return a == b;
+        }
+    };
+
+    const ctx = SimpleHasher{};
+    var set = HashSetUnmanagedWithContext(u32, SimpleHasher, 75).initContext(ctx);
+    defer set.deinit(testing.allocator);
+
+    _ = try set.add(testing.allocator, 123);
+    try expect(set.contains(123));
+    try expect(!set.contains(456));
+```
+
+#
+
 #### Installation of Module
 
 To add this module, update your applications build.zig.zon file by adding the `.ziglang-set` dependency definition. 

src/hash_set/managed.zig

@@ -23,23 +23,39 @@ const std = @import("std");
 const mem = std.mem;
 const Allocator = mem.Allocator;
 const SetUnmanaged = @import("unmanaged.zig").HashSetUnmanaged;
+const SetUnmanagedWithContext = @import("unmanaged.zig").HashSetUnmanagedWithContext;
 
 /// fn HashSetManaged(E) creates a set based on element type E.
 /// This implementation is backed by the std.AutoHashMap implementation
 /// where a Value is not needed and considered to be void and
 /// a Key is considered to be a Set element of type E.
 /// The Set comes complete with the common set operations expected
 /// in a comprehensive set-based data-structure.
+/// Note that max_load_percentage is passed as undefined, because the underlying
+/// std.AutoHashMap/std.StringHashMap defaults are used.
 pub fn HashSetManaged(comptime E: type) type {
+    return HashSetManagedWithContext(E, void, undefined);
+}
+
+/// HashSetManagedWithContext creates a set based on element type E with custom hashing behavior.
+/// This variant allows specifying:
+/// - A Context type that implements hash() and eql() functions for custom element hashing
+/// - A max_load_percentage (1-100) that controls hash table resizing
+/// If Context is undefined, then max_load_percentage is ignored.
+///
+/// The Context type must provide:
+///   fn hash(self: Context, key: K) u64
+///   fn eql(self: Context, a: K, b: K) bool
+pub fn HashSetManagedWithContext(comptime E: type, comptime Context: type, comptime max_load_percentage: u8) type {
     return struct {
         allocator: std.mem.Allocator,
 
         map: Map,
+        context: if (Context == void) void else Context = if (Context == void) {} else undefined,
+        max_load_percentage: if (Context == void) void else u8 = if (Context == void) {} else max_load_percentage,
 
         /// The type of the internal hash map
-        pub const Map = SetUnmanaged(E); //selectMap(E);
-        //pub const Map = std.AutoHashMap(E, void);
-        /// The integer type used to store the size of the map, borrowed from map
+        pub const Map = SetUnmanagedWithContext(E, Context, max_load_percentage);
         pub const Size = Map.Size;
         /// The iterator type returned by iterator(), key-only for sets
         pub const Iterator = Map.Iterator;
@@ -51,6 +67,17 @@ pub fn HashSetManaged(comptime E: type) type {
             return .{
                 .allocator = allocator,
                 .map = Map.init(),
+                .context = if (Context == void) {} else undefined,
+                .max_load_percentage = if (Context == void) {} else max_load_percentage,
+            };
+        }
+
+        pub fn initContext(allocator: std.mem.Allocator, context: Context) Self {
+            return .{
+                .allocator = allocator,
+                .map = Map.initContext(context),
+                .context = context,
+                .max_load_percentage = max_load_percentage,
             };
         }
 
@@ -835,9 +862,37 @@ test "in-place methods" {
 test "sizeOf" {
     const unmanagedSize = @sizeOf(SetUnmanaged(u32));
     const managedSize = @sizeOf(HashSetManaged(u32));
+    const managedWithVoidContextSize = @sizeOf(HashSetManagedWithContext(u32, void, undefined));
+    const managedWithContextSize = @sizeOf(HashSetManagedWithContext(u32, TestContext, 75));
 
     // The managed must be only 16 bytes larger, the cost of the internal allocator
     // otherwise we've added some CRAP!
     const expectedDiff = 16;
     try expectEqual(expectedDiff, managedSize - unmanagedSize);
+
+    // The managed with void context must be the same size as the managed.
+    // The managed with context must be larger by the size of the Context type,
+    // due to the added Context + allocator and alignment padding.
+    const expectedContextDiff = 16;
+    try expectEqual(expectedDiff, managedWithVoidContextSize - unmanagedSize);
+    try expectEqual(expectedContextDiff, managedWithContextSize - managedSize);
+}
+
+const TestContext = struct {
+    const Self = @This();
+    pub fn hash(_: Self, key: u32) u64 {
+        return @as(u64, key) *% 0x517cc1b727220a95;
+    }
+    pub fn eql(_: Self, a: u32, b: u32) bool {
+        return a == b;
+    }
+};
+
+test "custom hash function" {
+    const context = TestContext{};
+    var set = HashSetManagedWithContext(u32, TestContext, 75).initContext(testing.allocator, context);
+    defer set.deinit();
+
+    _ = try set.add(123);
+    try expect(set.contains(123));
 }

src/hash_set/unmanaged.zig

@@ -20,6 +20,7 @@
 ///
 const std = @import("std");
 const mem = std.mem;
+const math = std.math;
 const Allocator = mem.Allocator;
 
 /// comptime selection of the map type for string vs everything else.
@@ -33,27 +34,60 @@ fn selectMap(comptime E: type) type {
     }
 }
 
+/// Select a context-aware hash map type
+fn selectMapWithContext(comptime E: type, comptime Context: type, comptime max_load_percentage: u8) type {
+    return std.HashMapUnmanaged(E, void, Context, max_load_percentage);
+}
+
 /// HashSetUnmanaged is an implementation of a Set where there is no internal
 /// allocator and all allocating methods require a first argument allocator.
 /// This is a more compact Set built on top of the the HashMapUnmanaged
 /// datastructure.
+/// Note that max_load_percentage defaults to undefined, because the underlying
+/// std.AutoHashMap/std.StringHashMap defaults are used.
 pub fn HashSetUnmanaged(comptime E: type) type {
+    return HashSetUnmanagedWithContext(E, void, undefined);
+}
+
+/// HashSetUnmanagedWithContext creates a set based on element type E with custom hashing behavior.
+/// This variant allows specifying:
+/// - A Context type that implements hash() and eql() functions for custom element hashing
+/// - A max_load_percentage (1-100) that controls hash table resizing
+/// If Context is undefined, then max_load_percentage is ignored.
+///
+/// The Context type must provide:
+///   fn hash(self: Context, key: K) u64
+///   fn eql(self: Context, a: K, b: K) bool
+pub fn HashSetUnmanagedWithContext(comptime E: type, comptime Context: type, comptime max_load_percentage: u8) type {
     return struct {
         /// The type of the internal hash map
-        pub const Map = selectMap(E);
+        pub const Map = if (Context == void) selectMap(E) else selectMapWithContext(E, Context, max_load_percentage);
 
         unmanaged: Map,
+        context: if (Context == void) void else Context = if (Context == void) {} else undefined,
+        max_load_percentage: if (Context == void) void else u8 = if (Context == void) {} else max_load_percentage,
 
         pub const Size = Map.Size;
         /// The iterator type returned by iterator(), key-only for sets
         pub const Iterator = Map.KeyIterator;
 
         const Self = @This();
 
-        /// Initialzies a Set with the given Allocator
+        /// Initialize a default set without context
         pub fn init() Self {
             return .{
                 .unmanaged = Map{},
+                .context = if (Context == void) {} else undefined,
+                .max_load_percentage = if (Context == void) {} else max_load_percentage,
+            };
+        }
+
+        /// Initialize with a custom context
+        pub fn initContext(context: Context) Self {
+            return .{
+                .unmanaged = Map{},
+                .context = context,
+                .max_load_percentage = max_load_percentage,
             };
         }
 
@@ -765,6 +799,177 @@ test "sizeOf matches" {
     // No bloat guarantee, after all we're just building on top of what's good.
     // "What's good Miley!?!?""
     const expectedByteSize = 24;
-    try expectEqual(expectedByteSize, @sizeOf(std.hash_map.AutoHashMapUnmanaged(u32, void)));
-    try expectEqual(expectedByteSize, @sizeOf(HashSetUnmanaged(u32)));
+    const autoHashMapSize = @sizeOf(std.hash_map.AutoHashMapUnmanaged(u32, void));
+    const hashSetSize = @sizeOf(HashSetUnmanaged(u32));
+    try expectEqual(expectedByteSize, autoHashMapSize);
+    try expectEqual(expectedByteSize, hashSetSize);
+
+    // The unmanaged with void context must be the same size as the unmanaged.
+    // The unmanaged with context must be larger by the size of the empty Context struct,
+    // due to the added Context and alignment padding.
+    const expectedContextDiff = 8;
+    const hashSetWithVoidContextSize = @sizeOf(HashSetUnmanagedWithContext(u32, void, undefined));
+    const hashSetWithContextSize = @sizeOf(HashSetUnmanagedWithContext(u32, TestContext, 75));
+    try expectEqual(0, hashSetWithVoidContextSize - hashSetSize);
+    try expectEqual(expectedContextDiff, hashSetWithContextSize - hashSetSize);
+}
+
+const TestContext = struct {
+    const Self = @This();
+    pub fn hash(_: Self, key: u32) u64 {
+        return @as(u64, key) *% 0x517cc1b727220a95;
+    }
+    pub fn eql(_: Self, a: u32, b: u32) bool {
+        return a == b;
+    }
+};
+
+test "custom hash function comprehensive" {
+    const context = TestContext{};
+    var set = HashSetUnmanagedWithContext(u32, TestContext, 75).initContext(context);
+    defer set.deinit(testing.allocator);
+
+    // Test basic operations
+    _ = try set.add(testing.allocator, 123);
+    _ = try set.add(testing.allocator, 456);
+    try expect(set.contains(123));
+    try expect(set.contains(456));
+    try expect(!set.contains(789));
+    try expectEqual(set.cardinality(), 2);
+
+    // Test clone with custom context
+    var cloned = try set.clone(testing.allocator);
+    defer cloned.deinit(testing.allocator);
+    try expect(cloned.contains(123));
+    try expect(set.eql(cloned));
+
+    // Test set operations with custom context
+    var other = HashSetUnmanagedWithContext(u32, TestContext, 75).initContext(context);
+    defer other.deinit(testing.allocator);
+    _ = try other.add(testing.allocator, 456);
+    _ = try other.add(testing.allocator, 789);
+
+    // Test union
+    var union_set = try set.unionOf(testing.allocator, other);
+    defer union_set.deinit(testing.allocator);
+    try expectEqual(union_set.cardinality(), 3);
+    try expect(union_set.containsAllSlice(&.{ 123, 456, 789 }));
+
+    // Test intersection
+    var intersection = try set.intersectionOf(testing.allocator, other);
+    defer intersection.deinit(testing.allocator);
+    try expectEqual(intersection.cardinality(), 1);
+    try expect(intersection.contains(456));
+
+    // Test difference
+    var difference = try set.differenceOf(testing.allocator, other);
+    defer difference.deinit(testing.allocator);
+    try expectEqual(difference.cardinality(), 1);
+    try expect(difference.contains(123));
+
+    // Test symmetric difference
+    var sym_diff = try set.symmetricDifferenceOf(testing.allocator, other);
+    defer sym_diff.deinit(testing.allocator);
+    try expectEqual(sym_diff.cardinality(), 2);
+    try expect(sym_diff.containsAllSlice(&.{ 123, 789 }));
+
+    // Test in-place operations
+    try set.unionUpdate(testing.allocator, other);
+    try expectEqual(set.cardinality(), 3);
+    try expect(set.containsAllSlice(&.{ 123, 456, 789 }));
+}
+
+test "custom hash function with different load factors" {
+    const context = TestContext{};
+
+    // Test with low load factor
+    var low_load = HashSetUnmanagedWithContext(u32, TestContext, 25).initContext(context);
+    defer low_load.deinit(testing.allocator);
+
+    // Test with high load factor
+    var high_load = HashSetUnmanagedWithContext(u32, TestContext, 90).initContext(context);
+    defer high_load.deinit(testing.allocator);
+
+    // Add same elements to both
+    for (0..100) |i| {
+        _ = try low_load.add(testing.allocator, @intCast(i));
+        _ = try high_load.add(testing.allocator, @intCast(i));
+    }
+
+    // Verify functionality is identical despite different load factors
+    try expectEqual(low_load.cardinality(), high_load.cardinality());
+    try expect(low_load.capacity() != high_load.capacity()); // Should be different due to load factors
+
+    // Verify both sets contain the same elements
+    for (0..100) |i| {
+        const val: u32 = @intCast(i);
+        try expect(low_load.contains(val) and high_load.contains(val));
+    }
+}
+
+test "custom hash function error cases" {
+    const context = TestContext{};
+    var set = HashSetUnmanagedWithContext(u32, TestContext, 75).initContext(context);
+    defer set.deinit(testing.allocator);
+
+    // Test allocation failures
+    var failing_allocator = std.testing.FailingAllocator.init(testing.allocator, .{ .fail_index = 0 });
+    try std.testing.expectError(error.OutOfMemory, set.add(failing_allocator.allocator(), 123));
+}
+
+// String context for testing string usage with custom hash function
+const StringContext = struct {
+    pub fn hash(self: @This(), str: []const u8) u64 {
+        _ = self;
+        // Simple FNV-1a hash
+        var h: u64 = 0xcbf29ce484222325;
+        for (str) |b| {
+            h = (h ^ b) *% 0x100000001b3;
+        }
+        return h;
+    }
+
+    pub fn eql(self: @This(), a: []const u8, b: []const u8) bool {
+        _ = self;
+        return std.mem.eql(u8, a, b);
+    }
+};
+
+test "custom hash function string usage" {
+    const context = StringContext{};
+    var A = HashSetUnmanagedWithContext([]const u8, StringContext, 75).initContext(context);
+    defer A.deinit(testing.allocator);
+
+    var B = HashSetUnmanagedWithContext([]const u8, StringContext, 75).initContext(context);
+    defer B.deinit(testing.allocator);
+
+    _ = try A.add(testing.allocator, "Hello");
+    _ = try B.add(testing.allocator, "World");
+
+    var C = try A.unionOf(testing.allocator, B);
+    defer C.deinit(testing.allocator);
+    try expectEqual(2, C.cardinality());
+    try expect(C.containsAllSlice(&.{ "Hello", "World" }));
+
+    // Test string-specific behavior
+    try expect(A.contains("Hello"));
+    try expect(!A.contains("hello")); // Case sensitive
+    try expect(!A.contains("Hell")); // Prefix doesn't match
+    try expect(!A.contains("Hello ")); // Trailing space matters
+
+    // Test with longer strings
+    _ = try A.add(testing.allocator, "This is a longer string to test hash collisions");
+    _ = try A.add(testing.allocator, "This is another longer string to test hash collisions");
+    try expectEqual(3, A.cardinality());
+
+    // Test with empty string
+    _ = try A.add(testing.allocator, "");
+    try expect(A.contains(""));
+    try expectEqual(4, A.cardinality());
+
+    // Test with strings containing special characters
+    _ = try A.add(testing.allocator, "Hello\n");
+    _ = try A.add(testing.allocator, "Hello\r");
+    _ = try A.add(testing.allocator, "Hello\t");
+    try expectEqual(7, A.cardinality());
 }