c2_histograms/lib.rs
1//! This library contains tools for <b>simulating</b> space efficient histograms.
2//! For the purposes of this library, a histogram is a map from labels to
3//! frequencies, both of which must be numerical.
4//!
5//! We provide is a standard histogram implementation ([`StandardHistogram`]) which
6//! stores label-frequency pairs at face value using a HashMap.
7//!
8//! Furthermore, we provide three additional histogram implementations that use either
9//! strictly less memory than [`StandardHistogram`] or use a fixed amount of memory. The
10//! optimizations are done across two dimensions, the label storage (referred to as "compaction")
11//! and the frequency storage (referred to as "compression").
12//! Hence the name "C-Squared Histograms". The three implementations are as follows:
13//! - [`CompressedHistogram`] - This implementation uses strictly less space than a [`StandardHistogram`]
14//! by approximating the frequencies
15//! - [`CompactHistogram`] - This implementation consumes a fixed amount of space depending on a few
16//! precision parameters. It saves space by approximating labels.
17//! - [`C2Histogram`] - This implementation also utilizes a fixed amount of space, usually much less
18//! than a CompactHistogram. It approximates both labels and frequencies.
19//!
20//! Each of these implementations is parameterized such that the trade-off between precision and
21//! memory performance is directly controlled by the user.
22//!
23//! To construct a [`StandardHistogram`], use the function [`create_standard_histogram`]. Then,
24//! the other histograms can be derived from that standard histogram using the conversion functions
25//! [`to_compact`], [`to_compressed`], or [`to_c2`].
26//!
27//!
28//! [`CompactHistogram`]: c2/struct.CompactHistogram.html
29//! [`StandardHistogram`]: standard/struct.StandardHistogram.html
30//! [`create_standard_histogram`]: standard/fn.create_standard_histogram.html
31//! [`to_compact`]: standard/struct.StandardHistogram.html#method.to_compact
32//! [`to_compressed`]: standard/struct.StandardHistogram.html#method.to_compressed
33//! [`to_c2`]: standard/struct.StandardHistogram.html#method.to_c2
34//! [`C2Histogram`]: c2/struct.C2Histogram.html
35//! [`CompressedHistogram`]: c2/struct.CompressedHistogram.html
36
37/// General trait definitions and [`StandardHistogram`] implementation
38///
39/// [`StandardHistogram`]: struct.StandardHistogram.html
40pub mod standard;
41
42/// Space saving histogram implementations
43pub mod c2;