Struct sample::ring_buffer::Bounded[][src]

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

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.

extern crate sample;

use sample::ring_buffer;

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

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

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

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

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

Two slightly more efficient constructors are provided for fixed-size arrays and boxed slices. These are generally more efficient as they do not require initialising elements.

extern crate sample;

use sample::ring_buffer;

fn main() {
    // Fixed-size array.
    ring_buffer::Bounded::<[i32; 4]>::array();

    // Boxed slice.
    let mut rb = ring_buffer::Bounded::boxed_slice(4);
    rb.push(1);
}

Methods

impl<T> Bounded<Box<[T]>> where
    T: Copy
[src]

A Bounded ring buffer that uses a Boxed slice with the given maximum length to represent the data.

Slightly more efficient than using the similar From constructor as this creates the underlying slice with uninitialised memory.

extern crate sample;

use sample::ring_buffer;

fn main() {
    let mut rb = ring_buffer::Bounded::boxed_slice(4);
    assert_eq!(rb.max_len(), 4);
    assert_eq!(rb.len(), 0);
    rb.push(1);
    rb.push(2);
}

impl<S> Bounded<S> where
    S: Slice,
    S::Element: Copy
[src]

A Bounded buffer that uses a fixed-size array to represent data.

Slightly more efficient than using the similar From constructor as this creates the underlying array with uninitialised memory.

extern crate sample;

use sample::ring_buffer;

fn main() {
    let mut rb = ring_buffer::Bounded::<[f32; 3]>::array();
    assert_eq!(rb.len(), 0);
    assert_eq!(rb.max_len(), 3);
}

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.

extern crate sample;

use sample::ring_buffer;

fn main() {
    let mut rb = 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);
}

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

extern crate sample;

fn main() {
    let mut ring_buffer = sample::ring_buffer::Bounded::<[i32; 3]>::array();
    assert_eq!(ring_buffer.max_len(), 3);
}

The current length of the ring buffer.

extern crate sample;

fn main() {
    let mut ring_buffer = sample::ring_buffer::Bounded::<[i32; 3]>::array();
    assert_eq!(ring_buffer.len(), 0);
}

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

Equivalent to self.len() == 0.

extern crate sample;

use sample::ring_buffer;

fn main() {
    let mut rb = ring_buffer::Bounded::<[i32; 2]>::array();
    assert!(rb.is_empty());
    rb.push(0);
    assert!(!rb.is_empty());
}

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

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

extern crate sample;

use sample::ring_buffer;

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

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.

extern crate sample;

fn main() {
    let mut ring_buffer = sample::ring_buffer::Bounded::<[i32; 4]>::array();
    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][..]));
}

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

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

This method uses the slices method internally.

extern crate sample;

use sample::ring_buffer;

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

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

This method uses the slices_mut method internally.

Borrows the item at the given index.

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

extern crate sample;

use sample::ring_buffer;

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

Mutably borrows the item at the given index.

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

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.

extern crate sample;

fn main() {
    let mut ring_buffer = sample::ring_buffer::Bounded::<[i32; 3]>::array();
    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);
}

Pop an element from the front of the ring buffer.

If the buffer is empty, this returns None.

extern crate sample;

use sample::ring_buffer;

fn main() {
    let mut rb = 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);
}

Important traits for DrainBounded<'a, 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.

extern crate sample;

use sample::ring_buffer;

fn main() {
    let mut rb = 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);
}

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. Please see the Bounded::array and Bounded::boxed_slice functions for simpler constructor options that do not require manually passing indices.

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

  • start < data.slice().len()
  • len <= data.slice().len()

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

This method is unsafe as there is no guarantee that either:

  • start < data.slice().len() or
  • len <= data.slice().len().

Consumes the Bounded ring buffer and returns its parts:

  • The first usize is an index into the first element of the buffer.
  • The second usize is the length of the ring buffer.
  • S is the buffer data.

This method is unsafe as the returned data may contain uninitialised memory in the case that the ring buffer is not full.

Trait Implementations

impl<S: Copy> Copy for Bounded<S>
[src]

impl<S: Clone> Clone for Bounded<S>
[src]

Returns a copy of the value. Read more

Performs copy-assignment from source. Read more

impl<S: Debug> Debug for Bounded<S>
[src]

Formats the value using the given formatter. Read more

impl<S: PartialEq> PartialEq for Bounded<S>
[src]

This method tests for self and other values to be equal, and is used by ==. Read more

This method tests for !=.

impl<S: Eq> Eq for Bounded<S>
[src]

impl<S: Hash> Hash for Bounded<S>
[src]

Feeds this value into the given [Hasher]. Read more

Feeds a slice of this type into the given [Hasher]. Read more

impl<S> From<S> for Bounded<S> where
    S: Slice,
    S::Element: Copy
[src]

Construct a Bounded ring buffer from the given data slice.

**Panic!**s if the given data buffer is empty.

impl<S, T> FromIterator<T> for Bounded<S> where
    S: Slice<Element = T> + FromIterator<T>,
    T: Copy
[src]

Creates a value from an iterator. Read more

impl<S> Index<usize> for Bounded<S> where
    S: Slice,
    S::Element: Copy
[src]

The returned type after indexing.

Performs the indexing (container[index]) operation.

impl<S> IndexMut<usize> for Bounded<S> where
    S: SliceMut,
    S::Element: Copy
[src]

Performs the mutable indexing (container[index]) operation.

Auto Trait Implementations

impl<S> Send for Bounded<S> where
    S: Send

impl<S> Sync for Bounded<S> where
    S: Sync