running_buffer.rs

Data types for variables of which you want to monitor their changing state.

RunningBuffer

a RunningBuffer is a non-allocated fixed-length FILO container. Useful for example if you want to keep track of the N most recent values something has had. It keeps track of the most recent N entries.

        let a = RunningBuffer::<u32, 5>::new();
        assert_eq!(a.amount_of_entries(), 0);
        assert_eq!(a.most_recent(), None);
        assert_eq!(a.previous(), None);
        assert_eq!(a.n_ago(2), None);

        let single_entry = a.pushed(100);
        assert_eq!(single_entry.amount_of_entries(), 1);
        assert_eq!(single_entry.most_recent().unwrap(), &100);
        assert_eq!(single_entry.previous(), None);
        assert_eq!(single_entry.n_ago(2), None);

        let two_entries = single_entry.pushed(101);
        assert_eq!(two_entries.amount_of_entries(), 2);
        assert_eq!(two_entries.most_recent().unwrap(), &101);
        assert_eq!(two_entries.previous().unwrap(), &100);
        assert_eq!(two_entries.n_ago(2), None);

If more entries are added than it is long, then it starts discarding old entries.

History

a History keeps track of how a value changes over time. Its focus is on giving the ability to compare recent history with longer-duration history. It saves N_MOST_RECENT values in a RunningBuffer exactly, and in addition keeps cumulative and total amount of value as well. This way both recent and total historical values can be assessed and compared.

        let mut s = History::<u32, u64, 2>::new();
        assert_eq!(s.recent.n_ago(0), None);
        assert_eq!(s.total_tests, 0);
        assert_eq!(s.total_historic, 0);

        s.push(100);
        assert_eq!(s.recent.n_ago(0).unwrap(), &100);
        assert_eq!(s.total_tests, 1);
        assert_eq!(s.total_historic, 100);

        s.push(101);
        assert_eq!(s.recent.n_ago(0).unwrap(), &101);
        assert_eq!(s.recent.n_ago(1).unwrap(), &100);
        assert_eq!(s.total_tests, 2);
        assert_eq!(s.total_historic, 201);

        // Only keeps 2 most recent, other only as cumulative.
        s.push(102);
        assert_eq!(s.recent.n_ago(0).unwrap(), &102);
        assert_eq!(s.recent.n_ago(1).unwrap(), &101);
        assert_eq!(s.recent.n_ago(2), None);
        assert_eq!(s.total_tests, 3);
        assert_eq!(s.total_historic, 303);

the CUM type.

As keeping a very long history might run out of bounds of the variable type T, a separate type CUM is used to store long-term cumulative data. The only requirement is for T to be transformable into CUM. For example, I want to record instances of u32. If I record history.pushed(4_294_967_200).pushed(500000), u32 would overflow. By taking the CUM type as u64, you can keep the size of the History smaller than if you were to store all instances as u64, while still having an accurate cumulative number.