feat: add xor filter

CHANGELOG.md

@@ -4,6 +4,10 @@ All significant changes to this project will be documented in this file.
 
 ## Unreleased
 
+### New features
+
+* Add immutable xor filters behind the `xor` feature, with 8- and 16-bit fingerprints, pre-hashed input APIs, and compatible serialization.
+
 ## v0.4.0 (2026-08-18)
 
 ### Breaking changes

README.md

@@ -73,6 +73,7 @@ Enable multiple algorithms by listing their features together, such as `features
 | `tdigest` | `TDigestMut`, `TDigest` | Quantile and rank estimation, with high accuracy near distribution tails. |
 | `theta` | `ThetaSketch` and set operations | Distinct counts, set expressions, and Jaccard similarity. |
 | `tuple` | `TupleSketch` and set operations | Theta-style keys with user-defined summaries attached to retained entries. |
+| `xor` | `XorFilter`, `XorFilterBuilder` | Compact immutable probabilistic set membership with 8- or 16-bit fingerprints. |
 
 See the [API documentation](https://docs.rs/datasketches) for configuration, accuracy guarantees, serialization, and examples for each algorithm.
 

datasketches/Cargo.toml

@@ -46,6 +46,7 @@ hll = []
 tdigest = []
 theta = []
 tuple = []
+xor = []
 
 [[test]]
 name = "bloom_test"
@@ -87,6 +88,11 @@ name = "tuple_test"
 path = "tests/tuple_test/main.rs"
 required-features = ["tuple"]
 
+[[test]]
+name = "xor_test"
+path = "tests/xor_test/main.rs"
+required-features = ["xor"]
+
 [dev-dependencies]
 googletest = { workspace = true }
 insta = { workspace = true }

datasketches/src/codec/family.rs

@@ -106,6 +106,15 @@ impl Family {
         min_pre_longs: 3,
         max_pre_longs: 4,
     };
+
+    /// Xor filter for probabilistic set membership.
+    #[cfg(feature = "xor")]
+    pub const XORFILTER: Family = Family {
+        id: 22,
+        name: "XORFILTER",
+        min_pre_longs: 3,
+        max_pre_longs: 3,
+    };
 }
 
 impl Family {

datasketches/src/codec/mod.rs

@@ -31,6 +31,7 @@ pub use self::encode::SketchBytes;
     feature = "tdigest",
     feature = "theta",
     feature = "tuple",
+    feature = "xor",
 ))]
 #[allow(dead_code)] // some utilities are only used for certain sketches
 pub(crate) mod assert;
@@ -44,5 +45,6 @@ pub(crate) mod assert;
     feature = "tdigest",
     feature = "theta",
     feature = "tuple",
+    feature = "xor",
 ))]
 pub(crate) mod family;

datasketches/src/hash/mod.rs

@@ -38,9 +38,9 @@ mod murmurhash;
 ))]
 pub(crate) use self::murmurhash::*;
 
-#[cfg(feature = "bloom")]
+#[cfg(any(feature = "bloom", feature = "xor"))]
 mod xxhash;
-#[cfg(feature = "bloom")]
+#[cfg(any(feature = "bloom", feature = "xor"))]
 pub(crate) use self::xxhash::*;
 
 #[cfg(any(
@@ -95,6 +95,7 @@ pub(crate) const DEFAULT_UPDATE_SEED: u64 = 9001;
     feature = "hll",
     feature = "theta",
     feature = "tuple",
+    feature = "xor",
 ))]
 fn read_u64_le(bytes: &[u8]) -> u64 {
     let mut buf = [0u8; 8];

datasketches/src/lib.rs

@@ -51,6 +51,8 @@ pub use self::thetafamily::common as thetacommon;
 pub use self::thetafamily::theta;
 #[cfg(feature = "tuple")]
 pub use self::thetafamily::tuple;
+#[cfg(feature = "xor")]
+pub mod xor;
 
 // common modules
 pub mod codec;