Struct RollingSum

Source

pub struct RollingSum<T, const WINDOW: usize> { /* private fields */ }

Expand description

Tracks a rolling sum of at most WINDOW values.

This type is stack allocated. However a large window might warrant boxing. Clustering multiple instances in the same allocation might offer better cache access patterns.

use high_roller::rolling_sum::RollingSum;

struct Average {
    total: RollingSum<u32, 6000>,
    samples: RollingSum<u8, 6000>
}

// Probably want to box this.
const _: () = assert!(core::mem::size_of::<Average>() == 30064);

Implementations§

Source §

impl<T, const WINDOW: usize> RollingSum<T, WINDOW>
where T: Default,

Source

pub const fn new(init: T, zero: T) -> Self

Constructs a new RollingSum.

Prefer using RollingSum::default for a cleaner API. init is the sum’s initial value. zero is value separating positive and negative for this type. While identifying zero is strange, passing as a parameter avoids requiring a Zero trait impl, which isn’t fun for anybody. Zero is required for differentiating overflow and underflow.

use high_roller::rolling_sum::RollingSum;

let _sum: RollingSum::<usize, 10> = RollingSum::new(0, 0);

§Compile errors

Using WINDOW == 0 is a compile-time error.

// This will fail to compile. A rolling sum of capacity 0 is nonsensical.
let _sum: RollingSum::<usize, 0> = RollingSum::default();

Source §

impl<T, const WINDOW: usize> RollingSum<T, WINDOW>
where T: WrappingAdd + WrappingSub + CheckedAdd + CheckedSub + PartialOrd + Copy + Default,

Source

pub fn add(&mut self, val: T)

Adds T to the rolling sum, displacing the oldest member if the window is full to capacity.

If adding T causes numerical overflow, subsequent calls to RollingSum::total will return None until window expirations cause underflow commensurate to the overflow.

use high_roller::rolling_sum::RollingSum;

let mut rsum: RollingSum<i32, 1000> = RollingSum::default();

rsum.add(100);
rsum.add(1);
rsum.add(-2);

assert_eq!(rsum.total().copied(), Some(99));

§Panics

This function panics if the isize signed overflow balance counter itself overflows. Such a panic is impossible as long as WINDOW <= isize::MAX. And an array of size isize::MAX bytes is fantasy on all current hardware anyway.

Source

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

Returns the accumulated total of all added values that fit within the rolling window’s capacity.

Returns None if the window has overflowed. RollingSum will resume returning Some(&T) when the last element causing overflow is pushed out of the window.

use high_roller::rolling_sum::RollingSum;

let mut rsum: RollingSum<i32, 100> = RollingSum::default();

rsum.add(i32::MIN);
assert_eq!(rsum.total().copied(), Some(i32::MIN));

for _ in 0..1000 {
    rsum.add(i32::MIN);
    assert_eq!(rsum.total(), None);
}

for _ in 0..100 {
    rsum.add(-1);
}
assert_eq!(rsum.total().copied(), Some(-100));