refactor!: shorter constructors, bucket → subtable (#22)

## Description

Currently, the name of `bucket` is a bit confusing, because it is considered a 'table' in literature (as well as the whole hash table). A `bucket` is better described as a 'subtable', which is used by the total hash table to perform cuckoo hashing.

In addition, the constructors `NewTable`, `NewTableBy`, and `NewCustomTable` were given shorter names, because the package name `cuckoo` already implies that `New*` would create a hash table with cuckoo hashing. This package has one use-case, and so it unambiguous what constructors produce.

## Changes

- `NewTable` -> `New`
- `NewTableBy` -> `NewBy`
- `NewCustomTable` -> `NewCustom`
- `bucket` -> `subtable`

### Design Decisions

- I would have renamed `Table` and `subtable` to map equivalents, but 'submap' implies that a certain subsection of the map is contained within it, which isn't quite right.
- I chose not to go with `Map` and `table`, because of the split naming convention.

## Checklist

- [x] Tests pass
- [x] Docs updated

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

table.go

@@ -16,35 +16,35 @@ import (
 //  2. A different [Hash] algorithm.
 var ErrBadHash = errors.New("bad hash")
 
-// 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].
+// 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 {
-	bucketA, bucketB bucket[K, V]
-	growthFactor     uint64
-	minLoadFactor    float64
+	tableA, tableB subtable[K, V]
+	growthFactor   uint64
+	minLoadFactor  float64
 }
 
 // TotalCapacity 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]) TotalCapacity() uint64 {
-	return t.bucketA.capacity + t.bucketB.capacity
+func (t *Table[K, V]) TotalCapacity() uint64 {
+	return t.tableA.capacity + t.tableB.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 (t *Table[K, V]) Size() int {
+	return int(t.tableA.size + t.tableB.size)
 }
 
 func log2(n uint64) (m int) {
 	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())
 }
 
-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%.
 	// Every slot in the table is full.
 	if t.TotalCapacity() == 0 {
@@ -54,7 +54,7 @@ func (t Table[K, V]) load() float64 {
 	return float64(t.Size()) / float64(t.TotalCapacity())
 }
 
-// resize clears all buckets, changes the sizes of them to a specific capacity,
+// resize clears all tables, changes the sizes of them to a specific capacity,
 // and fills them back up again. It is a helper function for [Table.grow] and
 // [Table.shrink]; use them instead.
 func (t *Table[K, V]) resize(capacity uint64) error {
@@ -63,8 +63,8 @@ func (t *Table[K, V]) resize(capacity uint64) error {
 		entries = append(entries, entry[K, V]{k, v})
 	}
 
-	t.bucketA.resize(capacity)
-	t.bucketB.resize(capacity)
+	t.tableA.resize(capacity)
+	t.tableB.resize(capacity)
 
 	for _, entry := range entries {
 		if err := t.Put(entry.key, entry.value); err != nil {
@@ -75,7 +75,7 @@ func (t *Table[K, V]) resize(capacity uint64) error {
 	return nil
 }
 
-// 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.
 func (t *Table[K, V]) grow() error {
 	var newCapacity uint64
@@ -83,26 +83,26 @@ func (t *Table[K, V]) grow() error {
 	if t.TotalCapacity() == 0 {
 		newCapacity = 1
 	} else {
-		newCapacity = t.bucketA.capacity * t.growthFactor
+		newCapacity = t.tableA.capacity * t.growthFactor
 	}
 
 	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.
 func (t *Table[K, V]) shrink() error {
-	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]. Matches the comma-ok pattern
 // of a builtin map; see [Table.Find] for plain indexing.
 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, true
 	}
 
-	if item, ok := t.bucketB.get(key); ok {
+	if item, ok := t.tableB.get(key); ok {
 		return item, true
 	}
 
@@ -124,21 +124,21 @@ func (t Table[K, V]) Has(key K) (exists bool) {
 
 // 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) {
+	if t.tableA.update(key, value) {
 		return nil
 	}
 
-	if t.bucketB.update(key, value) {
+	if t.tableB.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 {
+		if entry, eviction = t.tableA.evict(entry); !eviction {
 			return nil
 		}
 
-		if entry, eviction = t.bucketB.evict(entry); !eviction {
+		if entry, eviction = t.tableB.evict(entry); !eviction {
 			return nil
 		}
 	}
@@ -157,8 +157,8 @@ func (t *Table[K, V]) Put(key K, value V) (err error) {
 // Drop removes a value for a key in the table. Returns an error if its value
 // cannot be removed.
 func (t *Table[K, V]) Drop(key K) (err error) {
-	t.bucketA.drop(key)
-	t.bucketB.drop(key)
+	t.tableA.drop(key)
+	t.tableB.drop(key)
 
 	if t.load() < t.minLoadFactor {
 		return t.shrink()
@@ -168,9 +168,9 @@ func (t *Table[K, V]) Drop(key K) (err error) {
 }
 
 // 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) {
-		for _, slot := range t.bucketA.slots {
+		for _, slot := range t.tableA.slots {
 			if slot.occupied {
 				if !yield(slot.key, slot.value) {
 					return
@@ -178,7 +178,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 !yield(slot.key, slot.value) {
 					return
@@ -189,8 +189,8 @@ func (t Table[K, V]) Entries() iter.Seq2[K, V] {
 }
 
 // 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 {
+// "table[k1:v1 k2:v2 ...]".
+func (t *Table[K, V]) String() string {
 	var sb strings.Builder
 	sb.WriteString("table[")
 
@@ -208,9 +208,9 @@ func (t Table[K, V]) String() 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.
-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{
 		growthFactor:  DefaultGrowthFactor,
 		bucketSize:    DefaultCapacity,
@@ -224,8 +224,8 @@ func NewCustomTable[K, V any](hashA, hashB Hash[K], compare EqualFunc[K], option
 	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),
+		tableA:        newSubtable[K, V](settings.bucketSize, hashA, compare),
+		tableB:        newSubtable[K, V](settings.bucketSize, hashB, compare),
 	}
 }
 
@@ -233,10 +233,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)) }
 }
 
-// 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.
-func NewTableBy[K, V any, C comparable](keyFunc func(K) C, options ...Option) *Table[K, V] {
-	return NewCustomTable[K, V](
+func NewBy[K, V any, C comparable](keyFunc func(K) C, options ...Option) *Table[K, V] {
+	return NewCustom[K, V](
 		pipe(keyFunc, NewDefaultHash[C]()),
 		pipe(keyFunc, NewDefaultHash[C]()),
 		func(a, b K) bool { return keyFunc(a) == keyFunc(b) },
@@ -244,10 +244,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
 // 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...)
+// [NewBy] or [NewCustom].
+func New[K comparable, V any](options ...Option) *Table[K, V] {
+	return NewCustom[K, V](NewDefaultHash[K](), NewDefaultHash[K](), DefaultEqualFunc[K], options...)
 }