Merge remote-tracking branch 'origin' into refactor/name-bucket-slot-table

## Description

Currently, the errors are not sentinel, and so are hard to test for. This PR makes sure hash collision errors are accounted for.

## Changes

- Add `ErrBadHash`. Happens when there are too many collisions for an item to be added.

### Design Decisions

- Chose to name `ErrBadHash` over `ErrCycle` because the feedbach that the user should be given is to evaluate their hash functions. Cycle collision is a bit esoteric.

## Checklist

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

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

hash_table.go

@@ -1,12 +1,21 @@
 package cuckoo
 
 import (
+	"errors"
 	"fmt"
 	"iter"
 	"math/bits"
 	"strings"
 )
 
+// ErrBadHash occurs when the hashes given to a [Table] cause too many key
+// collisions. Try rebuilding the table using:
+//
+//  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 HashTable which uses cuckoo hashing to resolve collision. Create
 // one with [New]. Or if you want more granularity, use [NewBy] or
 // [NewCustom].
@@ -128,7 +137,7 @@ func (t *HashTable[K, V]) Put(key K, value V) (err error) {
 	}
 
 	if t.load() < t.minLoadFactor {
-		return fmt.Errorf("bad hash: resize on load %d/%d = %f", t.Size(), t.TotalCapacity(), t.load())
+		return fmt.Errorf("hash functions produced a cycle at load %d/%d: %w", t.Size(), t.TotalCapacity(), ErrBadHash)
 	}
 
 	if err := t.grow(); err != nil {