feat: support theta and tuple a-not-b

datasketches/src/theta/a_not_b.rs

@@ -0,0 +1,95 @@
+// 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.
+
+//! Theta sketch set difference (`A and not B`).
+//!
+//! [`ThetaAnotB`] computes the set difference of two Theta sketches: the keys retained in `A`
+//! that are not present in `B`. The logic lives in the shared raw operator (`RawAnotB`) that also
+//! drives the Tuple a-not-B; Theta entries carry no summary, so nothing needs to be combined.
+
+use crate::error::Error;
+use crate::hash::DEFAULT_UPDATE_SEED;
+use crate::theta::CompactThetaSketch;
+use crate::theta::ThetaSketchView;
+use crate::thetacommon::a_not_b::RawAnotB;
+
+/// Set difference operator (`A and not B`) for Theta sketches.
+///
+/// This is a stateless operator (other than the seed): each call to [`compute`](Self::compute)
+/// takes two input sketches and returns a new [`CompactThetaSketch`].
+///
+/// # Examples
+///
+/// ```
+/// # use datasketches::theta::{ThetaAnotB, ThetaSketchBuilder};
+/// let mut a = ThetaSketchBuilder::default().build();
+/// a.update("apple");
+/// a.update("banana");
+///
+/// let mut b = ThetaSketchBuilder::default().build();
+/// b.update("banana");
+///
+/// let a_not_b = ThetaAnotB::new_with_default_seed();
+/// let result = a_not_b.compute(&a, &b, true).unwrap();
+/// assert_eq!(result.num_retained(), 1); // only "apple" survives
+/// ```
+#[derive(Debug, Clone, Copy)]
+pub struct ThetaAnotB {
+    raw: RawAnotB,
+}
+
+impl ThetaAnotB {
+    /// Creates a new set difference operator for the given `seed`.
+    pub fn new(seed: u64) -> Self {
+        Self {
+            raw: RawAnotB::new(seed),
+        }
+    }
+
+    /// Creates a new set difference operator with the default seed.
+    pub fn new_with_default_seed() -> Self {
+        Self::new(DEFAULT_UPDATE_SEED)
+    }
+
+    /// Computes `a and not b`.
+    ///
+    /// The result retains every key of `a` (below the combined theta) that is not present in `b`.
+    /// If `ordered` is true, the retained entries are sorted ascending by hash.
+    ///
+    /// # Errors
+    ///
+    /// Returns an error if either non-trivial input has a seed hash that differs from this
+    /// operator's seed.
+    pub fn compute<A, B>(&self, a: &A, b: &B, ordered: bool) -> Result<CompactThetaSketch, Error>
+    where
+        A: ThetaSketchView,
+        B: ThetaSketchView,
+    {
+        let parts = self.raw.compute(a, b, ordered)?;
+        Ok(CompactThetaSketch::from_parts(
+            parts
+                .entries
+                .into_iter()
+                .map(|entry| entry.hash())
+                .collect(),
+            parts.theta,
+            parts.seed_hash,
+            parts.ordered,
+            parts.empty,
+        ))
+    }
+}

datasketches/src/theta/mod.rs

@@ -39,13 +39,15 @@
 //! assert!(sketch.estimate() >= 1.0);
 //! ```
 
+mod a_not_b;
 mod bit_pack;
 mod hash_table;
 mod intersection;
 mod serialization;
 mod sketch;
 mod union;
 
+pub use self::a_not_b::ThetaAnotB;
 pub use self::hash_table::ThetaEntry;
 pub use self::intersection::ThetaIntersection;
 pub use self::sketch::CompactThetaSketch;

datasketches/src/thetacommon/a_not_b.rs

@@ -0,0 +1,184 @@
+// 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 std::collections::HashSet;
+
+use crate::error::Error;
+use crate::hash::compute_seed_hash;
+use crate::thetacommon::RawHashTableEntry;
+use crate::thetacommon::RawThetaSketchView;
+use crate::thetacommon::constants::MAX_THETA;
+use crate::thetacommon::hash_table::RawCompactParts;
+
+/// Stateless set difference (`A and not B`) operator shared by Theta and Tuple sketches.
+///
+/// `E` is the retained entry type. Ordinary Theta entries only contain a hash, while tuple
+/// entries also carry a summary. Surviving entries are moved from `A` unchanged, so unlike the
+/// union and intersection this operation needs no entry-merge policy.
+#[derive(Debug, Clone, Copy)]
+pub struct RawAnotB {
+    seed_hash: u16,
+}
+
+impl RawAnotB {
+    /// Creates a new set difference operator for the given `seed`.
+    pub fn new(seed: u64) -> Self {
+        Self {
+            seed_hash: compute_seed_hash(seed),
+        }
+    }
+
+    /// Computes `a and not b`.
+    ///
+    /// The result retains every entry of `a` (below the combined theta) whose hash is not present
+    /// in `b`. If `ordered` is true, the retained entries are sorted ascending by hash.
+    ///
+    /// # Errors
+    ///
+    /// Returns an error if either non-trivial input has a seed hash that differs from this
+    /// operator's seed.
+    pub fn compute<E, A, B>(&self, a: &A, b: &B, ordered: bool) -> Result<RawCompactParts<E>, Error>
+    where
+        E: RawHashTableEntry,
+        A: RawThetaSketchView<E>,
+        B: RawThetaSketchView<E>,
+    {
+        // If A is empty the result is an (empty) copy of A. As with the union and intersection, an
+        // empty input carries no keys, so its seed is not validated.
+        if a.is_empty() {
+            return Ok(Self::parts_from_view(a, ordered));
+        }
+
+        // A is non-empty, so its seed must be compatible.
+        if a.seed_hash() != self.seed_hash {
+            return Err(Error::invalid_argument(format!(
+                "A seed hash mismatch: expected {}, got {}",
+                self.seed_hash,
+                a.seed_hash()
+            )));
+        }
+
+        // An empty B subtracts nothing, so the result is simply a copy of A. This also covers the
+        // "A is non-empty but has no retained keys" state: B's seed and theta must not influence
+        // the result, so we return before touching them.
+        if b.is_empty() {
+            return Ok(Self::parts_from_view(a, ordered));
+        }
+
+        // B is non-empty, so its seed must be compatible.
+        if b.seed_hash() != self.seed_hash {
+            return Err(Error::invalid_argument(format!(
+                "B seed hash mismatch: expected {}, got {}",
+                self.seed_hash,
+                b.seed_hash()
+            )));
+        }
+
+        let theta = a.theta().min(b.theta());
+        // A is non-empty here; the result only becomes empty if everything is subtracted in exact
+        // mode (handled below).
+        let mut is_empty = false;
+
+        let entries: Vec<E> = if b.num_retained() == 0 {
+            a.iter().filter(|entry| entry.hash() < theta).collect()
+        } else if a.is_ordered() && b.is_ordered() {
+            // Both inputs are sorted ascending by hash: merge-scan without a hash set. Only
+            // b hashes below theta can exclude an a entry (a entries are all < theta), so
+            // unexamined b entries at or above theta are harmless.
+            let mut b_hashes = b.iter().map(|entry| entry.hash()).peekable();
+            let mut entries = Vec::new();
+            for entry in a.iter() {
+                let hash = entry.hash();
+                if hash >= theta {
+                    break;
+                }
+                while let Some(&b_hash) = b_hashes.peek() {
+                    if b_hash < hash {
+                        b_hashes.next();
+                    } else {
+                        break;
+                    }
+                }
+                if b_hashes.peek() != Some(&hash) {
+                    entries.push(entry);
+                }
+            }
+            entries
+        } else {
+            let mut b_keys: HashSet<u64> = HashSet::with_capacity(b.num_retained());
+            for entry in b.iter() {
+                let hash = entry.hash();
+                if hash < theta {
+                    b_keys.insert(hash);
+                } else if b.is_ordered() {
+                    break;
+                }
+            }
+
+            let mut entries = Vec::new();
+            for entry in a.iter() {
+                let hash = entry.hash();
+                if hash < theta {
+                    if !b_keys.contains(&hash) {
+                        entries.push(entry);
+                    }
+                } else if a.is_ordered() {
+                    break;
+                }
+            }
+            entries
+        };
+
+        if entries.is_empty() && theta == MAX_THETA {
+            is_empty = true;
+        }
+
+        let out_ordered = ordered || a.is_ordered();
+        let mut entries = entries;
+        if ordered && !a.is_ordered() && entries.len() > 1 {
+            entries.sort_unstable_by_key(RawHashTableEntry::hash);
+        }
+
+        Ok(RawCompactParts {
+            entries,
+            theta,
+            seed_hash: self.seed_hash,
+            ordered: out_ordered,
+            empty: is_empty,
+        })
+    }
+
+    /// Builds compact parts that are a copy of the view `a`.
+    fn parts_from_view<E, V>(a: &V, ordered: bool) -> RawCompactParts<E>
+    where
+        E: RawHashTableEntry,
+        V: RawThetaSketchView<E>,
+    {
+        let mut entries: Vec<E> = a.iter().collect();
+        let out_ordered = ordered || a.is_ordered();
+        if ordered && !a.is_ordered() && entries.len() > 1 {
+            entries.sort_unstable_by_key(RawHashTableEntry::hash);
+        }
+        RawCompactParts {
+            entries,
+            theta: a.theta(),
+            seed_hash: a.seed_hash(),
+            ordered: out_ordered,
+            empty: a.is_empty(),
+        }
+    }
+}

datasketches/src/thetacommon/mod.rs

@@ -17,6 +17,7 @@
 
 //! Data structures and functions that may be used across all the Theta sketch family.
 
+pub(crate) mod a_not_b;
 pub(crate) mod binomial_bounds;
 pub(crate) mod constants;
 pub(crate) mod hash_table;