chore: move from tools/dsa (#1)

Moved the implementation of this hash table from `tools/dsa` #1.

Reviewed-on: #1
Co-authored-by: M.V. Hutz <git@maximhutz.me>
Co-committed-by: M.V. Hutz <git@maximhutz.me>

table.go

@@ -0,0 +1,203 @@
+package cuckoo
+
+import (
+	"fmt"
+	"iter"
+	"math/bits"
+	"strings"
+)
+
+// A Table is hash table that uses cuckoo hashing to resolve collision. Create
+// one with [NewTable]. Or if you want more granularity, use [NewTableBy] or
+// [NewCustomTable].
+type Table[K, V any] struct {
+	bucketA, bucketB bucket[K, V]
+	growthFactor     uint64
+	minLoadFactor    float64
+}
+
+// Capacity returns the number of slots allocated for the [Table]. To get the
+// number of slots filled, look at [Table.Size].
+func (t Table[K, V]) Capacity() uint64 {
+	return t.bucketA.capacity + t.bucketB.capacity
+}
+
+// Size returns how many slots are filled in the [Table].
+func (t Table[K, V]) Size() int {
+	return int(t.bucketA.size + t.bucketB.size)
+}
+
+func log2(n uint64) (m int) {
+	return bits.Len64(n) - 1
+}
+
+func (t Table[K, V]) maxEvictions() int {
+	return 3 * log2(t.Capacity())
+}
+
+func (t Table[K, V]) load() float64 {
+	return float64(t.Size()) / float64(t.Capacity())
+}
+
+func (t *Table[K, V]) resize() error {
+	entries := make([]entry[K, V], 0, t.Size())
+	for k, v := range t.Entries() {
+		entries = append(entries, entry[K, V]{k, v})
+	}
+
+	t.bucketA.resize(t.growthFactor * t.bucketA.capacity)
+	t.bucketB.resize(t.growthFactor * t.bucketB.capacity)
+
+	for _, entry := range entries {
+		if err := t.Put(entry.key, entry.value); err != nil {
+			return err
+		}
+	}
+
+	return nil
+}
+
+// Get fetches the value for a key in the [Table]. Returns an error if no value
+// is found.
+func (t Table[K, V]) Get(key K) (value V, err error) {
+	if item, ok := t.bucketA.get(key); ok {
+		return item, nil
+	}
+
+	if item, ok := t.bucketB.get(key); ok {
+		return item, nil
+	}
+
+	return value, fmt.Errorf("key '%v' not found", key)
+}
+
+// Has returns true if a key has a value in the table.
+func (t Table[K, V]) Has(key K) (exists bool) {
+	_, err := t.Get(key)
+	return err == nil
+}
+
+// Put sets the value for a key. Returns error if its value cannot be set.
+func (t *Table[K, V]) Put(key K, value V) (err error) {
+	if t.bucketA.update(key, value) {
+		return nil
+	}
+
+	if t.bucketB.update(key, value) {
+		return nil
+	}
+
+	entry, eviction := entry[K, V]{key, value}, false
+	for range t.maxEvictions() {
+		if entry, eviction = t.bucketA.evict(entry); !eviction {
+			return nil
+		}
+
+		if entry, eviction = t.bucketB.evict(entry); !eviction {
+			return nil
+		}
+	}
+
+	if t.load() < t.minLoadFactor {
+		return fmt.Errorf("bad hash: resize on load %d/%d = %f", t.Size(), t.Capacity(), t.load())
+	}
+
+	if err := t.resize(); err != nil {
+		return err
+	}
+
+	return t.Put(entry.key, entry.value)
+}
+
+// Drop removes a value for a key in the table. Returns an error if its value
+// cannot be removed.
+//
+// Deprecated: Do not use.
+func (t Table[K, V]) Drop(_ K) {
+	panic("Not implemented")
+}
+
+// Entries returns an unordered sequence of all key-value pairs in the table.
+func (t Table[K, V]) Entries() iter.Seq2[K, V] {
+	return func(yield func(K, V) bool) {
+		for _, slot := range t.bucketA.slots {
+			if slot.occupied {
+				if !yield(slot.key, slot.value) {
+					return
+				}
+			}
+		}
+
+		for _, slot := range t.bucketB.slots {
+			if slot.occupied {
+				if !yield(slot.key, slot.value) {
+					return
+				}
+			}
+		}
+	}
+}
+
+// String returns the entries of the table as a string in the format:
+// "table[k1:v1 h2:v2 ...]".
+func (t Table[K, V]) String() string {
+	var sb strings.Builder
+	sb.WriteString("table[")
+
+	first := true
+	for k, v := range t.Entries() {
+		if !first {
+			sb.WriteString(" ")
+		}
+
+		fmt.Fprintf(&sb, "%v:%v", k, v)
+		first = false
+	}
+
+	sb.WriteString("]")
+	return sb.String()
+}
+
+// NewCustomTable creates a [Table] with custom [Hash] and [EqualFunc]
+// functions, along with any [Option] the user provides.
+func NewCustomTable[K, V any](hashA, hashB Hash[K], compare EqualFunc[K], options ...Option) *Table[K, V] {
+	settings := &settings{
+		growthFactor:  DefaultGrowthFactor,
+		bucketSize:    DefaultCapacity,
+		minLoadFactor: DefaultMinimumLoad,
+	}
+
+	for _, option := range options {
+		option(settings)
+	}
+
+	return &Table[K, V]{
+		growthFactor:  settings.growthFactor,
+		minLoadFactor: settings.minLoadFactor,
+		bucketA:       newBucket[K, V](settings.bucketSize, hashA, compare),
+		bucketB:       newBucket[K, V](settings.bucketSize, hashB, compare),
+	}
+}
+
+func pipe[X, Y, Z any](a func(X) Y, b func(Y) Z) func(X) Z {
+	return func(x X) Z { return b(a(x)) }
+}
+
+// NewTableBy creates a [Table] for any key type by using keyFunc to derive a
+// comparable key. Two keys with the same derived key are treated as equal.
+func NewTableBy[K, V any, C comparable](keyFunc func(K) C, options ...Option) *Table[K, V] {
+	return NewCustomTable[K, V](
+		pipe(keyFunc, NewDefaultHash[C]()),
+		pipe(keyFunc, NewDefaultHash[C]()),
+		func(a, b K) bool { return keyFunc(a) == keyFunc(b) },
+		options...,
+	)
+}
+
+// NewTable creates a [Table] using the default [Hash] and [EqualFunc]. Use
+// the [Option] functions to configure its behavior. Note that this constructor
+// is only provided for comparable keys. For arbitrary keys, consider
+// [NewTableBy] or [NewCustomTable].
+func NewTable[K comparable, V any](options ...Option) *Table[K, V] {
+	return NewCustomTable[K, V](NewDefaultHash[K](), NewDefaultHash[K](), DefaultEqualFunc[K], options...)
+}