apache_datasketches/tuple/generic/
mod.rs

1//! Generic Tuple sketches: cardinality estimation where each distinct key
2//! carries a summary of a type you define.
3//!
4//! Implement [`TupleSummary`] on your own type and it becomes usable as a
5//! sketch summary. C++ calls back into Rust to clone and combine summaries;
6//! see [`TupleSummary`]'s documentation for which methods must not panic.
7//!
8//! For the common case of a fixed-width array of `f64` per key, prefer
9//! [`ArrayOfDoublesSketch`](crate::tuple::ArrayOfDoublesSketch) — it binds a
10//! concrete C++ instantiation with no callback overhead.
11//!
12//! ```
13//! # fn main() -> Result<(), apache_datasketches::SketchError> {
14//! use apache_datasketches::tuple::generic::{TupleSketch, TupleSketchBuilder, TupleSummary};
15//!
16//! #[derive(Clone)]
17//! struct Count(u64);
18//!
19//! impl TupleSummary for Count {
20//!     type Update = ();
21//!     fn create(_: &()) -> Self { Count(1) }
22//!     fn union_combine(&mut self, other: &Self) { self.0 += other.0; }
23//!     fn intersection_combine(&mut self, other: &Self) { self.0 += other.0; }
24//! }
25//!
26//! let mut sketch: TupleSketch<Count> = TupleSketchBuilder::new().build()?;
27//! for key in 0..100u64 {
28//!     sketch.update_u64(key, &());
29//! }
30//! // Updating a key that is already present combines the new summary into
31//! // the retained one with `union_combine`, so key 42 ends up at 2.
32//! sketch.update_u64(42, &());
33//! println!("estimate: {}", sketch.get_estimate());
34//!
35//! // `compact` freezes the sketch into an immutable snapshot; `entries`
36//! // hands back each retained `(hash, summary)` pair, with the summary
37//! // cloned back out of C++ as an owned `Count`.
38//! let compact = sketch.compact(true);
39//! assert_eq!(compact.get_num_retained(), 100);
40//! assert!(compact.is_ordered());
41//!
42//! let entries: Vec<(u64, Count)> = compact.entries().collect();
43//! assert_eq!(entries.len(), 100);
44//! // 99 keys were seen once and key 42 was seen twice.
45//! assert_eq!(entries.iter().map(|(_, c)| c.0).sum::<u64>(), 101);
46//! # Ok(())
47//! # }
48//! ```
49
50mod a_not_b;
51mod builder;
52mod compact;
53mod input;
54mod intersection;
55mod jaccard;
56mod sketch;
57mod summary;
58mod union;
59
60pub use a_not_b::TupleAnotB;
61pub use builder::TupleSketchBuilder;
62pub use compact::CompactTupleSketch;
63pub use input::TupleInput;
64pub use intersection::TupleIntersection;
65pub use jaccard::tuple_jaccard_similarity;
66pub use sketch::TupleSketch;
67pub use summary::TupleSummary;
68pub use union::{TupleUnion, TupleUnionBuilder};
apache_datasketches/tuple/generic/mod.rs

apache_datasketches/tuple/generic/
mod.rs
