apache_datasketches/tuple/
builder.rs

1use apache_datasketches_sys::array_of_doubles_sketch::ffi as sys;
2
3/// Controls how aggressively an ArrayOfDoubles sketch's internal hash table
4/// grows. Mirrors upstream's `datasketches::resize_factor`. Default is `X8`,
5/// matching `theta_constants::DEFAULT_RESIZE_FACTOR` (the tuple family
6/// inherits Theta's builder defaults).
7///
8/// This is a distinct type from the theta module's `ResizeFactor` with the
9/// same shape — the two sketch families are independently feature-gated and
10/// do not share types. (Deliberately not an intra-doc link: `theta` may not
11/// be compiled in.)
12#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
13pub enum ResizeFactor {
14    /// Grow by 1x (i.e. never resize past the initial allocation).
15    X1,
16    /// Grow by 2x each time the hash table fills.
17    X2,
18    /// Grow by 4x each time the hash table fills.
19    X4,
20    /// Grow by 8x each time the hash table fills. The default.
21    #[default]
22    X8,
23}
24
25impl From<ResizeFactor> for sys::TupleResizeFactor {
26    fn from(rf: ResizeFactor) -> Self {
27        match rf {
28            ResizeFactor::X1 => sys::TupleResizeFactor::X1,
29            ResizeFactor::X2 => sys::TupleResizeFactor::X2,
30            ResizeFactor::X4 => sys::TupleResizeFactor::X4,
31            ResizeFactor::X8 => sys::TupleResizeFactor::X8,
32        }
33    }
34}
35
36/// Builder for [`crate::tuple::ArrayOfDoublesSketch`], mirroring upstream's
37/// `update_array_of_doubles_sketch::builder`. `lg_k` defaults to `12`,
38/// `resize_factor` to [`ResizeFactor::X8`], `p` to `1.0` (no sampling), and
39/// `num_values` to `1` (matching upstream's
40/// `default_array_tuple_update_policy` default). The seed is never exposed —
41/// every sketch built by this crate uses upstream's `DEFAULT_SEED`.
42#[derive(Debug, Clone, Copy)]
43pub struct ArrayOfDoublesSketchBuilder {
44    lg_k: u8,
45    resize_factor: ResizeFactor,
46    p: f32,
47    num_values: u8,
48}
49
50impl Default for ArrayOfDoublesSketchBuilder {
51    fn default() -> Self {
52        Self {
53            lg_k: 12,
54            resize_factor: ResizeFactor::default(),
55            p: 1.0,
56            num_values: 1,
57        }
58    }
59}
60
61impl ArrayOfDoublesSketchBuilder {
62    /// Creates a new builder with default settings (`lg_k = 12`,
63    /// `resize_factor = X8`, `p = 1.0`, `num_values = 1`).
64    pub fn new() -> Self {
65        Self::default()
66    }
67
68    /// Sets the base-2 log of the target number of retained entries.
69    pub fn lg_k(mut self, lg_k: u8) -> Self {
70        self.lg_k = lg_k;
71        self
72    }
73
74    /// Sets the hash table's growth [`ResizeFactor`].
75    pub fn resize_factor(mut self, resize_factor: ResizeFactor) -> Self {
76        self.resize_factor = resize_factor;
77        self
78    }
79
80    /// Sets the sampling probability. `1.0` (the default) disables sampling;
81    /// values below `1.0` put the sketch into estimation mode from the start.
82    pub fn p(mut self, p: f32) -> Self {
83        self.p = p;
84        self
85    }
86
87    /// Sets the fixed number of `f64` values each retained entry carries.
88    /// Must be at least `1`. Every sketch that will later be unioned,
89    /// intersected, or differenced with this one must use the same value.
90    pub fn num_values(mut self, num_values: u8) -> Self {
91        self.num_values = num_values;
92        self
93    }
94
95    /// Builds the sketch. Returns
96    /// [`SketchError::InvalidConfig`](crate::SketchError::InvalidConfig) if
97    /// `lg_k` is out of range, `p` is outside `(0, 1]`, or `num_values` is
98    /// `0`.
99    pub fn build(self) -> Result<super::ArrayOfDoublesSketch, crate::error::SketchError> {
100        super::ArrayOfDoublesSketch::from_parts(
101            self.lg_k,
102            self.resize_factor,
103            self.p,
104            self.num_values,
105        )
106    }
107}
apache_datasketches/tuple/builder.rs

apache_datasketches/tuple/
builder.rs
