Struct quantiles::histogram::Histogram

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

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.

Methods

impl<T> Histogram<T> where
    T: Copy + PartialOrd + Debug, 

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);

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);

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);

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));

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);

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);

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);

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]);

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: Debug> Debug for Histogram<T> where
    T: Copy, 

fn fmt(&self, __arg_0: &mut Formatter) -> Result

Formats the value using the given formatter.

impl<T: Clone> Clone for Histogram<T> where
    T: Copy, 

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: PartialEq> PartialEq for Histogram<T> where
    T: Copy, 

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

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, __arg_0: &Histogram<T>) -> bool

This method tests for !=.