feat: add tuple theta implementation and tests based on raw hashtable

datasketches/Cargo.toml

@@ -45,6 +45,7 @@ frequencies = []
 hll = []
 tdigest = []
 theta = []
+tuple = ["theta"]
 
 [dev-dependencies]
 googletest = { workspace = true }

datasketches/src/codec/decode.rs

@@ -38,6 +38,16 @@ impl SketchSlice<'_> {
         self.slice.set_position(pos + n);
     }
 
+    /// Returns the not-yet-read portion of the underlying slice.
+    ///
+    /// Useful for handing the remaining bytes to a variable-length decoder that reports how many
+    /// bytes it consumed; pair it with [`advance`](Self::advance).
+    pub fn remaining(&self) -> &[u8] {
+        let buf = self.slice.get_ref();
+        let pos = (self.slice.position() as usize).min(buf.len());
+        &buf[pos..]
+    }
+
     /// Reads exactly `buf.len()` bytes from the slice into `buf`.
     pub fn read_exact(&mut self, buf: &mut [u8]) -> io::Result<()> {
         self.slice.read_exact(buf)

datasketches/src/codec/family.rs

@@ -53,6 +53,15 @@ impl Family {
         max_pre_longs: 1,
     };
 
+    /// Tuple Sketch for cardinality estimation with per-key summaries.
+    #[cfg(feature = "tuple")]
+    pub const TUPLE: Family = Family {
+        id: 9,
+        name: "TUPLE",
+        min_pre_longs: 1,
+        max_pre_longs: 3,
+    };
+
     /// The Frequency family of sketches.
     #[cfg(feature = "frequencies")]
     pub const FREQUENCY: Family = Family {

datasketches/src/lib.rs

@@ -45,6 +45,8 @@ pub mod hll;
 pub mod tdigest;
 #[cfg(feature = "theta")]
 pub mod theta;
+#[cfg(feature = "tuple")]
+pub mod tuple;
 
 // common modules
 pub mod codec;

datasketches/src/theta/intersection.rs

@@ -113,6 +113,9 @@ impl ThetaIntersection {
                 sketch.num_retained(),
                 HASH_TABLE_REBUILD_THRESHOLD,
             );
+            // num_retained >= 1 here (the zero case returned early above), so lg_size >= 1 and
+            // lg_size - 1 below cannot underflow.
+            debug_assert!(lg_size >= 1);
             self.table = ThetaHashTable::from_raw_parts(
                 lg_size,
                 lg_size - 1,
@@ -174,6 +177,9 @@ impl ThetaIntersection {
                     matched_entries.len(),
                     HASH_TABLE_REBUILD_THRESHOLD,
                 );
+                // matched_entries is non-empty here (the empty case is handled above), so
+                // lg_size >= 1 and lg_size - 1 below cannot underflow.
+                debug_assert!(lg_size >= 1);
                 self.table = ThetaHashTable::from_raw_parts(
                     lg_size,
                     lg_size - 1,

datasketches/src/theta/mod.rs

@@ -46,7 +46,17 @@ mod raw_hash_table;
 mod serialization;
 mod sketch;
 
+// These helpers are re-exported only for Tuple hash-table tests; production code uses the shared
+// raw table directly.
+#[cfg(all(feature = "tuple", test))]
+pub(crate) use self::hash_table::starting_sub_multiple;
+#[cfg(all(feature = "tuple", test))]
+pub(crate) use self::hash_table::starting_theta_from_sampling_probability;
 pub use self::intersection::ThetaIntersection;
+#[cfg(feature = "tuple")]
+pub(crate) use self::raw_hash_table::RawHashTable;
+#[cfg(feature = "tuple")]
+pub(crate) use self::raw_hash_table::RawHashTableEntry;
 pub use self::sketch::CompactThetaSketch;
 pub use self::sketch::ThetaSketch;
 pub use self::sketch::ThetaSketchBuilder;