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