Struct emath::History

pub struct History<T> {
    min_len: usize,
    max_len: usize,
    max_age: f32,
    total_count: u64,
    values: VecDeque<(f64, T)>,
}

This struct tracks recent values of some time series.

It can be used as a smoothing filter for e.g. latency, fps etc, or to show a log or graph of recent events.

It has a minimum and maximum length, as well as a maximum storage time.

• The minimum length is to ensure you have enough data for an estimate.
• The maximum length is to make sure the history doesn’t take up too much space.
• The maximum age is to make sure the estimate isn’t outdated.

Time difference between values can be zero, but never negative.

This can be used for things like smoothed averages (for e.g. FPS) or for smoothed velocity (e.g. mouse pointer speed). All times are in seconds.

Fields

min_len: usize

In elements, i.e. of values.len(). The length is initially zero, but once past min_len will not shrink below it.

max_len: usize

In elements, i.e. of values.len().

max_age: f32

In seconds.

total_count: u64

Total number of elements seen ever

values: VecDeque<(f64, T)>

(time, value) pairs, oldest front, newest back. Time difference between values can be zero, but never negative.

Implementations

impl<T> History<T>

where T: Copy,

pub fn new(length_range: Range<usize>, max_age: f32) -> Self

Example:

// Drop events that are older than one second,
// as long we keep at least two events. Never keep more than a hundred events.
let mut history = History::new(2..100, 1.0);
assert_eq!(history.average(), None);
history.add(now(), 40.0_f32);
history.add(now(), 44.0_f32);
assert_eq!(history.average(), Some(42.0));

pub fn max_len(&self) -> usize

pub fn max_age(&self) -> f32

pub fn is_empty(&self) -> bool

pub fn len(&self) -> usize

Current number of values kept in history

pub fn total_count(&self) -> u64

Total number of values seen. Includes those that have been discarded due to max_len or max_age.

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

pub fn latest_mut(&mut self) -> Option<&mut T>

pub fn duration(&self) -> f32

Amount of time contained from start to end in this History.

pub fn iter(&self) -> impl ExactSizeIterator<Item = (f64, T)> + '_

(time, value) pairs Time difference between values can be zero, but never negative.

pub fn values(&self) -> impl ExactSizeIterator<Item = T> + '_

pub fn clear(&mut self)

pub fn add(&mut self, now: f64, value: T)

Values must be added with a monotonically increasing time, or at least not decreasing.

pub fn mean_time_interval(&self) -> Option<f32>

Mean time difference between values in this History.

pub fn rate(&self) -> Option<f32>

pub fn flush(&mut self, now: f64)

Remove samples that are too old.

impl<T> History<T>

where T: Copy + Sum + Div<f32, Output = T>,

pub fn sum(&self) -> T

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

impl<T> History<T>

where T: Copy + Sum + Div<f32, Output = T> + Mul<f32, Output = T>,

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

Average times rate. If you are keeping track of individual sizes of things (e.g. bytes), this will estimate the bandwidth (bytes per second).

impl<T, Vel> History<T>

where T: Copy + Sub<Output = Vel>, Vel: Div<f32, Output = Vel>,

pub fn velocity(&self) -> Option<Vel>

Calculate a smooth velocity (per second) over the entire time span. Calculated as the last value minus the first value over the elapsed time between them.

Trait Implementations

impl<T: Clone> Clone for History<T>

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

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<T: Debug> Debug for History<T>

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

Formats the value using the given formatter.