Struct heapless::HistoryBuffer

pub struct HistoryBuffer<T, const N: usize> { /* 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.

Examples

use heapless::HistoryBuffer;

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

// Starts with no data
assert_eq!(buf.recent(), None);

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

// The most recent written element is a four.
assert_eq!(buf.recent(), Some(&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 4.
let avg = buf.as_slice().iter().sum::<usize>() / buf.len();
assert_eq!(avg, 4);

Implementations

impl<T, const N: usize> HistoryBuffer<T, N>

pub const fn new() -> Self

Constructs a new history buffer.

The construction of a HistoryBuffer works in const contexts.

Examples

use heapless::HistoryBuffer;

// Allocate a 16-element buffer on the stack
let x: HistoryBuffer<u8, 16> = HistoryBuffer::new();
assert_eq!(x.len(), 0);

pub fn clear(&mut self)

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

impl<T, const N: usize> HistoryBuffer<T, N> where
    T: Copy + Clone, 

pub fn new_with(t: T) -> Self

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

Examples

use heapless::HistoryBuffer;

// Allocate a 16-element buffer on the stack
let mut x: HistoryBuffer<u8, 16> = 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, const N: usize> HistoryBuffer<T, N>

pub fn len(&self) -> usize

Returns the current fill level of the buffer.

pub fn capacity(&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) -> Option<&T>

Returns a reference to the most recently written value.

Examples

use heapless::HistoryBuffer;

let mut x: HistoryBuffer<u8, 16> = HistoryBuffer::new();
x.write(4);
x.write(10);
assert_eq!(x.recent(), Some(&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, const N: usize> AsRef<[T]> for HistoryBuffer<T, N>

fn as_ref(&self) -> &[T]

Performs the conversion.

impl<T, const N: usize> Debug for HistoryBuffer<T, N> where
    T: Debug, 

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

Formats the value using the given formatter.

impl<T, const N: usize> Deref for HistoryBuffer<T, N>

type Target = [T]

The resulting type after dereferencing.

fn deref(&self) -> &[T]

Dereferences the value.

impl<T, const N: usize> Drop for HistoryBuffer<T, N>

fn drop(&mut self)

Executes the destructor for this type.

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

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, const N: usize> Extend<T> for HistoryBuffer<T, N>

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.