feat: CuckooFilter

README.md

@@ -167,7 +167,8 @@ than the standard filter.
 | Type | Thread-safe | Deletion | Growable | Memory | Use when |
 |------|-------------|----------|----------|--------|----------|
 | `BloomFilter` | No | No | No | 1× | fixed capacity, single-threaded |
-| `CountingBloomFilter` | No | Yes | No | 8× | need deletion, single-threaded |
+| `CountingBloomFilter` | No | Yes | No | 8× | deletion, high accuracy |
+| `CuckooFilter` | No | Yes | No | ~1× | deletion, memory-efficient |
 | `AtomicBloomFilter` | Yes | No | No | 1× | concurrent insert + lookup |
 | `ScalableBloomFilter` | No | No | Yes | 1×+ | unknown or unbounded item count |
 

src/error.rs

@@ -62,6 +62,16 @@ pub enum BloomError {
     ///
     /// [`ScalableBloomFilter::with_options`]: crate::ScalableBloomFilter::with_options
     InvalidTighteningRatio(f64),
+
+    /// A [`CuckooFilter`] insertion failed because the table is too full.
+    ///
+    /// Cuckoo filters can reject insertions when the load factor approaches
+    /// its practical limit (~95%). Construct a larger filter or use a
+    /// [`ScalableBloomFilter`] if unbounded growth is required.
+    ///
+    /// [`CuckooFilter`]: crate::CuckooFilter
+    /// [`ScalableBloomFilter`]: crate::ScalableBloomFilter
+    CapacityExceeded,
 }
 
 impl PartialEq for BloomError {
@@ -76,6 +86,7 @@ impl PartialEq for BloomError {
             (Self::IncompatibleGeometry { m: m1, k: k1 }, Self::IncompatibleGeometry { m: m2, k: k2 }) => m1 == m2 && k1 == k2,
             (Self::InvalidGrowthFactor(a), Self::InvalidGrowthFactor(b)) => a == b,
             (Self::InvalidTighteningRatio(a), Self::InvalidTighteningRatio(b)) => a == b || (a.is_nan() && b.is_nan()),
+            (Self::CapacityExceeded, Self::CapacityExceeded) => true,
             _ => false,
         }
     }
@@ -105,6 +116,9 @@ impl fmt::Display for BloomError {
             BloomError::InvalidTighteningRatio(r) => {
                 write!(f, "tightening ratio must be in (0, 1), got {r}")
             }
+            BloomError::CapacityExceeded => {
+                write!(f, "cuckoo filter is full — insert failed after maximum evictions")
+            }
         }
     }
 }