Struct Bounded

Source

pub struct Bounded<S> { /* private fields */ }

Expand description

A ring buffer with an upper bound on its length.

AKA Circular buffer, cyclic buffer, FIFO queue.

Elements can be pushed to the back of the buffer and popped from the front.

Elements must be Copy due to the behaviour of the push and pop methods. If you require working with non-Copy elements, the std VecDeque type may be better suited.

A Bounded ring buffer can be created from any type providing a slice to use for pushing and popping elements.

fn main() {
    // From a fixed size array.
    dasp_ring_buffer::Bounded::from([0; 4]);

    // From a Vec.
    dasp_ring_buffer::Bounded::from(vec![0; 4]);

    // From a Boxed slice.
    dasp_ring_buffer::Bounded::from(vec![0; 3].into_boxed_slice());

    // From a mutably borrowed slice.
    let mut slice = [0; 4];
    dasp_ring_buffer::Bounded::from(&mut slice[..]);

    // An immutable ring buffer from an immutable slice.
    let slice = [0; 4];
    dasp_ring_buffer::Bounded::from(&slice[..]);
}

Implementations§

Source §

impl<S> Bounded<S>
where S: Slice, S::Element: Copy,

Source

pub fn from_full(data: S) -> Self

The same as the From implementation, but assumes that the given data is full of valid elements and initialises the ring buffer with a length equal to max_len.

fn main() {
    let mut rb = dasp_ring_buffer::Bounded::from_full([0, 1, 2, 3]);
    assert_eq!(rb.len(), rb.max_len());
    assert_eq!(rb.pop(), Some(0));
    assert_eq!(rb.pop(), Some(1));
    assert_eq!(rb.pop(), Some(2));
    assert_eq!(rb.pop(), Some(3));
    assert_eq!(rb.pop(), None);
}

Source

pub fn max_len(&self) -> usize

The maximum length that the Bounded buffer can be before pushing would overwrite the front of the buffer.

fn main() {
    let mut ring_buffer = dasp_ring_buffer::Bounded::from([0i32; 3]);
    assert_eq!(ring_buffer.max_len(), 3);
}

Source

pub fn len(&self) -> usize

The current length of the ring buffer.

fn main() {
    let mut ring_buffer = dasp_ring_buffer::Bounded::from([0i32; 3]);
    assert_eq!(ring_buffer.len(), 0);
}

Source

pub fn is_empty(&self) -> bool

Whether or not the ring buffer’s length is equal to 0.

Equivalent to self.len() == 0.

fn main() {
    let mut rb = dasp_ring_buffer::Bounded::from([0i32; 2]);
    assert!(rb.is_empty());
    rb.push(0);
    assert!(!rb.is_empty());
}

Source

pub fn is_full(&self) -> bool

Whether or not the ring buffer’s length is equal to the maximum length.

Equivalent to self.len() == self.max_len().

fn main() {
    let mut rb = dasp_ring_buffer::Bounded::from([0i32; 2]);
    assert!(!rb.is_full());
    rb.push(0);
    rb.push(1);
    assert!(rb.is_full());
}

Source

pub fn slices(&self) -> (&[S::Element], &[S::Element])

The start and end slices that make up the ring buffer.

These two slices chained together represent all elements within the buffer in order.

The first slice is always aligned contiguously behind the second slice.

fn main() {
    let mut ring_buffer = dasp_ring_buffer::Bounded::from([0i32; 4]);
    assert_eq!(ring_buffer.slices(), (&[][..], &[][..]));
    ring_buffer.push(1);
    ring_buffer.push(2);
    assert_eq!(ring_buffer.slices(), (&[1, 2][..], &[][..]));
    ring_buffer.push(3);
    ring_buffer.push(4);
    assert_eq!(ring_buffer.slices(), (&[1, 2, 3, 4][..], &[][..]));
    ring_buffer.push(5);
    ring_buffer.push(6);
    assert_eq!(ring_buffer.slices(), (&[3, 4][..], &[5, 6][..]));
}

Source

pub fn slices_mut(&mut self) -> (&mut [S::Element], &mut [S::Element])
where S: SliceMut,

The same as the slices method, but returns mutable slices instead.

Source

pub fn iter(&self) -> Chain<Iter<'_, S::Element>, Iter<'_, S::Element>>

Produce an iterator that yields a reference to each element in the buffer.

This method uses the slices method internally.

fn main() {
    let mut rb = dasp_ring_buffer::Bounded::from([0i32; 3]);
    assert_eq!(rb.iter().count(), 0);
    rb.push(1);
    rb.push(2);
    assert_eq!(rb.iter().cloned().collect::<Vec<_>>(), vec![1, 2]);
}

Source

pub fn iter_mut( &mut self, ) -> Chain<IterMut<'_, S::Element>, IterMut<'_, S::Element>>
where S: SliceMut,

Produce an iterator that yields a mutable reference to each element in the buffer.

This method uses the slices_mut method internally.

Source

pub fn get(&self, index: usize) -> Option<&S::Element>

Borrows the item at the given index.

Returns None if there is no element at the given index.

fn main() {
    let mut rb = dasp_ring_buffer::Bounded::from([0i32; 4]);
    assert_eq!(rb.get(1), None);
    rb.push(0);
    rb.push(1);
    assert_eq!(rb.get(1), Some(&1));
}

Source

pub fn get_mut(&mut self, index: usize) -> Option<&mut S::Element>
where S: SliceMut,

Mutably borrows the item at the given index.

Returns None if there is no element at the given index.

Source

pub fn push(&mut self, elem: S::Element) -> Option<S::Element>
where S: SliceMut,

Pushes the given element to the back of the buffer.

If the buffer length is currently the max length, this replaces the element at the front of the buffer and returns it.

If the buffer length is less than the max length, this pushes the element to the back of the buffer and increases the length of the buffer by 1. None is returned.

fn main() {
    let mut ring_buffer = dasp_ring_buffer::Bounded::from([0i32; 3]);
    assert_eq!(ring_buffer.push(1), None);
    assert_eq!(ring_buffer.push(2), None);
    assert_eq!(ring_buffer.len(), 2);
    assert_eq!(ring_buffer.push(3), None);
    assert_eq!(ring_buffer.len(), 3);
    assert_eq!(ring_buffer.push(4), Some(1));
    assert_eq!(ring_buffer.len(), 3);
}

Source

pub fn pop(&mut self) -> Option<S::Element>
where S: SliceMut,

Pop an element from the front of the ring buffer.

If the buffer is empty, this returns None.

fn main() {
    let mut rb = dasp_ring_buffer::Bounded::from_full([0, 1, 2]);
    assert_eq!(rb.len(), rb.max_len());
    assert_eq!(rb.pop(), Some(0));
    assert_eq!(rb.pop(), Some(1));
    assert_eq!(rb.push(3), None);
    assert_eq!(rb.pop(), Some(2));
    assert_eq!(rb.pop(), Some(3));
    assert_eq!(rb.pop(), None);
}

Source

pub fn drain(&mut self) -> DrainBounded<'_, S> ⓘ

Produce an iterator that drains the ring buffer by popping each element one at a time.

Note that only elements yielded by DrainBounded::next will be popped from the ring buffer. That is, all non-yielded elements will remain in the ring buffer.

fn main() {
    let mut rb = dasp_ring_buffer::Bounded::from_full([0, 1, 2, 3]);
    assert_eq!(rb.drain().take(2).collect::<Vec<_>>(), vec![0, 1]);
    assert_eq!(rb.pop(), Some(2));
    assert_eq!(rb.pop(), Some(3));
    assert_eq!(rb.pop(), None);
}

Source

pub fn from_raw_parts(start: usize, len: usize, data: S) -> Self

Creates a Bounded ring buffer from its start index, length and data slice.

The maximum length of the Bounded ring buffer is assumed to the length of the given slice.

Note: Existing elements within the given data’s slice will not be dropped when overwritten by calls to push. Thus, it is safe for the slice to contain uninitialized elements when using this method.

Note: This method should only be necessary if you require specifying the start and initial len.

**Panic!**s if the following conditions are not met: