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

Methods

impl<T> RingBuffer<T>

pub fn new() -> RingBuffer<T>

Creates an empty RingBuffer.

Example

use ring_buffer::RingBuffer;

fn main() {
    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

use ring_buffer::RingBuffer;

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

use ring_buffer::RingBuffer;

let mut buffer = RingBuffer::new();

buffer.push(41);
buffer.push(42);
buffer.push(1);
buffer.push(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();
buffer.pop();
buffer.push(3);
buffer.push(4);

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

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

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

Example

use ring_buffer::RingBuffer;

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

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

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

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

Example

use ring_buffer::RingBuffer;

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

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

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

use ring_buffer::RingBuffer;

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

pub fn clear(&mut self)

Clears the RingBuffer, removing all values.

Example

use ring_buffer::RingBuffer;

let mut buffer = RingBuffer::new();
buffer.push(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

use ring_buffer::RingBuffer;

let mut buffer = RingBuffer::new();

buffer.push(0);
buffer.push(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, or None if the RingBuffer is empty.

Example

use ring_buffer::RingBuffer;

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

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

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

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

Example

use ring_buffer::RingBuffer;

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

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

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

use ring_buffer::RingBuffer;

let mut buffer = RingBuffer::new();

let first = buffer.push(1);
buffer.push(2);
let second = buffer.push(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

use ring_buffer::RingBuffer;

let mut buffer = RingBuffer::new();

buffer.push(1);
let the_answer = buffer.push(2);
buffer.push(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.

Example

use ring_buffer::RingBuffer;

let mut buffer = RingBuffer::new();

let first = buffer.push(1);
buffer.push(2);
let second = buffer.push(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.

Example

use ring_buffer::RingBuffer;

let mut buffer = RingBuffer::new();

buffer.push(1);
let the_answer = buffer.push(2);
buffer.push(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

use ring_buffer::RingBuffer;

let mut buffer = RingBuffer::new();
buffer.push(3);
buffer.push(4);
buffer.push(5);
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

use ring_buffer::RingBuffer;

let mut buffer = RingBuffer::new();
buffer.push(3);
buffer.push(4);
buffer.push(5);
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

use ring_buffer::RingBuffer;

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

pub fn is_full(&self) -> bool

Returns true if the buffer is at full capacity.

Example

use ring_buffer::RingBuffer;

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

Important traits for Iter<'a, T>

impl<'a, T> Iterator for Iter<'a, T> where
    T: 'a,  type Item = &'a T;

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

Returns a front-to-back iterator.

Example

use ring_buffer::RingBuffer;

let mut buffer = RingBuffer::new();
buffer.push(3);
buffer.push(4);
buffer.push(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);

Important traits for IterMut<'a, T>

impl<'a, T> Iterator for IterMut<'a, T> where
    T: 'a,  type Item = &'a mut T;

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

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

Example

use ring_buffer::RingBuffer;

let mut buffer = RingBuffer::new();
buffer.push(3);
buffer.push(4);
buffer.push(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

use ring_buffer::RingBuffer;

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

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

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

Example

use ring_buffer::RingBuffer;

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

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

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

Appends an element to the back of the RingBuffer.

Examples

use ring_buffer::RingBuffer;

let mut buffer = RingBuffer::new();
buffer.push(1);
buffer.push(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

use ring_buffer::RingBuffer;

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

use ring_buffer::RingBuffer;

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

use ring_buffer::RingBuffer;

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

use ring_buffer::RingBuffer;

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

assert_eq!(buffer.get_relative(0), Some(&7));
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(&7));

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

use ring_buffer::RingBuffer;

let mut buffer = RingBuffer::new();
buffer.push(3);
let first = buffer.push(4);
buffer.push(5);
let second = buffer.push(6);
buffer.push(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

use ring_buffer::RingBuffer;

let mut buffer = RingBuffer::new();
buffer.push(5);
buffer.push(10);
buffer.push(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> Ord for RingBuffer<T> where
    T: Ord, 

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

This method returns an Ordering between self and other.

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

Compares and returns the maximum of two values.

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

Compares and returns the minimum of two values.

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

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

Restrict a value to a certain interval.

impl<T> Default for RingBuffer<T>

fn default() -> RingBuffer<T>

Returns the "default value" for a type.

impl<T> IntoIterator for RingBuffer<T>

type Item = T

The type of the elements being iterated over.

type IntoIter = OwnedIter<T>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

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

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

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

Performs the conversion.

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.

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.

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> Into<VecDeque<T>> for RingBuffer<T>

fn into(self) -> VecDeque<T>

Performs the conversion.

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

fn drop(&mut self)

Executes the destructor for this type.

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

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

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

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

Creates a value from an iterator.