Struct ring_buffer::RingBuffer

pub struct RingBuffer<T> { /* fields omitted */ }

A queue that also allows direct index addressing.

This queue trades some features from VecDeque in the std library for the feature of direct indexing. Instead of returning (), push returns the index of the new element in the buffer. Methods like get_absolute can then be used for element access.

The index returned by push or used by get_absolute may not be the actual index but a higher number that gets wrapped around internally so the indices are still valid after elements get moved around by expanding or shrinking the container.

The features not present in RingBuffer whereas present in VecDeque include:

• Double ended functionality, including push_front and pop_back
• append
• drain
• insert
• remove
• basically anything that messes with the position of elements in the buffer apart from swap

Implementations

impl<T> RingBuffer<T>

pub fn new() -> RingBuffer<T>

Creates an empty RingBuffer.

Example

let buffer: RingBuffer<usize> = RingBuffer::new();

pub fn with_capacity(capacity: usize) -> RingBuffer<T>

Creates an empty RingBuffer with space for at least capacity elements.

Example

let buffer: RingBuffer<usize> = RingBuffer::with_capacity(10);
assert!(buffer.capacity() >= 10);

pub fn as_slices(&self) -> (&[T], &[T])

Returns a pair of slices which contain, in order, the contents of the RingBuffer.

Example

let mut buffer = RingBuffer::new();

buffer.push_back(41);
buffer.push_back(42);
buffer.push_back(1);
buffer.push_back(2);

assert_eq!(buffer.len(), 4);
assert_eq!(buffer.capacity(), 4);
assert_eq!(buffer.front(), Some(&41));
assert_eq!(buffer.as_slices(), (&[41, 42, 1, 2][..], &[][..]));

buffer.pop_front();
buffer.pop_front();
buffer.push_back(3);
buffer.push_back(4);

assert_eq!(buffer.as_slices(), (&[1, 2][..], &[3, 4][..]));

pub fn back(&self) -> Option<&T>

Provides a reference to the back element of the queue, or None if the RingBuffer is empty.

Example

let mut buffer = RingBuffer::new();
assert_eq!(buffer.back(), None);

buffer.push_back(1);
buffer.push_back(2);
assert_eq!(buffer.back(), Some(&2));

pub fn back_mut(&mut self) -> Option<&mut T>

Provides a mutable reference to the back element of the queue, or None if the RingBuffer is empty.

Example

let mut buffer = RingBuffer::new();
assert_eq!(buffer.back(), None);

buffer.push_back(1);
buffer.push_back(2);
if let Some(x) = buffer.back_mut() {
    *x = 42;
}
assert_eq!(buffer.back(), Some(&42));

pub fn back_absolute_index(&self) -> Option<usize>

Returns the absolute index of the back element of the queue, or None if the RingBuffer is empty.

Example

let mut buffer = RingBuffer::new();
assert_eq!(buffer.back_absolute_index(), None);

buffer.push_back(1);
buffer.push_back(2);
let back_index = buffer.back_absolute_index();

assert!(back_index.is_some());
assert_eq!(buffer.get_absolute(back_index.unwrap()), buffer.back());

pub fn capacity(&self) -> usize

Returns the number of elements the RingBuffer can hold without reallocating. For fast wrapping functionality, capacity is always a power of two.

Example

let buffer: RingBuffer<usize> = RingBuffer::with_capacity(10);
assert!(buffer.capacity() >= 16);

pub fn clear(&mut self)

Clears the RingBuffer, removing all values.

Example

let mut buffer = RingBuffer::new();
buffer.push_back(1);
buffer.clear();
assert!(buffer.is_empty());

pub fn contains(&self, x: &T) -> bool where
    T: PartialEq<T>, 

Returns true if the RingBuffer contains an element equal to the given value.

Example

let mut buffer = RingBuffer::new();

buffer.push_back(0);
buffer.push_back(1);

assert_eq!(buffer.contains(&1), true);
assert_eq!(buffer.contains(&42), false);

pub fn front(&self) -> Option<&T>

Provides a reference to the front element of the queue, or None if the RingBuffer is empty.

Example

let mut buffer = RingBuffer::new();
assert_eq!(buffer.front(), None);

buffer.push_back(1);
buffer.push_back(2);
assert_eq!(buffer.front(), Some(&1));

pub fn front_mut(&mut self) -> Option<&mut T>

Provides a mutable reference to the front element of the queue, or None if the RingBuffer is empty.

Example

let mut buffer = RingBuffer::new();
assert_eq!(buffer.front_mut(), None);

buffer.push_back(1);
buffer.push_back(2);
if let Some(x) = buffer.front_mut() {
    *x = 42;
}
assert_eq!(buffer.front(), Some(&42));

pub fn front_absolute_index(&self) -> Option<usize>

Returns the absolute index of the front element of the queue, or None if the RingBuffer is empty.

Example

let mut buffer = RingBuffer::new();
assert_eq!(buffer.front_absolute_index(), None);

buffer.push_back(1);
buffer.push_back(2);

let front_index = buffer.front_absolute_index();

assert!(front_index.is_some());
assert_eq!(buffer.get_absolute(front_index.unwrap()), buffer.front());

pub fn get_absolute(&self, index: usize) -> Option<&T>

Retrieves an element in the RingBuffer by absolute index.

The index provided is the index used by the internal container. This is designed to be used in conjunction with push. This also gets wrapped around, supporting expanding and shrinking the container without breaking the access with absolute addresses.

Example

let mut buffer = RingBuffer::new();

let first = buffer.push_back(1);
buffer.push_back(2);
let second = buffer.push_back(42);

assert_eq!(buffer.get_absolute(first), Some(&1));
assert_eq!(buffer.get_absolute(second), Some(&42));

pub fn get_absolute_mut(&mut self, index: usize) -> Option<&mut T>

Retrieves a mutable element in the RingBuffer by absolute index.

The index provided is the index used by the internal container. This is designed to be used in conjunction with push. This also gets wrapped around, supporting expanding and shrinking the container without breaking the access with absolute addresses.

Example

let mut buffer = RingBuffer::new();

buffer.push_back(1);
let the_answer = buffer.push_back(2);
buffer.push_back(3);

assert_eq!(buffer.get_absolute(the_answer), Some(&2));

if let Some(x) = buffer.get_relative_mut(the_answer) {
    *x = 42;
}

assert_eq!(buffer.get_absolute(the_answer), Some(&42));

pub unsafe fn get_absolute_unchecked(&self, index: usize) -> &T

Retrieves an element in the RingBuffer by absolute index without checking for validity.

This does the same as get_absolute, but skips any checks. Use this if you really need the performance and can guarantee the accessed element is valid.

Safety

The caller is responsible for maintaining Rusts ownership guarantees. The validity of a buffer entry also isn’t checked, so while being valid memory, the reference may not point to an object in valid state.

Example

let mut buffer = RingBuffer::new();

let first = buffer.push_back(1);
buffer.push_back(2);
let second = buffer.push_back(42);

unsafe {
    assert_eq!(buffer.get_absolute_unchecked(first), &1);
    assert_eq!(buffer.get_absolute_unchecked(second), &42);
}

pub unsafe fn get_absolute_mut_unchecked(&mut self, index: usize) -> &mut T

Retrieves a mutable element in the RingBuffer by absolute index without checking for validity.

This does the same as get_absolute_mut, but skips any checks. Use this if you really need the performance and can guarantee the accessed element is valid.

Safety

The caller is responsible for maintaining Rusts ownership guarantees. The validity of a buffer entry also isn’t checked, so while being valid memory, the reference may not point to an object in valid state.

Example

let mut buffer = RingBuffer::new();

buffer.push_back(1);
let the_answer = buffer.push_back(2);
buffer.push_back(3);

assert_eq!(buffer.get_absolute(the_answer), Some(&2));

unsafe {
    *buffer.get_absolute_mut_unchecked(the_answer) = 42;
}

assert_eq!(buffer.get_absolute(the_answer), Some(&42));

pub fn get_relative(&self, index: usize) -> Option<&T>

Retrieves an element in the RingBuffer by relative index.

Element at index 0 is the front of the queue.

Example

let mut buffer = RingBuffer::new();
buffer.push_back(3);
buffer.push_back(4);
buffer.push_back(5);
buffer.push_back(6);
assert_eq!(buffer.get_relative(1), Some(&4));

pub fn get_relative_mut(&mut self, index: usize) -> Option<&mut T>

Retrieves an element in the RingBuffer mutably by relative index.

Element at index 0 is the front of the queue.

Example

let mut buffer = RingBuffer::new();
buffer.push_back(3);
buffer.push_back(4);
buffer.push_back(5);
buffer.push_back(6);
if let Some(elem) = buffer.get_relative_mut(1) {
    *elem = 7;
}

assert_eq!(buffer.get_relative(1), Some(&7));

pub fn is_empty(&self) -> bool

Returns true if the RingBuffer is empty.

Example

let mut buffer = RingBuffer::new();
assert!(buffer.is_empty());
buffer.push_back(1);
assert!(!buffer.is_empty());

pub fn is_full(&self) -> bool

Returns true if the buffer is at full capacity.

Example

let mut buffer = RingBuffer::with_capacity(2);
assert_eq!(buffer.capacity(), 2);
assert!(!buffer.is_full());
buffer.push_back(1);
buffer.push_back(2);
assert!(buffer.is_full());

pub fn iter(&self) -> Iter<'_, T>

Returns a front-to-back iterator.

Example

let mut buffer = RingBuffer::new();
buffer.push_back(3);
buffer.push_back(4);
buffer.push_back(5);
let b: &[_] = &[&3, &4, &5];
let c: Vec<&usize> = buffer.iter().collect();
assert_eq!(buffer.get_absolute(0), Some(&3));
assert_eq!(&c[..], b);

pub fn iter_mut(&mut self) -> IterMut<'_, T>

Returns a front-to-back iterator that returns mutable references.

Example

let mut buffer = RingBuffer::new();
buffer.push_back(3);
buffer.push_back(4);
buffer.push_back(5);
for num in buffer.iter_mut() {
    *num = *num - 2;
}
let b: &[_] = &[&mut 1, &mut 2, &mut 3];
assert_eq!(&buffer.iter_mut().collect::<Vec<&mut usize>>()[..], b);

pub fn len(&self) -> usize

Returns the number of elements in the RingBuffer.

Example

let mut buffer = RingBuffer::new();
assert_eq!(buffer.len(), 0);
buffer.push_back(1);
assert_eq!(buffer.len(), 1);

pub fn pop_front(&mut self) -> Option<T>

Removes the first element and returns it, or None if the RingBuffer is empty.

Example

let mut buffer = RingBuffer::new();
buffer.push_back(1);
buffer.push_back(2);

assert_eq!(buffer.pop_front(), Some(1));
assert_eq!(buffer.pop_front(), Some(2));
assert_eq!(buffer.pop_front(), None);

pub fn push_back(&mut self, new_element: T) -> usize

Appends an element to the back of the RingBuffer.

Examples

let mut buffer = RingBuffer::new();
buffer.push_back(1);
buffer.push_back(42);
assert_eq!(42, *buffer.back().unwrap());

pub fn reserve(&mut self, additional: usize)

Reserves capacity for at least additional more elements to be inserted in the given RingBuffer. The collection may reserve more space to avoid frequent reallocations.

Panics

Panics if the new capacity overflows usize.

Example

let mut buffer: RingBuffer<usize> = vec![1].into_iter().collect();
buffer.reserve(10);
assert!(buffer.capacity() >= 11);

pub fn shrink_to(&mut self, min_capacity: usize)

Shrinks the capacity of the RingBuffer with a lower bound.

The capacity will remain at least as large as the maximum of the length and the supplied value.

Does nothing if the current capacity is smaller than the supplied minimum capacity.

Example

let mut buffer = RingBuffer::with_capacity(15);
buffer.extend(0..4);
assert!(buffer.capacity() >= 15);
assert!(!(buffer.capacity() < 6));
buffer.shrink_to(6);
assert!(buffer.capacity() >= 6);
assert!(!(buffer.capacity() < 4));
buffer.shrink_to(0);
assert!(buffer.capacity() >= 4);

pub fn shrink_to_fit(&mut self)

Shrinks the capacity of the RingBuffer as much as possible.

It will drop down as close as possible to the length but the allocator may still inform the RingBuffer that there is space for a few more elements.

Example

let mut buffer = RingBuffer::with_capacity(15);
buffer.extend(0..4);
assert!(buffer.capacity() >= 15);
buffer.shrink_to_fit();
assert!(buffer.capacity() >= 4);

pub fn swap_relative(&mut self, i: usize, j: usize)

Swaps elements at relative indices i and j.

i and j may be equal.

Element at index 0 is the front of the queue.

Panics

Panics if either index is out of bounds.

Example

let mut buffer = RingBuffer::new();
buffer.push_back(3);
buffer.push_back(4);
buffer.push_back(5);
buffer.push_back(6);
buffer.push_back(7);

assert_eq!(buffer.get_relative(0), Some(&3));
assert_eq!(buffer.get_relative(2), Some(&5));

buffer.swap_relative(0, 2);

assert_eq!(buffer.get_relative(0), Some(&5));
assert_eq!(buffer.get_relative(2), Some(&3));

pub fn swap_absolute(&mut self, i: usize, j: usize)

Swaps elements at absolute indices i and j.

i and j may be equal.

This is designed to be used in conjunction with push.

Panics

Panics if either index is out of bounds.

Example

let mut buffer = RingBuffer::new();
buffer.push_back(3);
let first = buffer.push_back(4);
buffer.push_back(5);
let second = buffer.push_back(6);
buffer.push_back(7);

assert_eq!(buffer.get_absolute(first), Some(&4));
assert_eq!(buffer.get_absolute(second), Some(&6));

buffer.swap_relative(first, second);

assert_eq!(buffer.get_absolute(first), Some(&6));
assert_eq!(buffer.get_absolute(second), Some(&4));

pub fn truncate(&mut self, len: usize)

Shortens the RingBuffer, dropping excess elements from the back.

If len is greater than the RingBuffer’s current length, this has no effect.

Example

let mut buffer = RingBuffer::new();
buffer.push_back(5);
buffer.push_back(10);
buffer.push_back(15);
assert_eq!(buffer.len(), 3);
buffer.truncate(1);
assert_eq!(buffer.len(), 1);
assert_eq!(buffer.get_relative(0), Some(&15));

Trait Implementations

impl<T> Clone for RingBuffer<T> where
    T: Clone, 

fn clone(&self) -> RingBuffer<T>

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<T> Debug for RingBuffer<T> where
    T: Debug, 

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

Formats the value using the given formatter.

impl<T> Default for RingBuffer<T>

fn default() -> RingBuffer<T>

Returns the “default value” for a type.

impl<T> Drop for RingBuffer<T>

fn drop(&mut self)

Executes the destructor for this type.

impl<'a, T> Extend<&'a T> for RingBuffer<T> where
    T: 'a + Copy, 

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

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> Extend<T> for RingBuffer<T>

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

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> From<Vec<T, Global>> for RingBuffer<T>

fn from(other: Vec<T>) -> Self

Performs the conversion.

impl<T> FromIterator<T> for RingBuffer<T>

fn from_iter<I: IntoIterator<Item = T>>(iter: I) -> RingBuffer<T>

Creates a value from an iterator.

impl<T> Hash for RingBuffer<T> where
    T: Hash, 

fn hash<H: Hasher>(&self, state: &mut H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H) where
    H: Hasher, 

Feeds a slice of this type into the given Hasher.

impl<T> Index<usize> for RingBuffer<T>

type Output = T

The returned type after indexing.

fn index(&self, index: usize) -> &T

Performs the indexing (container[index]) operation.

impl<T> IndexMut<usize> for RingBuffer<T>

fn index_mut(&mut self, index: usize) -> &mut T

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

impl<T> IntoIterator for RingBuffer<T>

fn into_iter(self) -> Self::IntoIter

Consumes the RingBuffer into a front-to-back iterator yielding elements by value.

type Item = T

The type of the elements being iterated over.

type IntoIter = IntoIter<T>

Which kind of iterator are we turning this into?

impl<'a, T> IntoIterator for &'a RingBuffer<T>

type Item = &'a T

The type of the elements being iterated over.

type IntoIter = Iter<'a, T>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl<'a, T> IntoIterator for &'a mut RingBuffer<T>

type Item = &'a mut T

The type of the elements being iterated over.

type IntoIter = IterMut<'a, T>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl<T> Ord for RingBuffer<T> where
    T: Ord, 

fn cmp(&self, other: &RingBuffer<T>) -> Ordering

This method returns an Ordering between self and other.

#[must_use]

fn max(self, other: Self) -> Self

Compares and returns the maximum of two values.

#[must_use]

fn min(self, other: Self) -> Self

Compares and returns the minimum of two values.

#[must_use]

fn clamp(self, min: Self, max: Self) -> Self

Restrict a value to a certain interval.

impl<T> PartialEq<RingBuffer<T>> for RingBuffer<T> where
    T: PartialEq, 

fn eq(&self, other: &RingBuffer<T>) -> bool

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

#[must_use]

fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl<T> PartialOrd<RingBuffer<T>> for RingBuffer<T> where
    T: PartialOrd, 

fn partial_cmp(&self, other: &RingBuffer<T>) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

#[must_use]

fn lt(&self, other: &Rhs) -> bool

This method tests less than (for self and other) and is used by the < operator.

#[must_use]

fn le(&self, other: &Rhs) -> bool

This method tests less than or equal to (for self and other) and is used by the <= operator.

#[must_use]

fn gt(&self, other: &Rhs) -> bool

This method tests greater than (for self and other) and is used by the > operator.

#[must_use]

fn ge(&self, other: &Rhs) -> bool

This method tests greater than or equal to (for self and other) and is used by the >= operator.

impl<T> Eq for RingBuffer<T> where
    T: Eq, 

impl<T> Send for RingBuffer<T> where
    T: Send, 

impl<T> Sync for RingBuffer<T> where
    T: Sync,