Struct Histogram

pub struct Histogram<T>
where
    T: Copy,
{ /* private fields */ }

A binning histogram of unequal, pre-defined bins

This implementation performs summation over T. It’s possible that this summation will overflow, a crash condition in Rust. Unfortunately there’s no generic saturating / checked add over a generic. Please take care when inserting into Histogram for small Ts.

Implementations

impl<T> Histogram<T>

where T: Copy + PartialOrd + Debug,

pub fn new(bounds: Vec<T>) -> Result<Histogram<T>, Error>

Create a new Histogram

This Histogram is a binning histogram of unequal bins. The user is responsible for defining the upper bounds of bins. Users are able to query bin counts without exact bins but should be aware that the results will only be approximate unless the explicit bin is used. See total_* functions for details.

Examples

use quantiles::histogram::{Bound, Histogram};

let mut histo = Histogram::<u64>::new(vec![10, 256, 1987,
1990]).unwrap();
for i in 0..2048 {
    histo.insert(i as u64);
}

assert_eq!(histo.total_above(Bound::Finite(0)), 2048);
assert_eq!(histo.total_above(Bound::Finite(11)), 2037);
assert_eq!(histo.total_above(Bound::Finite(10)), 2037);
assert_eq!(histo.total_between(Bound::Finite(1987),
Bound::Finite(1990)), 3);
assert_eq!(histo.total_below(Bound::PosInf), 2048);

pub fn insert(&mut self, value: T)

where T: Add<Output = T>,

Insert a T into the Histogram

Insertion will search for the appropriate bin and increase the counter found there. If two bins a and b form a bin with a < b then X will be placed into that bin if a < X <= b.

Examples

use quantiles::histogram::{Bound, Histogram};

let mut histo = Histogram::<u64>::new(vec![10, 100]).unwrap();
histo.insert(99 as u64);
histo.insert(100 as u64);

assert_eq!(histo.total_between(Bound::Finite(10), Bound::Finite(100)),
2);

pub fn count(&self) -> usize

Returns the total number of items ‘stored’ in the histogram

Examples

use quantiles::histogram::{Bound, Histogram};

let mut histo = Histogram::<u64>::new(vec![10, 256, 1987,
1990]).unwrap();
for i in 0..2048 {
    histo.insert(i as u64);
}

assert_eq!(histo.count(), 2048);

pub fn sum(&self) -> Option<T>

Returns the sum of the items ‘stored’ in the histogram

Examples

use quantiles::histogram::Histogram;

let mut histo = Histogram::<u64>::new(vec![10, 256, 1987,
1990]).unwrap();

assert_eq!(histo.sum(), None);

for i in 0..2048 {
    histo.insert(i as u64);
}

assert_eq!(histo.sum(), Some(2096128));

pub fn total_below(&self, upper: Bound<T>) -> usize

Total number of items below supplied upper_bound

Examples

use quantiles::histogram::{Bound, Histogram};

let mut histo = Histogram::<u64>::new(vec![10, 256, 1987,
1990]).unwrap();
for i in 0..2048 {
    histo.insert(i as u64);
}

assert_eq!(histo.total_below(Bound::PosInf), 2048);

pub fn total_above(&self, lower: Bound<T>) -> usize

Total number of items above supplied lower_bound

Examples

use quantiles::histogram::{Bound, Histogram};

let mut histo = Histogram::<u64>::new(vec![10, 256, 1987,
1990]).unwrap();
for i in 0..2048 {
    histo.insert(i as u64);
}

assert_eq!(histo.total_above(Bound::Finite(0)), 2048);
assert_eq!(histo.total_above(Bound::Finite(11)), 2037);
assert_eq!(histo.total_above(Bound::Finite(10)), 2037);

pub fn total_between(&self, lower: Bound<T>, upper: Bound<T>) -> usize

Total number of items between [lower_bound, upper_bound)

Examples

use quantiles::histogram::{Bound, Histogram};

let mut histo = Histogram::<u64>::new(vec![10, 256, 1987,
1990]).unwrap();
for i in 0..2048 {
    histo.insert(i as u64);
}

assert_eq!(histo.total_between(Bound::Finite(1987),
Bound::Finite(1990)), 3);

pub fn iter(&self) -> Iter<'_, T>

Iterate over the bounds and counts of bounds

Examples

use quantiles::histogram::{Bound, Histogram};

let mut histo = Histogram::<u64>::new(vec![10, 256, 1987,
1990]).unwrap();
for i in 0..2048 {
    histo.insert(i as u64);
}

let expected: Vec<(Bound<u64>, usize)> = vec![(Bound::Finite(10), 11),
(Bound::Finite(256), 246), (Bound::Finite(1987), 1731),
(Bound::Finite(1990), 3), (Bound::PosInf, 57)];
let actual: Vec<(Bound<u64>, usize)> = histo.iter().map(|x|
*x).collect();
assert_eq!(expected[0], actual[0]);
assert_eq!(expected[1], actual[1]);
assert_eq!(expected[2], actual[2]);
assert_eq!(expected[3], actual[3]);
assert_eq!(expected[4], actual[4]);

pub fn into_vec(self) -> Vec<(Bound<T>, usize)>

Convert a Histogram into an array of tuples

Examples

use quantiles::histogram::{Bound, Histogram};

let mut histo = Histogram::<u64>::new(vec![10, 256, 1987,
1990]).unwrap();
for i in 0..2048 {
    histo.insert(i as u64);
}

let expected: Vec<(Bound<u64>, usize)> = vec![(Bound::Finite(10), 11),
(Bound::Finite(256), 246), (Bound::Finite(1987), 1731),
(Bound::Finite(1990), 3), (Bound::PosInf, 57)];
let actual: Vec<(Bound<u64>, usize)> = histo.into_vec();
assert_eq!(expected[0], actual[0]);
assert_eq!(expected[1], actual[1]);
assert_eq!(expected[2], actual[2]);
assert_eq!(expected[3], actual[3]);
assert_eq!(expected[4], actual[4]);

Trait Implementations

impl<T> AddAssign for Histogram<T>

where T: Copy + PartialOrd + Debug + Add<Output = T>,

fn add_assign(&mut self, rhs: Histogram<T>)

Performs the += operation.

impl<T> Clone for Histogram<T>

where T: Copy + Clone,

fn clone(&self) -> Histogram<T>

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<T> Debug for Histogram<T>

where T: Copy + Debug,

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<T> PartialEq for Histogram<T>

where T: Copy + PartialEq,

fn eq(&self, other: &Histogram<T>) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<T> StructuralPartialEq for Histogram<T>

where T: Copy,