roaring/bitmap/
statistics.rs

1use core::mem;
2
3use crate::bitmap::container::Container;
4use crate::RoaringBitmap;
5
6use super::store::Store;
7
8/// Detailed statistics on the composition of a bitmap.
9#[derive(Clone, Copy, PartialEq, Debug)]
10#[non_exhaustive]
11pub struct Statistics {
12    /// Number of containers in the bitmap
13    pub n_containers: u32,
14    /// Number of array containers in the bitmap
15    pub n_array_containers: u32,
16    /// Number of run containers in the bitmap
17    pub n_run_containers: u32,
18    /// Number of bitset containers in the bitmap
19    pub n_bitset_containers: u32,
20    /// Number of values stored in array containers
21    pub n_values_array_containers: u32,
22    /// Number of values stored in run containers
23    pub n_values_run_containers: u32,
24    /// Number of values stored in bitset containers
25    pub n_values_bitset_containers: u64,
26    /// Number of bytes used by array containers
27    pub n_bytes_array_containers: u64,
28    /// Number of bytes used by run containers
29    pub n_bytes_run_containers: u64,
30    /// Number of bytes used by bitset containers
31    pub n_bytes_bitset_containers: u64,
32    /// Maximum value stored in the bitmap
33    pub max_value: Option<u32>,
34    /// Minimum value stored in the bitmap
35    pub min_value: Option<u32>,
36    /// Number of values stored in the bitmap
37    pub cardinality: u64,
38}
39
40impl RoaringBitmap {
41    /// Returns statistics about the composition of a roaring bitmap.
42    ///
43    /// ```
44    /// use roaring::RoaringBitmap;
45    ///
46    /// let mut bitmap: RoaringBitmap = (1..100).collect();
47    /// let statistics = bitmap.statistics();
48    ///
49    /// assert_eq!(statistics.n_containers, 1);
50    /// assert_eq!(statistics.n_array_containers, 1);
51    /// assert_eq!(statistics.n_run_containers, 0);
52    /// assert_eq!(statistics.n_bitset_containers, 0);
53    /// assert_eq!(statistics.n_values_array_containers, 99);
54    /// assert_eq!(statistics.n_values_run_containers, 0);
55    /// assert_eq!(statistics.n_values_bitset_containers, 0);
56    /// assert_eq!(statistics.n_bytes_array_containers, 512);
57    /// assert_eq!(statistics.n_bytes_run_containers, 0);
58    /// assert_eq!(statistics.n_bytes_bitset_containers, 0);
59    /// assert_eq!(statistics.max_value, Some(99));
60    /// assert_eq!(statistics.min_value, Some(1));
61    /// assert_eq!(statistics.cardinality, 99);
62    /// ```
63    pub fn statistics(&self) -> Statistics {
64        let mut n_containers = 0;
65        let mut n_array_containers = 0;
66        let mut n_bitset_containers = 0;
67        let mut n_run_containers = 0;
68        let mut n_values_array_containers = 0;
69        let mut n_values_bitset_containers = 0;
70        let mut n_values_run_containers = 0;
71        let mut n_bytes_array_containers = 0;
72        let mut n_bytes_bitset_containers = 0;
73        let mut n_bytes_run_containers = 0;
74        let mut cardinality = 0;
75
76        for Container { key: _, store } in &self.containers {
77            match store {
78                Store::Array(array) => {
79                    cardinality += array.len();
80                    n_values_array_containers += array.len() as u32;
81                    n_bytes_array_containers += (array.capacity() * mem::size_of::<u32>()) as u64;
82                    n_array_containers += 1;
83                }
84                Store::Bitmap(bitmap) => {
85                    cardinality += bitmap.len();
86                    n_values_bitset_containers += bitmap.len();
87                    n_bytes_bitset_containers += bitmap.capacity() as u64;
88                    n_bitset_containers += 1;
89                }
90                Store::Run(runs) => {
91                    cardinality += runs.len();
92                    n_values_run_containers += runs.len() as u32;
93                    n_bytes_run_containers += runs.byte_size() as u64;
94                    n_run_containers += 1;
95                }
96            }
97            n_containers += 1;
98        }
99
100        Statistics {
101            n_containers,
102            n_array_containers,
103            n_run_containers,
104            n_bitset_containers,
105            n_values_array_containers,
106            n_values_run_containers,
107            n_values_bitset_containers,
108            n_bytes_array_containers,
109            n_bytes_run_containers,
110            n_bytes_bitset_containers,
111            max_value: self.max(),
112            min_value: self.min(),
113            cardinality,
114        }
115    }
116}