apache_datasketches/theta/
compact.rs

1use crate::error::SketchError;
2use apache_datasketches_sys::theta_compact::ffi as sys;
3use cxx::UniquePtr;
4
5/// An immutable, serializable snapshot of a theta sketch. Produced by
6/// [`super::ThetaSketch::compact`], by any set operation's result
7/// (`ThetaUnion::get_result`, `ThetaIntersection::get_result`,
8/// `ThetaAnotB::compute`), or by [`Self::deserialize`].
9pub struct CompactThetaSketch {
10    pub(crate) inner: UniquePtr<sys::CompactThetaSketchShim>,
11}
12
13unsafe impl Send for CompactThetaSketch {}
14
15impl CompactThetaSketch {
16    pub(crate) fn from_shim(inner: UniquePtr<sys::CompactThetaSketchShim>) -> Self {
17        Self { inner }
18    }
19
20    /// Deserializes v1/v2/v3 (uncompressed) bytes. Upstream's `deserialize()`
21    /// auto-detects the serial version transparently, including v4
22    /// (compressed) — see [`Self::deserialize_compressed`], which calls the
23    /// exact same underlying routine; the two Rust names exist purely for
24    /// call-site symmetry with `serialize_compact`/`serialize_compressed`.
25    pub fn deserialize(bytes: &[u8]) -> Result<Self, SketchError> {
26        let inner = sys::compact_theta_sketch_deserialize(bytes)
27            .map_err(|e| SketchError::Deserialization(e.what().to_string()))?;
28        Ok(Self { inner })
29    }
30
31    /// Deserializes v4 (compressed) bytes. See [`Self::deserialize`] — both
32    /// methods call the same upstream auto-detecting `deserialize()`.
33    pub fn deserialize_compressed(bytes: &[u8]) -> Result<Self, SketchError> {
34        Self::deserialize(bytes)
35    }
36
37    /// Returns the current estimate of the number of distinct items in this
38    /// sketch.
39    pub fn get_estimate(&self) -> f64 {
40        self.inner.get_estimate()
41    }
42
43    /// Returns the lower bound of the confidence interval around
44    /// [`Self::get_estimate`]. See
45    /// [`ThetaSketch::get_lower_bound`](super::ThetaSketch::get_lower_bound)
46    /// for the meaning of `num_std_dev`.
47    pub fn get_lower_bound(&self, num_std_dev: u8) -> Result<f64, SketchError> {
48        self.inner
49            .get_lower_bound(num_std_dev)
50            .map_err(|e| SketchError::InvalidConfig(e.what().to_string()))
51    }
52
53    /// Returns the upper bound of the confidence interval around
54    /// [`Self::get_estimate`]. See
55    /// [`ThetaSketch::get_lower_bound`](super::ThetaSketch::get_lower_bound)
56    /// for the meaning of `num_std_dev`.
57    pub fn get_upper_bound(&self, num_std_dev: u8) -> Result<f64, SketchError> {
58        self.inner
59            .get_upper_bound(num_std_dev)
60            .map_err(|e| SketchError::InvalidConfig(e.what().to_string()))
61    }
62
63    /// Returns `true` if this sketch represents an empty set.
64    pub fn is_empty(&self) -> bool {
65        self.inner.is_empty()
66    }
67
68    /// Returns `true` if this sketch's theta threshold is below `1.0`
69    /// (i.e. [`Self::get_estimate`] is a statistical estimate rather than
70    /// an exact count).
71    pub fn is_estimation_mode(&self) -> bool {
72        self.inner.is_estimation_mode()
73    }
74
75    /// Returns `true` if this sketch's retained entries are sorted by hash
76    /// value.
77    pub fn is_ordered(&self) -> bool {
78        self.inner.is_ordered()
79    }
80
81    /// Returns the current theta threshold (`1.0` if not in estimation
82    /// mode).
83    pub fn get_theta(&self) -> f64 {
84        self.inner.get_theta()
85    }
86
87    /// Returns the number of entries currently retained by this sketch.
88    pub fn get_num_retained(&self) -> u32 {
89        self.inner.get_num_retained()
90    }
91
92    /// Serializes in the v3 (uncompressed) format. Note: unlike the design
93    /// spec's initially-sketched signature, this takes no `ordered`
94    /// parameter — upstream's `compact_theta_sketch::serialize()` has none;
95    /// orderedness is fixed when this sketch was created (e.g. via
96    /// `ThetaSketch::compact(ordered)`).
97    pub fn serialize_compact(&self) -> Vec<u8> {
98        self.inner.serialize_compact()
99    }
100
101    /// Serializes in the v4 (compressed) format.
102    pub fn serialize_compressed(&self) -> Vec<u8> {
103        self.inner.serialize_compressed()
104    }
105}
apache_datasketches/theta/compact.rs

apache_datasketches/theta/
compact.rs
