Struct heapless::HistoryBuffer

pub struct HistoryBuffer<T, N> where
    N: ArrayLength<T>,  { /* fields omitted */ }

A “history buffer”, similar to a write-only ring buffer of fixed length.

This buffer keeps a fixed number of elements. On write, the oldest element is overwritten. Thus, the buffer is useful to keep a history of values with some desired depth, and for example calculate a rolling average.

The buffer is always fully initialized; depending on the constructor, the initial value is either the default value for the element type or a supplied initial value. This simplifies the API and is mostly irrelevant for the intended use case.

Examples

use heapless::HistoryBuffer;
use heapless::consts::*;

// Initialize a new buffer with 8 elements, all initially zero.
let mut buf = HistoryBuffer::<_, U8>::new();

buf.write(3);
buf.write(5);
buf.extend(&[4, 4]);

// The most recent written element is a four.
assert_eq!(buf.recent(), &4);

// To access all elements in an unspecified order, use `as_slice()`.
for el in buf.as_slice() { println!("{:?}", el); }

// Now we can prepare an average of all values, which comes out to 2.
let avg = buf.as_slice().iter().sum::<usize>() / buf.len();
assert_eq!(avg, 2);

Implementations

impl<T, N> HistoryBuffer<T, N> where
    N: ArrayLength<T>,
    T: Default, 

pub fn new() -> Self

Constructs a new history buffer, where every element is filled with the default value of the type T.

HistoryBuffer currently cannot be constructed in const context.

Examples

use heapless::HistoryBuffer;
use heapless::consts::*;

// Allocate a 16-element buffer on the stack
let mut x: HistoryBuffer<u8, U16> = HistoryBuffer::new();
// All elements are zero
assert_eq!(x.as_slice(), [0; 16]);

pub fn clear(&mut self)

Clears the buffer, replacing every element with the default value of type T.

impl<T, N> HistoryBuffer<T, N> where
    N: ArrayLength<T>,
    T: Clone, 

pub fn new_with(t: T) -> Self

Constructs a new history buffer, where every element is the given value.

Examples

use heapless::HistoryBuffer;
use heapless::consts::*;

// Allocate a 16-element buffer on the stack
let mut x: HistoryBuffer<u8, U16> = HistoryBuffer::new_with(4);
// All elements are four
assert_eq!(x.as_slice(), [4; 16]);

pub fn clear_with(&mut self, t: T)

Clears the buffer, replacing every element with the given value.

impl<T, N> HistoryBuffer<T, N> where
    N: ArrayLength<T>, 

pub fn len(&self) -> usize

Returns the capacity of the buffer, which is the length of the underlying backing array.

pub fn write(&mut self, t: T)

Writes an element to the buffer, overwriting the oldest value.

pub fn extend_from_slice(&mut self, other: &[T]) where
    T: Clone, 

Clones and writes all elements in a slice to the buffer.

If the slice is longer than the buffer, only the last self.len() elements will actually be stored.

pub fn recent(&self) -> &T

Returns a reference to the most recently written value.

Examples

use heapless::HistoryBuffer;
use heapless::consts::*;

let mut x: HistoryBuffer<u8, U16> = HistoryBuffer::new();
x.write(4);
x.write(10);
assert_eq!(x.recent(), &10);

pub fn as_slice(&self) -> &[T]

Returns the array slice backing the buffer, without keeping track of the write position. Therefore, the element order is unspecified.

Trait Implementations

impl<T: Clone, N: Clone> Clone for HistoryBuffer<T, N> where
    N: ArrayLength<T>, 

fn clone(&self) -> HistoryBuffer<T, N>

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<'a, T, N> Extend<&'a T> for HistoryBuffer<T, N> where
    T: 'a + Clone,
    N: ArrayLength<T>, 

fn extend<I>(&mut self, iter: I) where
    I: IntoIterator<Item = &'a T>, 

Extends a collection with the contents of an iterator.

fn extend_one(&mut self, item: A)

🔬 This is a nightly-only experimental API. (extend_one)

Extends a collection with exactly one element.

fn extend_reserve(&mut self, additional: usize)

🔬 This is a nightly-only experimental API. (extend_one)

Reserves capacity in a collection for the given number of additional elements.

impl<T, N> Extend<T> for HistoryBuffer<T, N> where
    N: ArrayLength<T>, 

fn extend<I>(&mut self, iter: I) where
    I: IntoIterator<Item = T>, 

Extends a collection with the contents of an iterator.

fn extend_one(&mut self, item: A)

🔬 This is a nightly-only experimental API. (extend_one)

Extends a collection with exactly one element.

fn extend_reserve(&mut self, additional: usize)

🔬 This is a nightly-only experimental API. (extend_one)

Reserves capacity in a collection for the given number of additional elements.