feat: add xor filter

CHANGELOG.md

@@ -11,6 +11,7 @@ All significant changes to this project will be documented in this file.
 ### New features
 
 * Add KLL sketches behind the `kll` feature, with rank, quantile, PMF, and CDF queries, merging, totally ordered custom item types, a `KllFloat` adapter for non-NaN floating-point values, and serialization.
+* Add immutable xor filters behind the `xor` feature, with 8-, 16-, and 32-bit fingerprints, pre-hashed input APIs, and compatible serialization. Images with 32-bit fingerprints are a Rust-specific extension that other DataSketches implementations reject.
 
 ### Improvements
 

Cargo.toml

@@ -39,6 +39,7 @@ insta = { version = "1.48.0" }
 cargo_metadata = { version = "0.23.1" }
 quickcheck = { version = "1.1.0", default-features = false }
 rand = { version = "0.10.0" }
+xorf = { version = "0.12" }
 which = { version = "8.0.5" }
 flate2 = { version = "1.1.9", default-features = false, features = ["zlib-rs"] }
 tar = { version = "0.4.46", default-features = false }

README.md

@@ -74,6 +74,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-, 16-, or 32-bit fingerprints.           |
 
 See the [API documentation](https://docs.rs/datasketches) for configuration, accuracy guarantees, serialization, and examples for each algorithm.
 

benchmarks/Cargo.toml

@@ -34,9 +34,11 @@ datasketches = { workspace = true, features = [
   "tdigest",
   "theta",
   "tuple",
+  "xor",
 ] }
 divan = { workspace = true }
 rand = { workspace = true }
+xorf = { workspace = true }
 
 [[bench]]
 harness = false

benchmarks/main.rs

@@ -31,6 +31,7 @@ mod req;
 mod tdigest;
 mod theta;
 mod tuple;
+mod xor;
 
 fn main() {
     divan::main();

benchmarks/xor/build.rs

@@ -0,0 +1,72 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+use datasketches::xor::XorFilter;
+use datasketches::xor::XorFilterType;
+use divan::Bencher;
+use divan::black_box;
+use divan::counter::ItemsCount;
+
+use crate::hash_inputs::ITEMS;
+
+#[divan::bench]
+fn datasketches_xor8(bencher: Bencher) {
+    bencher.counter(ItemsCount::new(ITEMS)).bench_local(|| {
+        black_box(XorFilter::from_hashes(0..ITEMS as u64, XorFilterType::Xor8).unwrap())
+    });
+}
+
+#[divan::bench]
+fn datasketches_xor16(bencher: Bencher) {
+    bencher.counter(ItemsCount::new(ITEMS)).bench_local(|| {
+        black_box(XorFilter::from_hashes(0..ITEMS as u64, XorFilterType::Xor16).unwrap())
+    });
+}
+
+#[divan::bench]
+fn datasketches_xor32(bencher: Bencher) {
+    bencher.counter(ItemsCount::new(ITEMS)).bench_local(|| {
+        black_box(XorFilter::from_hashes(0..ITEMS as u64, XorFilterType::Xor32).unwrap())
+    });
+}
+
+#[divan::bench]
+fn xorf_xor8(bencher: Bencher) {
+    bencher.counter(ItemsCount::new(ITEMS)).bench_local(|| {
+        black_box(xorf::Xor8::from_iterator(
+            (0..ITEMS).map(|value| value as u64),
+        ))
+    });
+}
+
+#[divan::bench]
+fn xorf_xor16(bencher: Bencher) {
+    bencher.counter(ItemsCount::new(ITEMS)).bench_local(|| {
+        black_box(xorf::Xor16::from_iterator(
+            (0..ITEMS).map(|value| value as u64),
+        ))
+    });
+}
+
+#[divan::bench]
+fn xorf_xor32(bencher: Bencher) {
+    bencher.counter(ItemsCount::new(ITEMS)).bench_local(|| {
+        black_box(xorf::Xor32::from_iterator(
+            (0..ITEMS).map(|value| value as u64),
+        ))
+    });
+}

benchmarks/xor/mod.rs

@@ -0,0 +1,19 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+mod build;
+mod query;