feat: impl CpcWrapper

CHANGELOG.md

@@ -13,6 +13,7 @@ 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.
+* `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.
 

datasketches/src/cpc/estimator.rs

@@ -88,7 +88,43 @@ static HIP_HIGH_SIDE_DATA: [u16; 33] = [
     5880, 5914, 5953, // 14 1000297
 ];
 
-pub(super) fn icon_confidence_lb(lg_k: u8, num_coupons: u32, kappa: NumStdDev) -> f64 {
+pub(super) fn estimate(merge_flag: bool, hip_est_accum: f64, lg_k: u8, num_coupons: u32) -> f64 {
+    if !merge_flag {
+        hip_est_accum
+    } else {
+        icon_estimate(lg_k, num_coupons)
+    }
+}
+
+pub(super) fn lower_bound(
+    merge_flag: bool,
+    hip_est_accum: f64,
+    lg_k: u8,
+    num_coupons: u32,
+    kappa: NumStdDev,
+) -> f64 {
+    if !merge_flag {
+        hip_confidence_lb(lg_k, num_coupons, hip_est_accum, kappa)
+    } else {
+        icon_confidence_lb(lg_k, num_coupons, kappa)
+    }
+}
+
+pub(super) fn upper_bound(
+    merge_flag: bool,
+    hip_est_accum: f64,
+    lg_k: u8,
+    num_coupons: u32,
+    kappa: NumStdDev,
+) -> f64 {
+    if !merge_flag {
+        hip_confidence_ub(lg_k, num_coupons, hip_est_accum, kappa)
+    } else {
+        icon_confidence_ub(lg_k, num_coupons, kappa)
+    }
+}
+
+fn icon_confidence_lb(lg_k: u8, num_coupons: u32, kappa: NumStdDev) -> f64 {
     if num_coupons == 0 {
         return 0.0;
     }
@@ -112,7 +148,7 @@ pub(super) fn icon_confidence_lb(lg_k: u8, num_coupons: u32, kappa: NumStdDev) -
     }
 }
 
-pub(super) fn icon_confidence_ub(lg_k: u8, num_coupons: u32, kappa: NumStdDev) -> f64 {
+fn icon_confidence_ub(lg_k: u8, num_coupons: u32, kappa: NumStdDev) -> f64 {
     if num_coupons == 0 {
         return 0.0;
     }
@@ -132,12 +168,7 @@ pub(super) fn icon_confidence_ub(lg_k: u8, num_coupons: u32, kappa: NumStdDev) -
     result.ceil() // slight widening of interval to be conservative
 }
 
-pub(super) fn hip_confidence_lb(
-    lg_k: u8,
-    num_coupons: u32,
-    hip_est_accum: f64,
-    kappa: NumStdDev,
-) -> f64 {
+fn hip_confidence_lb(lg_k: u8, num_coupons: u32, hip_est_accum: f64, kappa: NumStdDev) -> f64 {
     if num_coupons == 0 {
         return 0.0;
     }
@@ -160,12 +191,7 @@ pub(super) fn hip_confidence_lb(
     }
 }
 
-pub(super) fn hip_confidence_ub(
-    lg_k: u8,
-    num_coupons: u32,
-    hip_est_accum: f64,
-    kappa: NumStdDev,
-) -> f64 {
+fn hip_confidence_ub(lg_k: u8, num_coupons: u32, hip_est_accum: f64, kappa: NumStdDev) -> f64 {
     if num_coupons == 0 {
         return 0.0;
     }
@@ -362,7 +388,7 @@ fn icon_exponential_approximation(k: f64, c: f64) -> f64 {
     0.7940236163830469 * k * 2f64.powf(c / k)
 }
 
-pub(super) fn icon_estimate(lg_k: u8, num_coupons: u32) -> f64 {
+fn icon_estimate(lg_k: u8, num_coupons: u32) -> f64 {
     let lg_k = lg_k as usize;
     assert!(
         (ICON_MIN_LOG_K..=ICON_MAX_LOG_K).contains(&lg_k),

datasketches/src/cpc/mod.rs

@@ -40,11 +40,14 @@ mod compression_data;
 mod estimator;
 mod kxp_byte_lookup;
 mod pair_table;
+mod serialization;
 mod sketch;
 mod union;
+mod wrapper;
 
 pub use self::sketch::CpcSketch;
 pub use self::union::CpcUnion;
+pub use self::wrapper::CpcWrapper;
 
 /// Default log2 of K.
 const DEFAULT_LG_K: u8 = 11;

datasketches/src/cpc/serialization.rs

@@ -0,0 +1,48 @@
+// 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.
+
+pub(super) const SERIAL_VERSION: u8 = 1;
+pub(super) const FLAG_COMPRESSED: u8 = 1;
+pub(super) const FLAG_HAS_HIP: u8 = 2;
+pub(super) const FLAG_HAS_TABLE: u8 = 3;
+pub(super) const FLAG_HAS_WINDOW: u8 = 4;
+
+pub(super) fn make_preamble_ints(
+    num_coupons: u32,
+    has_hip: bool,
+    has_table: bool,
+    has_window: bool,
+) -> u8 {
+    let mut preamble_ints = 2;
+    if num_coupons > 0 {
+        preamble_ints += 1; // number of coupons
+        if has_hip {
+            preamble_ints += 4; // HIP
+        }
+        if has_table {
+            preamble_ints += 1; // table data length
+            // number of values (if there is no window it is the same as number of coupons)
+            if has_window {
+                preamble_ints += 1;
+            }
+        }
+        if has_window {
+            preamble_ints += 1; // window length
+        }
+    }
+    preamble_ints
+}

datasketches/src/cpc/sketch.rs

@@ -33,13 +33,17 @@ use crate::cpc::compression::CompressedState;
 use crate::cpc::count_bits_set_in_matrix;
 use crate::cpc::determine_correct_offset;
 use crate::cpc::determine_flavor;
-use crate::cpc::estimator::hip_confidence_lb;
-use crate::cpc::estimator::hip_confidence_ub;
-use crate::cpc::estimator::icon_confidence_lb;
-use crate::cpc::estimator::icon_confidence_ub;
-use crate::cpc::estimator::icon_estimate;
+use crate::cpc::estimator::estimate;
+use crate::cpc::estimator::lower_bound;
+use crate::cpc::estimator::upper_bound;
 use crate::cpc::kxp_byte_lookup::KXP_BYTE_TABLE;
 use crate::cpc::pair_table::PairTable;
+use crate::cpc::serialization::FLAG_COMPRESSED;
+use crate::cpc::serialization::FLAG_HAS_HIP;
+use crate::cpc::serialization::FLAG_HAS_TABLE;
+use crate::cpc::serialization::FLAG_HAS_WINDOW;
+use crate::cpc::serialization::SERIAL_VERSION;
+use crate::cpc::serialization::make_preamble_ints;
 use crate::error::Error;
 use crate::error::ErrorKind;
 use crate::hash::DEFAULT_UPDATE_SEED;
@@ -130,29 +134,34 @@ impl CpcSketch {
 
     /// Returns the best estimate of the cardinality of the sketch.
     pub fn estimate(&self) -> f64 {
-        if !self.merge_flag {
-            self.hip_est_accum
-        } else {
-            icon_estimate(self.lg_k, self.num_coupons)
-        }
+        estimate(
+            self.merge_flag,
+            self.hip_est_accum,
+            self.lg_k,
+            self.num_coupons,
+        )
     }
 
     /// Returns the best estimate of the lower bound of the confidence interval given `kappa`.
     pub fn lower_bound(&self, kappa: NumStdDev) -> f64 {
-        if !self.merge_flag {
-            hip_confidence_lb(self.lg_k, self.num_coupons, self.hip_est_accum, kappa)
-        } else {
-            icon_confidence_lb(self.lg_k, self.num_coupons, kappa)
-        }
+        lower_bound(
+            self.merge_flag,
+            self.hip_est_accum,
+            self.lg_k,
+            self.num_coupons,
+            kappa,
+        )
     }
 
     /// Returns the best estimate of the upper bound of the confidence interval given `kappa`.
     pub fn upper_bound(&self, kappa: NumStdDev) -> f64 {
-        if !self.merge_flag {
-            hip_confidence_ub(self.lg_k, self.num_coupons, self.hip_est_accum, kappa)
-        } else {
-            icon_confidence_ub(self.lg_k, self.num_coupons, kappa)
-        }
+        upper_bound(
+            self.merge_flag,
+            self.hip_est_accum,
+            self.lg_k,
+            self.num_coupons,
+            kappa,
+        )
     }
 
     /// Returns true if the sketch is empty.
@@ -437,12 +446,6 @@ impl CpcSketch {
     }
 }
 
-const SERIAL_VERSION: u8 = 1;
-const FLAG_COMPRESSED: u8 = 1;
-const FLAG_HAS_HIP: u8 = 2;
-const FLAG_HAS_TABLE: u8 = 3;
-const FLAG_HAS_WINDOW: u8 = 4;
-
 impl CpcSketch {
     /// Serializes this CpcSketch to bytes.
     pub fn serialize(&self) -> Vec<u8> {
@@ -637,27 +640,6 @@ impl CpcSketch {
     }
 }
 
-fn make_preamble_ints(num_coupons: u32, has_hip: bool, has_table: bool, has_window: bool) -> u8 {
-    let mut preamble_ints = 2;
-    if num_coupons > 0 {
-        preamble_ints += 1; // number of coupons
-        if has_hip {
-            preamble_ints += 4; // HIP
-        }
-        if has_table {
-            preamble_ints += 1; // table data length
-            // number of values (if there is no window it is the same as number of coupons)
-            if has_window {
-                preamble_ints += 1;
-            }
-        }
-        if has_window {
-            preamble_ints += 1; // window length
-        }
-    }
-    preamble_ints
-}
-
 impl CpcSketch {
     /// Returns the estimated maximum compressed serialized size of a sketch.
     ///