tools/go-cuckoo
1
0
Fork 0
Code Issues 2 Pull Requests Actions Releases 4 Wiki Activity

feat!: Drop returns bool, Put doesn't stack-overflow #21

Merged
mvhutz merged 12 commits from feat/safe-put into main 2026-04-17 01:31:02 +00:00
Conversation 0 Commits 12 Files Changed 6 +121 -104
11 changed files with 121 additions and 104 deletions
Download Patch File Download Diff File Expand all files Collapse all files
Showing only changes of commit 1f7c64366d - Show all commits

5
.golangci.yml
View File

@@ -114,6 +114,9 @@ linters:
# Reports uses of functions with replacement inside the testing package. # Reports uses of functions with replacement inside the testing package.
- usetesting - usetesting
# Reports mixed receiver types in structs/interfaces.
- recvcheck
settings: settings:
revive: revive:
rules: rules:
@@ -198,7 +201,7 @@ linters:
# warns when initialism, variable or package naming conventions are not followed. # warns when initialism, variable or package naming conventions are not followed.
- name: var-naming - name: var-naming
misspell: misspell:
# Correct spellings using locale preferences for US or UK. # Correct spellings using locale preferences for US or UK.
# Setting locale to US will correct the British spelling of 'colour' to 'color'. # Setting locale to US will correct the British spelling of 'colour' to 'color'.

2
compare.go
View File

@@ -2,7 +2,7 @@ package cuckoo
// An EqualFunc determines whethers two keys are 'equal'. Keys that are 'equal' // An EqualFunc determines whethers two keys are 'equal'. Keys that are 'equal'
// are teated as the same by the [Table]. A good EqualFunc is pure, // are teated as the same by the [Table]. A good EqualFunc is pure,
// deterministic, and fast. By default, [NewTable] uses [DefaultEqualFunc]. // deterministic, and fast. By default, [New] uses [DefaultEqualFunc].
// //
// This function MUST NOT return true if the [Hash] digest of two keys // This function MUST NOT return true if the [Hash] digest of two keys
// are different: the [Table] will not work. // are different: the [Table] will not work.

2
compare_example_test.go
View File

@@ -28,7 +28,7 @@ func ExampleEqualFunc_badEqualFunc() {
// Two users with the same ID are equal. // Two users with the same ID are equal.
isEqual := func(a, b User) bool { return a.ID == b.ID } isEqual := func(a, b User) bool { return a.ID == b.ID }
userbase := cuckoo.NewCustomTable[User, bool](makeHash(1), makeHash(2), isEqual) userbase := cuckoo.NewCustom[User, bool](makeHash(1), makeHash(2), isEqual)
(userbase.Put(User{"1", "Robert Doe"}, true)) (userbase.Put(User{"1", "Robert Doe"}, true))

10
cuckoo_fuzz_test.go
View File

@@ -56,7 +56,7 @@ func FuzzInsertLookup(f *testing.F) {
fmt.Fprintf(os.Stderr, "seedA=%d seedB=%d capacity=%d growthFactor=%d\n", fmt.Fprintf(os.Stderr, "seedA=%d seedB=%d capacity=%d growthFactor=%d\n",
seedA, seedB, capacity, growthFactor) seedA, seedB, capacity, growthFactor)
actual := cuckoo.NewCustomTable[uint32, uint32]( actual := cuckoo.NewCustom[uint32, uint32](
offsetHash(seedA), offsetHash(seedA),
offsetHash(seedB), offsetHash(seedB),
func(a, b uint32) bool { return a == b }, func(a, b uint32) bool { return a == b },
@@ -74,16 +74,16 @@ func FuzzInsertLookup(f *testing.F) {
delete(expected, step.key) delete(expected, step.key)
_, err := actual.Get(step.key) _, ok = actual.Get(step.key)
assert.Error(err) assert.True(ok)
} else { } else {
_, err := actual.Put(step.key, step.value) _, err := actual.Put(step.key, step.value)
assert.NoError(err) assert.NoError(err)
expected[step.key] = step.value expected[step.key] = step.value
found, err := actual.Get(step.key) found, ok := actual.Get(step.key)
assert.NoError(err) assert.True(ok)
assert.Equal(step.value, found) assert.Equal(step.value, found)
} }

4
cuckoo_internal_test.go
View File

@@ -11,7 +11,7 @@ func TestMaxEvictions(t *testing.T) {
assert := assert.New(t) assert := assert.New(t)
for i := 16; i < 116; i++ { for i := 16; i < 116; i++ {
table := NewTable[int, bool](Capacity(i / 2)) table := New[int, bool](Capacity(i / 2))
expectedEvictions := 3 * math.Floor(math.Log2(float64(i))) expectedEvictions := 3 * math.Floor(math.Log2(float64(i)))
assert.Equal(table.maxEvictions(), int(expectedEvictions)) assert.Equal(table.maxEvictions(), int(expectedEvictions))
@@ -20,7 +20,7 @@ func TestMaxEvictions(t *testing.T) {
func TestLoad(t *testing.T) { func TestLoad(t *testing.T) {
assert := assert.New(t) assert := assert.New(t)
table := NewTable[int, bool](Capacity(8)) table := New[int, bool](Capacity(8))
for i := range 16 { for i := range 16 {
_, err := table.Put(i, true) _, err := table.Put(i, true)

38
cuckoo_test.go
View File

@@ -14,7 +14,7 @@ import (
func TestNewTable(t *testing.T) { func TestNewTable(t *testing.T) {
assert := assert.New(t) assert := assert.New(t)
table := cuckoo.NewTable[int, bool]() table := cuckoo.New[int, bool]()
assert.NotNil(table) assert.NotNil(table)
assert.Zero(table.Size()) assert.Zero(table.Size())
@@ -23,7 +23,7 @@ func TestNewTable(t *testing.T) {
func TestAddItem(t *testing.T) { func TestAddItem(t *testing.T) {
assert := assert.New(t) assert := assert.New(t)
key, value := 0, true key, value := 0, true
table := cuckoo.NewTable[int, bool]() table := cuckoo.New[int, bool]()
_, err := table.Put(key, value) _, err := table.Put(key, value)
@@ -35,7 +35,7 @@ func TestAddItem(t *testing.T) {
func TestPutOverwrite(t *testing.T) { func TestPutOverwrite(t *testing.T) {
assert := assert.New(t) assert := assert.New(t)
key, value, newValue := 0, 1, 2 key, value, newValue := 0, 1, 2
table := cuckoo.NewTable[int, int]() table := cuckoo.New[int, int]()
(table.Put(key, value)) (table.Put(key, value))
_, err := table.Put(key, newValue) _, err := table.Put(key, newValue)
@@ -50,7 +50,7 @@ func TestPutOverwrite(t *testing.T) {
func TestSameHash(t *testing.T) { func TestSameHash(t *testing.T) {
assert := assert.New(t) assert := assert.New(t)
hash := func(int) uint64 { return 0 } hash := func(int) uint64 { return 0 }
table := cuckoo.NewCustomTable[int, bool](hash, hash, cuckoo.DefaultEqualFunc[int]) table := cuckoo.NewCustom[int, bool](hash, hash, cuckoo.DefaultEqualFunc[int])
_, errA := table.Put(0, true) _, errA := table.Put(0, true)
_, errB := table.Put(1, true) _, errB := table.Put(1, true)
@@ -63,14 +63,14 @@ func TestSameHash(t *testing.T) {
func TestStartingCapacity(t *testing.T) { func TestStartingCapacity(t *testing.T) {
assert := assert.New(t) assert := assert.New(t)
table := cuckoo.NewTable[int, bool](cuckoo.Capacity(64)) table := cuckoo.New[int, bool](cuckoo.Capacity(64))
assert.Equal(uint64(128), table.TotalCapacity()) assert.Equal(uint64(128), table.TotalCapacity())
} }
func TestResizeCapacity(t *testing.T) { func TestResizeCapacity(t *testing.T) {
assert := assert.New(t) assert := assert.New(t)
table := cuckoo.NewTable[int, bool]( table := cuckoo.New[int, bool](
cuckoo.Capacity(8), cuckoo.Capacity(8),
cuckoo.GrowthFactor(2), cuckoo.GrowthFactor(2),
) )
@@ -85,7 +85,7 @@ func TestResizeCapacity(t *testing.T) {
func TestPutMany(t *testing.T) { func TestPutMany(t *testing.T) {
assert := assert.New(t) assert := assert.New(t)
expected, actual := map[int]bool{}, cuckoo.NewTable[int, bool]() expected, actual := map[int]bool{}, cuckoo.New[int, bool]()
for i := range 1_000 { for i := range 1_000 {
expected[i] = true expected[i] = true
@@ -100,7 +100,7 @@ func TestPutMany(t *testing.T) {
func TestGetMany(t *testing.T) { func TestGetMany(t *testing.T) {
assert := assert.New(t) assert := assert.New(t)
table := cuckoo.NewTable[int, bool]() table := cuckoo.New[int, bool]()
for i := range 1_000 { for i := range 1_000 {
_, err := table.Put(i, true) _, err := table.Put(i, true)
@@ -108,12 +108,12 @@ func TestGetMany(t *testing.T) {
} }
for i := range 2_000 { for i := range 2_000 {
value, err := table.Get(i) value, ok := table.Get(i)
if i < 1_000 { if i < 1_000 {
assert.NoError(err) assert.True(ok)
assert.Equal(value, true) assert.Equal(value, true)
} else { } else {
assert.Error(err) assert.False(ok)
} }
} }
} }
@@ -121,7 +121,7 @@ func TestGetMany(t *testing.T) {
func TestDropExistingItem(t *testing.T) { func TestDropExistingItem(t *testing.T) {
assert := assert.New(t) assert := assert.New(t)
key, value := 0, true key, value := 0, true
table := cuckoo.NewTable[int, bool]() table := cuckoo.New[int, bool]()
(table.Put(key, value)) (table.Put(key, value))
had := table.Drop(key) had := table.Drop(key)
@@ -134,7 +134,7 @@ func TestDropExistingItem(t *testing.T) {
func TestDropNoItem(t *testing.T) { func TestDropNoItem(t *testing.T) {
assert := assert.New(t) assert := assert.New(t)
key := 0 key := 0
table := cuckoo.NewTable[int, bool]() table := cuckoo.New[int, bool]()
had := table.Drop(key) had := table.Drop(key)
@@ -146,7 +146,7 @@ func TestDropNoItem(t *testing.T) {
func TestDropItemCapacity(t *testing.T) { func TestDropItemCapacity(t *testing.T) {
assert := assert.New(t) assert := assert.New(t)
key := 0 key := 0
table := cuckoo.NewTable[int, bool]( table := cuckoo.New[int, bool](
cuckoo.Capacity(64), cuckoo.Capacity(64),
cuckoo.GrowthFactor(2), cuckoo.GrowthFactor(2),
) )
@@ -163,7 +163,7 @@ func TestDropItemCapacity(t *testing.T) {
func TestPutNoCapacity(t *testing.T) { func TestPutNoCapacity(t *testing.T) {
assert := assert.New(t) assert := assert.New(t)
key, value := 0, true key, value := 0, true
table := cuckoo.NewTable[int, bool]( table := cuckoo.New[int, bool](
cuckoo.Capacity(0), cuckoo.Capacity(0),
) )
@@ -176,7 +176,7 @@ func TestPutNoCapacity(t *testing.T) {
func TestBadHashCapacity(t *testing.T) { func TestBadHashCapacity(t *testing.T) {
assert := assert.New(t) assert := assert.New(t)
table := cuckoo.NewCustomTable[int, bool]( table := cuckoo.NewCustom[int, bool](
func(int) uint64 { return 0 }, func(int) uint64 { return 0 },
func(int) uint64 { return 0 }, func(int) uint64 { return 0 },
func(a, b int) bool { return a == b }, func(a, b int) bool { return a == b },
@@ -196,7 +196,7 @@ func TestBadHashCapacity(t *testing.T) {
func TestDropResizeCapacity(t *testing.T) { func TestDropResizeCapacity(t *testing.T) {
assert := assert.New(t) assert := assert.New(t)
table := cuckoo.NewTable[int, bool]( table := cuckoo.New[int, bool](
cuckoo.Capacity(10), cuckoo.Capacity(10),
) )
@@ -216,9 +216,7 @@ func TestNewTableBy(t *testing.T) {
} }
assert := assert.New(t) assert := assert.New(t)
table := cuckoo.NewTableBy[User, bool]( table := cuckoo.NewBy[User, bool](func(u User) string { return u.id })
func(u User) string { return u.id },
)
_, err := table.Put(User{nil, "1", "Robert"}, true) _, err := table.Put(User{nil, "1", "Robert"}, true)

4
doc.go
View File

@@ -1,8 +1,8 @@
// Package cuckoo provides a hash table that uses cuckoo hashing to achieve // Package cuckoo provides a hash table that uses cuckoo hashing to achieve
// a worst-case O(1) lookup time. // a worst-case O(1) lookup time.
// //
// While a [NewTable] only supports comparable keys by default, you can create // While a [New] only supports comparable keys by default, you can create
// a table with any key type using [NewCustomTable]. Custom [Hash] functions and // a table with any key type using [NewCustom]. Custom [Hash] functions and
// key comparison are also supported. // key comparison are also supported.
// //
// See more: https://en.wikipedia.org/wiki/Cuckoo_hashing // See more: https://en.wikipedia.org/wiki/Cuckoo_hashing

12
doc_example_test.go
View File

@@ -8,25 +8,25 @@ import (
) )
func Example_basic() { func Example_basic() {
table := cuckoo.NewTable[int, string]() table := cuckoo.New[int, string]()
if _, err := table.Put(1, "Hello, World!"); err != nil { if _, err := table.Put(1, "Hello, World!"); err != nil {
fmt.Println("Put error:", err) fmt.Println("Put error:", err)
} }
if item, err := table.Get(1); err != nil { if item, ok := table.Get(1); !ok {
fmt.Println("Error:", err) fmt.Println("Not Found 1!")
} else { } else {
fmt.Println("Found 1:", item) fmt.Println("Found 1:", item)
} }
if item, err := table.Get(0); err != nil { if item, ok := table.Get(0); !ok {
fmt.Println("Error:", err) fmt.Println("Not Found 0!")
} else { } else {
fmt.Println("Found 0:", item) fmt.Println("Found 0:", item)
} }
// Output: // Output:
// Found 1: Hello, World! // Found 1: Hello, World!
// Error: key '0' not found // Not Found 0!
} }

6
settings.go
View File

@@ -9,7 +9,7 @@ import "fmt"
const DefaultCapacity uint64 = 16 const DefaultCapacity uint64 = 16
// DefaultGrowthFactor is the standard resize multiplier for a [Table]. Most // DefaultGrowthFactor is the standard resize multiplier for a [Table]. Most
// hash table implementations use 2. // implementations use 2.
const DefaultGrowthFactor uint64 = 2 const DefaultGrowthFactor uint64 = 2
// defaultMinimumLoad is the default lowest acceptable occupancy of a [Table]. // defaultMinimumLoad is the default lowest acceptable occupancy of a [Table].
@@ -31,10 +31,10 @@ type settings struct {
} }
// An Option modifies the settings of a [Table]. It is used in its constructors // An Option modifies the settings of a [Table]. It is used in its constructors
// like [NewTable], for example. // like [New], for example.
type Option func(*settings) type Option func(*settings)
// Capacity modifies the starting capacity of each bucket of the [Table]. The // Capacity modifies the starting capacity of each subtable of the [Table]. The
// value must be non-negative. // value must be non-negative.
func Capacity(value int) Option { func Capacity(value int) Option {
if value < 0 { if value < 0 {

20
bucket.go → subtable.go
View File

@@ -11,7 +11,7 @@ type slot[K, V any] struct {
occupied bool occupied bool
} }
type bucket[K, V any] struct { type subtable[K, V any] struct {
hash Hash[K] hash Hash[K]
slots []slot[K, V] slots []slot[K, V]
capacity, size uint64 capacity, size uint64
@@ -20,11 +20,11 @@ type bucket[K, V any] struct {
// location determines where in the bucket a certain key would be placed. If the // location determines where in the bucket a certain key would be placed. If the
// capacity is 0, this will panic. // capacity is 0, this will panic.
func (b bucket[K, V]) location(key K) uint64 { func (b *subtable[K, V]) location(key K) uint64 {
return b.hash(key) % b.capacity return b.hash(key) % b.capacity
} }
func (b bucket[K, V]) get(key K) (value V, found bool) { func (b *subtable[K, V]) get(key K) (value V, found bool) {
if b.capacity == 0 { if b.capacity == 0 {
return return
} }
@@ -33,7 +33,7 @@ func (b bucket[K, V]) get(key K) (value V, found bool) {
return slot.Value, slot.occupied && b.compare(slot.Key, key) return slot.Value, slot.occupied && b.compare(slot.Key, key)
} }
func (b *bucket[K, V]) drop(key K) (occupied bool) { func (b *subtable[K, V]) drop(key K) (occupied bool) {
if b.capacity == 0 { if b.capacity == 0 {
return return
} }
@@ -49,8 +49,8 @@ func (b *bucket[K, V]) drop(key K) (occupied bool) {
return false return false
} }
func (b *bucket[K, V]) resized(capacity uint64) bucket[K, V] { func (b *subtable[K, V]) resized(capacity uint64) *subtable[K, V] {
return bucket[K, V]{ return &subtable[K, V]{
slots: make([]slot[K, V], capacity), slots: make([]slot[K, V], capacity),
capacity: capacity, capacity: capacity,
hash: b.hash, hash: b.hash,
@@ -58,7 +58,7 @@ func (b *bucket[K, V]) resized(capacity uint64) bucket[K, V] {
} }
} }
func (b bucket[K, V]) update(key K, value V) (updated bool) { func (b *subtable[K, V]) update(key K, value V) (updated bool) {
if b.capacity == 0 { if b.capacity == 0 {
return return
} }
@@ -73,7 +73,7 @@ func (b bucket[K, V]) update(key K, value V) (updated bool) {
return false return false
} }
func (b *bucket[K, V]) insert(insertion Entry[K, V]) (evicted Entry[K, V], eviction bool) { func (b *subtable[K, V]) insert(insertion Entry[K, V]) (evicted Entry[K, V], eviction bool) {
if b.capacity == 0 { if b.capacity == 0 {
return insertion, true return insertion, true
} }
@@ -96,8 +96,8 @@ func (b *bucket[K, V]) insert(insertion Entry[K, V]) (evicted Entry[K, V], evict
return insertion, true return insertion, true
} }
func newBucket[K, V any](capacity uint64, hash Hash[K], compare EqualFunc[K]) bucket[K, V] { func newSubtable[K, V any](capacity uint64, hash Hash[K], compare EqualFunc[K]) *subtable[K, V] {
return bucket[K, V]{ return &subtable[K, V]{
hash: hash, hash: hash,
capacity: capacity, capacity: capacity,
compare: compare, compare: compare,

122
table.go
View File

@@ -1,41 +1,50 @@
package cuckoo package cuckoo
import ( import (
"errors"
"fmt" "fmt"
"iter" "iter"
"math/bits" "math/bits"
"strings" "strings"
) )
// A Table is hash table that uses cuckoo hashing to resolve collision. Create // ErrBadHash occurs when the hashes given to a [Table] cause too many key
// one with [NewTable]. Or if you want more granularity, use [NewTableBy] or // collisions. Try rebuilding the table using:
// [NewCustomTable]. //
// 1. Different hash seeds. Equal seeds produce equal hash functions, which
// always cycle.
// 2. A different [Hash] algorithm.
var ErrBadHash = errors.New("bad hash")
// A Table which uses cuckoo hashing to resolve collision. Create
// one with [New]. Or if you want more granularity, use [NewBy] or
// [NewCustom].
type Table[K, V any] struct { type Table[K, V any] struct {
bucketA, bucketB bucket[K, V] tableA, tableB *subtable[K, V]
growthFactor uint64 growthFactor uint64
minLoadFactor float64 minLoadFactor float64
} }
// TotalCapacity returns the number of slots allocated for the [Table]. To get the // TotalCapacity returns the number of slots allocated for the [Table]. To get the
// number of slots filled, look at [Table.Size]. // number of slots filled, look at [Table.Size].
func (t Table[K, V]) TotalCapacity() uint64 { func (t *Table[K, V]) TotalCapacity() uint64 {
return t.bucketA.capacity + t.bucketB.capacity return t.tableA.capacity + t.tableB.capacity
} }
// Size returns how many slots are filled in the [Table]. // Size returns how many slots are filled in the [Table].
func (t Table[K, V]) Size() int { func (t *Table[K, V]) Size() int {
return int(t.bucketA.size + t.bucketB.size) return int(t.tableA.size + t.tableB.size)
} }
func log2(n uint64) (m int) { func log2(n uint64) (m int) {
return max(0, bits.Len64(n)-1) return max(0, bits.Len64(n)-1)
} }
func (t Table[K, V]) maxEvictions() int { func (t *Table[K, V]) maxEvictions() int {
return 3 * log2(t.TotalCapacity()) return 3 * log2(t.TotalCapacity())
} }
func (t Table[K, V]) load() float64 { func (t *Table[K, V]) load() float64 {
// When there are no slots in the table, we still treat the load as 100%. // When there are no slots in the table, we still treat the load as 100%.
// Every slot in the table is full. // Every slot in the table is full.
if t.TotalCapacity() == 0 { if t.TotalCapacity() == 0 {
@@ -49,20 +58,20 @@ func (t Table[K, V]) load() float64 {
// size of the table. Returns a displaced entry and 'homeless = true' if an // size of the table. Returns a displaced entry and 'homeless = true' if an
// entry could not be placed after exhausting evictions. // entry could not be placed after exhausting evictions.
func (t *Table[K, V]) insert(entry Entry[K, V]) (displaced Entry[K, V], homeless bool) { func (t *Table[K, V]) insert(entry Entry[K, V]) (displaced Entry[K, V], homeless bool) {
if t.bucketA.update(entry.Key, entry.Value) { if t.tableA.update(entry.Key, entry.Value) {
return return
} }
if t.bucketB.update(entry.Key, entry.Value) { if t.tableB.update(entry.Key, entry.Value) {
return return
} }
for range t.maxEvictions() { for range t.maxEvictions() {
if entry, homeless = t.bucketA.insert(entry); !homeless { if entry, homeless = t.tableA.insert(entry); !homeless {
return return
} }
if entry, homeless = t.bucketB.insert(entry); !homeless { if entry, homeless = t.tableB.insert(entry); !homeless {
return return
} }
} }
@@ -72,12 +81,12 @@ func (t *Table[K, V]) insert(entry Entry[K, V]) (displaced Entry[K, V], homeless
// resized creates an empty copy of the table, with a new capacity for each // resized creates an empty copy of the table, with a new capacity for each
// bucket. // bucket.
func (t Table[K, V]) resized(capacity uint64) Table[K, V] { func (t *Table[K, V]) resized(capacity uint64) *Table[K, V] {
return Table[K, V]{ return &Table[K, V]{
growthFactor: t.growthFactor, growthFactor: t.growthFactor,
minLoadFactor: t.minLoadFactor, minLoadFactor: t.minLoadFactor,
bucketA: t.bucketA.resized(capacity), tableA: t.tableA.resized(capacity),
bucketB: t.bucketB.resized(capacity), tableB: t.tableB.resized(capacity),
} }
} }
@@ -93,11 +102,11 @@ func (t *Table[K, V]) resize(capacity uint64) bool {
} }
} }
*t = updated *t = *updated
return true return true
} }
// grow increases the table's capacity by the [Table.growthFactor]. If the // grow increases the table's capacity by the growth factor. If the
// capacity is 0, it increases it to 1. // capacity is 0, it increases it to 1.
func (t *Table[K, V]) grow() bool { func (t *Table[K, V]) grow() bool {
var newCapacity uint64 var newCapacity uint64
@@ -105,36 +114,43 @@ func (t *Table[K, V]) grow() bool {
if t.TotalCapacity() == 0 { if t.TotalCapacity() == 0 {
newCapacity = 1 newCapacity = 1
} else { } else {
newCapacity = t.bucketA.capacity * t.growthFactor newCapacity = t.tableA.capacity * t.growthFactor
} }
return t.resize(newCapacity) return t.resize(newCapacity)
} }
// shrink reduces the table's capacity by the [Table.growthFactor]. It may // shrink reduces the table's capacity by the growth factor. It may
// reduce it down to 0. // reduce it down to 0.
func (t *Table[K, V]) shrink() bool { func (t *Table[K, V]) shrink() bool {
return t.resize(t.bucketA.capacity / t.growthFactor) return t.resize(t.tableA.capacity / t.growthFactor)
} }
// Get fetches the value for a key in the [Table]. Returns an error if no value // Get fetches the value for a key in the [Table]. Matches the comma-ok pattern
// is found. // of a builtin map; see [Table.Find] for plain indexing.
func (t Table[K, V]) Get(key K) (value V, err error) { func (t *Table[K, V]) Get(key K) (value V, ok bool) {
if item, ok := t.bucketA.get(key); ok { if item, ok := t.tableA.get(key); ok {
return item, nil return item, true
} }
if item, ok := t.bucketB.get(key); ok { if item, ok := t.tableB.get(key); ok {
return item, nil return item, true
} }
return value, fmt.Errorf("key '%v' not found", key) return
}
// Find fetches the value of a key. Matches direct indexing of a builtin map;
// see [Table.Get] for a comma-ok pattern.
func (t *Table[K, V]) Find(key K) (value V) {
value, _ = t.Get(key)
return
} }
// Has returns true if a key has a value in the table. // Has returns true if a key has a value in the table.
func (t Table[K, V]) Has(key K) (exists bool) { func (t *Table[K, V]) Has(key K) (exists bool) {
_, err := t.Get(key) _, exists = t.Get(key)
return err == nil return
} }
// Put sets the value for a key. If it cannot be set, an error is returned, // Put sets the value for a key. If it cannot be set, an error is returned,
@@ -174,7 +190,7 @@ func (t *Table[K, V]) Put(key K, value V) (displaced Entry[K, V], err error) {
// Drop removes a value for a key in the table. Returns whether the key had // Drop removes a value for a key in the table. Returns whether the key had
// existed. // existed.
func (t *Table[K, V]) Drop(key K) bool { func (t *Table[K, V]) Drop(key K) bool {
occupied := t.bucketA.drop(key) || t.bucketB.drop(key) occupied := t.tableA.drop(key) || t.tableB.drop(key)
if t.load() < t.minLoadFactor { if t.load() < t.minLoadFactor {
// The error is not handled here, because table-shrinking is an internal // The error is not handled here, because table-shrinking is an internal
@@ -186,9 +202,9 @@ func (t *Table[K, V]) Drop(key K) bool {
} }
// Entries returns an unordered sequence of all key-value pairs in the table. // Entries returns an unordered sequence of all key-value pairs in the table.
func (t Table[K, V]) Entries() iter.Seq2[K, V] { func (t *Table[K, V]) Entries() iter.Seq2[K, V] {
return func(yield func(K, V) bool) { return func(yield func(K, V) bool) {
for _, slot := range t.bucketA.slots { for _, slot := range t.tableA.slots {
if slot.occupied { if slot.occupied {
if !yield(slot.Key, slot.Value) { if !yield(slot.Key, slot.Value) {
return return
@@ -196,7 +212,7 @@ func (t Table[K, V]) Entries() iter.Seq2[K, V] {
} }
} }
for _, slot := range t.bucketB.slots { for _, slot := range t.tableB.slots {
if slot.occupied { if slot.occupied {
if !yield(slot.Key, slot.Value) { if !yield(slot.Key, slot.Value) {
return return
@@ -207,8 +223,8 @@ func (t Table[K, V]) Entries() iter.Seq2[K, V] {
} }
// String returns the entries of the table as a string in the format: // String returns the entries of the table as a string in the format:
// "table[k1:v1 h2:v2 ...]". // "table[k1:v1 k2:v2 ...]".
func (t Table[K, V]) String() string { func (t *Table[K, V]) String() string {
var sb strings.Builder var sb strings.Builder
sb.WriteString("table[") sb.WriteString("table[")
@@ -226,9 +242,9 @@ func (t Table[K, V]) String() string {
return sb.String() return sb.String()
} }
// NewCustomTable creates a [Table] with custom [Hash] and [EqualFunc] // NewCustom creates a [Table] with custom [Hash] and [EqualFunc]
// functions, along with any [Option] the user provides. // 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] { func NewCustom[K, V any](hashA, hashB Hash[K], compare EqualFunc[K], options ...Option) *Table[K, V] {
settings := &settings{ settings := &settings{
growthFactor: DefaultGrowthFactor, growthFactor: DefaultGrowthFactor,
bucketSize: DefaultCapacity, bucketSize: DefaultCapacity,
@@ -242,8 +258,8 @@ func NewCustomTable[K, V any](hashA, hashB Hash[K], compare EqualFunc[K], option
return &Table[K, V]{ return &Table[K, V]{
growthFactor: settings.growthFactor, growthFactor: settings.growthFactor,
minLoadFactor: settings.minLoadFactor, minLoadFactor: settings.minLoadFactor,
bucketA: newBucket[K, V](settings.bucketSize, hashA, compare), tableA: newSubtable[K, V](settings.bucketSize, hashA, compare),
bucketB: newBucket[K, V](settings.bucketSize, hashB, compare), tableB: newSubtable[K, V](settings.bucketSize, hashB, compare),
} }
} }
@@ -251,10 +267,10 @@ 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)) } return func(x X) Z { return b(a(x)) }
} }
// NewTableBy creates a [Table] for any key type by using keyFunc to derive a // NewBy 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. // 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] { func NewBy[K, V any, C comparable](keyFunc func(K) C, options ...Option) *Table[K, V] {
return NewCustomTable[K, V]( return NewCustom[K, V](
pipe(keyFunc, NewDefaultHash[C]()), pipe(keyFunc, NewDefaultHash[C]()),
pipe(keyFunc, NewDefaultHash[C]()), pipe(keyFunc, NewDefaultHash[C]()),
func(a, b K) bool { return keyFunc(a) == keyFunc(b) }, func(a, b K) bool { return keyFunc(a) == keyFunc(b) },
@@ -262,10 +278,10 @@ func NewTableBy[K, V any, C comparable](keyFunc func(K) C, options ...Option) *T
) )
} }
// NewTable creates a [Table] using the default [Hash] and [EqualFunc]. Use // New creates a [Table] using the default [Hash] and [EqualFunc]. Use
// the [Option] functions to configure its behavior. Note that this constructor // the [Option] functions to configure its behavior. Note that this constructor
// is only provided for comparable keys. For arbitrary keys, consider // is only provided for comparable keys. For arbitrary keys, consider
// [NewTableBy] or [NewCustomTable]. // [NewBy] or [NewCustom].
func NewTable[K comparable, V any](options ...Option) *Table[K, V] { func New[K comparable, V any](options ...Option) *Table[K, V] {
return NewCustomTable[K, V](NewDefaultHash[K](), NewDefaultHash[K](), DefaultEqualFunc[K], options...) return NewCustom[K, V](NewDefaultHash[K](), NewDefaultHash[K](), DefaultEqualFunc[K], options...)
} }