Merge branch 'main' into refine_theta_sketch

Author: tisonkun

CHANGELOG.md

@@ -13,7 +13,9 @@ All significant changes to this project will be documented in this file.
 
 * `CountMinSketch` with unsigned values now supports `halve` and `decay` operations.
 * `CpcSketch` and `CpcUnion` are now available for cardinality estimation.
-* `FrequentItemsSketch` now supports serde for `u64` value.
+* `CpcWrapper` is now available for reading estimation from a serialized CpcSketch without full deserialization.
+* `FrequentItemsSketch` now supports serde for any value implement `FrequentItemValue` (builtin supports for `i64`, `u64`, and `String`).
+* Expose `codec::SketchBytes`, `codec::SketchSlice`, and `FrequentItemValue` as public API.
 
 ## v0.2.0 (2026-01-14)
 

datasketches/src/bloom/builder.rs

@@ -22,9 +22,9 @@ use crate::hash::DEFAULT_UPDATE_SEED;
 /// Builder for creating [`BloomFilter`] instances.
 ///
 /// Provides two construction modes:
-/// - [`with_accuracy()`](Self::with_accuracy): Specify target items and false positive rate
+/// * [`with_accuracy()`](Self::with_accuracy): Specify target items and false positive rate
 ///   (recommended)
-/// - [`with_size()`](Self::with_size): Specify requested bit count and hash functions (manual)
+/// * [`with_size()`](Self::with_size): Specify requested bit count and hash functions (manual)
 #[derive(Debug, Clone)]
 pub struct BloomFilterBuilder {
     num_bits: u64,
@@ -52,8 +52,8 @@ impl BloomFilterBuilder {
     ///
     /// # Arguments
     ///
-    /// - `max_items`: Maximum expected number of distinct items
-    /// - `fpp`: Target false positive probability (e.g., 0.01 for 1%)
+    /// * `max_items`: Maximum expected number of distinct items
+    /// * `fpp`: Target false positive probability (e.g., 0.01 for 1%)
     ///
     /// # Panics
     ///
@@ -95,14 +95,14 @@ impl BloomFilterBuilder {
     ///
     /// # Arguments
     ///
-    /// - `num_bits`: Total number of bits in the filter
-    /// - `num_hashes`: Number of hash functions to use
+    /// * `num_bits`: Total number of bits in the filter
+    /// * `num_hashes`: Number of hash functions to use
     ///
     /// # Panics
     ///
     /// Panics if any of:
-    /// - `num_bits` < [`Self::MIN_NUM_BITS`] or `num_bits` > [`Self::MAX_NUM_BITS`]
-    /// - `num_hashes` < [`Self::MIN_NUM_HASHES`] or `num_hashes` > [`Self::MIN_NUM_HASHES`]
+    /// * `num_bits` < [`Self::MIN_NUM_BITS`] or `num_bits` > [`Self::MAX_NUM_BITS`]
+    /// * `num_hashes` < [`Self::MIN_NUM_HASHES`] or `num_hashes` > [`Self::MAX_NUM_HASHES`]
     ///
     /// # Examples
     ///

datasketches/src/bloom/mod.rs

@@ -23,14 +23,14 @@
 //!
 //! # Properties
 //!
-//! - **No false negatives**: If an item was inserted, `contains()` will always return `true`
-//! - **Possible false positives**: `contains()` may return `true` for items never inserted
-//! - **Fixed size**: Unlike typical sketches, Bloom filters do not resize automatically
-//! - **Linear space**: Size is proportional to the expected number of distinct items
+//! * **No false negatives**: If an item was inserted, `contains()` will always return `true`
+//! * **Possible false positives**: `contains()` may return `true` for items never inserted
+//! * **Fixed size**: Unlike typical sketches, Bloom filters do not resize automatically
+//! * **Linear space**: Size is proportional to the expected number of distinct items
 //!
 //! # Usage
 //!
-//! ```rust
+//! ```
 //! use datasketches::bloom::BloomFilter;
 //! use datasketches::bloom::BloomFilterBuilder;
 //!
@@ -60,7 +60,7 @@
 //!
 //! Automatically calculates optimal size and hash functions:
 //!
-//! ```rust
+//! ```
 //! # use datasketches::bloom::BloomFilterBuilder;
 //! let filter = BloomFilterBuilder::with_accuracy(
 //!     10_000, // Expected max items
@@ -74,7 +74,7 @@
 //!
 //! Specify requested bit count and hash functions (rounded up to a multiple of 64 bits):
 //!
-//! ```rust
+//! ```
 //! # use datasketches::bloom::BloomFilterBuilder;
 //! let filter = BloomFilterBuilder::with_size(
 //!     95_851, // Number of bits
@@ -87,7 +87,7 @@
 //!
 //! Bloom filters support efficient set operations:
 //!
-//! ```rust
+//! ```
 //! # use datasketches::bloom::BloomFilterBuilder;
 //! let mut filter1 = BloomFilterBuilder::with_accuracy(100, 0.01).build();
 //! let mut filter2 = BloomFilterBuilder::with_accuracy(100, 0.01).build();
@@ -109,15 +109,15 @@
 //!
 //! # Implementation Details
 //!
-//! - Uses XXHash64 for hashing
-//! - Implements double hashing (Kirsch-Mitzenmacher method) for k hash functions
-//! - Bits packed efficiently in `u64` words
-//! - Compatible serialization format (family ID: 21)
+//! * Uses XXHash64 for hashing
+//! * Implements double hashing (Kirsch-Mitzenmacher method) for k hash functions
+//! * Bits packed efficiently in `u64` words
+//! * Compatible serialization format (family ID: 21)
 //!
 //! # References
 //!
-//! - Bloom, Burton H. (1970). "Space/time trade-offs in hash coding with allowable errors"
-//! - Kirsch and Mitzenmacher (2008). "Less Hashing, Same Performance: Building a Better Bloom
+//! * Bloom, Burton H. (1970). "Space/time trade-offs in hash coding with allowable errors"
+//! * Kirsch and Mitzenmacher (2008). "Less Hashing, Same Performance: Building a Better Bloom
 //!   Filter"
 
 mod builder;

datasketches/src/bloom/sketch.rs

@@ -20,9 +20,10 @@ use std::hash::Hasher;
 
 use crate::codec::SketchBytes;
 use crate::codec::SketchSlice;
+use crate::codec::assert::ensure_preamble_longs_in_range;
+use crate::codec::assert::ensure_serial_version_is;
+use crate::codec::assert::insufficient_data;
 use crate::codec::family::Family;
-use crate::codec::utility::ensure_preamble_longs_in_range;
-use crate::codec::utility::ensure_serial_version_is;
 use crate::error::Error;
 use crate::hash::XxHash64;
 
@@ -33,9 +34,9 @@ const EMPTY_FLAG_MASK: u8 = 1 << 2;
 /// A Bloom filter for probabilistic set membership testing.
 ///
 /// Provides fast membership queries with:
-/// - No false negatives (inserted items always return `true`)
-/// - Tunable false positive rate
-/// - Constant space usage
+/// * No false negatives (inserted items always return `true`)
+/// * Tunable false positive rate
+/// * Constant space usage
 ///
 /// Use [`super::BloomFilterBuilder`] to construct instances.
 #[derive(Debug, Clone, PartialEq)]
@@ -54,8 +55,8 @@ impl BloomFilter {
     /// Tests whether an item is possibly in the set.
     ///
     /// Returns:
-    /// - `true`: Item was **possibly** inserted (or false positive)
-    /// - `false`: Item was **definitely not** inserted
+    /// * `true`: Item was **possibly** inserted (or false positive)
+    /// * `false`: Item was **definitely not** inserted
     ///
     /// # Examples
     ///
@@ -290,8 +291,8 @@ impl BloomFilter {
     ///
     /// Uses the approximation: `load_factor^k`
     /// where:
-    /// - load_factor = fraction of bits set (bits_used / capacity)
-    /// - k = num_hashes
+    /// * load_factor = fraction of bits set (bits_used / capacity)
+    /// * k = num_hashes
     ///
     /// This assumes uniform bit distribution and is more accurate than
     /// trying to estimate insertion count from the load factor.
@@ -307,9 +308,9 @@ impl BloomFilter {
     /// Checks if two filters are compatible for merging.
     ///
     /// Filters are compatible if they have the same:
-    /// - Capacity (number of bits)
-    /// - Number of hash functions
-    /// - Seed
+    /// * Capacity (number of bits)
+    /// * Number of hash functions
+    /// * Seed
     pub fn is_compatible(&self, other: &Self) -> bool {
         self.bit_array.len() == other.bit_array.len()
             && self.num_hashes == other.num_hashes
@@ -379,9 +380,9 @@ impl BloomFilter {
     /// # Errors
     ///
     /// Returns an error if:
-    /// - The data is truncated or corrupted
-    /// - The family ID doesn't match (not a Bloom filter)
-    /// - The serial version is unsupported
+    /// * The data is truncated or corrupted
+    /// * The family ID doesn't match (not a Bloom filter)
+    /// * The serial version is unsupported
     ///
     /// # Examples
     ///
@@ -399,18 +400,14 @@ impl BloomFilter {
         // Read preamble
         let preamble_longs = cursor
             .read_u8()
-            .map_err(|_| Error::insufficient_data("preamble_longs"))?;
+            .map_err(insufficient_data("preamble_longs"))?;
         let serial_version = cursor
             .read_u8()
-            .map_err(|_| Error::insufficient_data("serial_version"))?;
-        let family_id = cursor
-            .read_u8()
-            .map_err(|_| Error::insufficient_data("family_id"))?;
+            .map_err(insufficient_data("serial_version"))?;
+        let family_id = cursor.read_u8().map_err(insufficient_data("family_id"))?;
 
         // Byte 3: flags byte (directly after family_id)
-        let flags = cursor
-            .read_u8()
-            .map_err(|_| Error::insufficient_data("flags"))?;
+        let flags = cursor.read_u8().map_err(insufficient_data("flags"))?;
 
         // Validate
         Family::BLOOMFILTER.validate_id(family_id)?;
@@ -425,7 +422,7 @@ impl BloomFilter {
         // Bytes 4-5: num_hashes (u16)
         let num_hashes = cursor
             .read_u16_le()
-            .map_err(|_| Error::insufficient_data("num_hashes"))?;
+            .map_err(insufficient_data("num_hashes"))?;
         if num_hashes == 0 || num_hashes > i16::MAX as u16 {
             return Err(Error::deserial(format!(
                 "invalid num_hashes: expected [1, {}], got {}",
@@ -436,18 +433,14 @@ impl BloomFilter {
         // Bytes 6-7: unused (u16)
         let _unused = cursor
             .read_u16_le()
-            .map_err(|_| Error::insufficient_data("unused_header"))?;
-        let seed = cursor
-            .read_u64_le()
-            .map_err(|_| Error::insufficient_data("seed"))?;
+            .map_err(insufficient_data("unused_header"))?;
+        let seed = cursor.read_u64_le().map_err(insufficient_data("seed"))?;
 
         // Bit array capacity is stored as number of 64-bit words (int32) + unused padding (uint32).
         let num_longs = cursor
             .read_i32_le()
-            .map_err(|_| Error::insufficient_data("num_longs"))?;
-        let _unused = cursor
-            .read_u32_le()
-            .map_err(|_| Error::insufficient_data("unused"))?;
+            .map_err(insufficient_data("num_longs"))?;
+        let _unused = cursor.read_u32_le().map_err(insufficient_data("unused"))?;
 
         if num_longs <= 0 {
             return Err(Error::deserial(format!(
@@ -465,12 +458,12 @@ impl BloomFilter {
         } else {
             let raw_num_bits_set = cursor
                 .read_u64_le()
-                .map_err(|_| Error::insufficient_data("num_bits_set"))?;
+                .map_err(insufficient_data("num_bits_set"))?;
 
             for word in &mut bit_array {
                 *word = cursor
                     .read_u64_le()
-                    .map_err(|_| Error::insufficient_data("bit_array"))?;
+                    .map_err(insufficient_data("bit_array"))?;
             }
 
             // Handle "dirty" state: 0xFFFFFFFFFFFFFFFF indicates bits need recounting
@@ -501,8 +494,8 @@ impl BloomFilter {
     /// Computes the two base hash values using XXHash64.
     ///
     /// Uses a two-hash approach:
-    /// - h0 = XXHash64(item, seed)
-    /// - h1 = XXHash64(item, h0)
+    /// * h0 = XXHash64(item, seed)
+    /// * h1 = XXHash64(item, h0)
     fn compute_hash<T: Hash>(&self, item: &T) -> (u64, u64) {
         // First hash with the configured seed
         let mut hasher = XxHash64::with_seed(self.seed);

datasketches/src/codec/utility.rs datasketches/src/codec/assert.rsdatasketches/src/codec/utility.rs renamed to datasketches/src/codec/assert.rs

@@ -20,6 +20,10 @@ use std::ops::RangeBounds;
 
 use crate::error::Error;
 
+pub(crate) fn insufficient_data(tag: &'static str) -> impl FnOnce(std::io::Error) -> Error {
+    move |_| Error::insufficient_data(tag)
+}
+
 pub(crate) fn ensure_serial_version_is(expected: u8, actual: u8) -> Result<(), Error> {
     if expected == actual {
         Ok(())

datasketches/src/codec/mod.rs

@@ -24,5 +24,5 @@ pub use self::decode::SketchSlice;
 pub use self::encode::SketchBytes;
 
 // private to datasketches crate
+pub(crate) mod assert;
 pub(crate) mod family;
-pub(crate) mod utility;