Struct ringbuffer::AllocRingBuffer

pub struct AllocRingBuffer<T, SIZE: RingbufferSize = PowerOfTwo> { /* private fields */ }

The AllocRingBuffer is a RingBufferExt which is based on a Vec. This means it allocates at runtime on the heap, and therefore needs the alloc crate. This struct and therefore the dependency on alloc can be disabled by disabling the alloc (default) feature.

Example

use ringbuffer::{AllocRingBuffer, RingBuffer, RingBufferExt, RingBufferWrite};

let mut buffer = AllocRingBuffer::with_capacity(2);

// First entry of the buffer is now 5.
buffer.push(5);

// The last item we pushed is 5
assert_eq!(buffer.get(-1), Some(&5));

// Second entry is now 42.
buffer.push(42);

assert_eq!(buffer.peek(), Some(&5));
assert!(buffer.is_full());

// Because capacity is reached the next push will be the first item of the buffer.
buffer.push(1);
assert_eq!(buffer.to_vec(), vec![42, 1]);

Implementations

impl<T> AllocRingBuffer<T, NonPowerOfTwo>

pub fn with_capacity_non_power_of_two(cap: usize) -> Self

Creates a AllocRingBuffer with a certain capacity. This capacity is fixed. for this ringbuffer to work, and must not be zero.

Note, that not using a power of two means some operations can’t be optimized as well. For example, bitwise ands might become modulos.

For example, on push operations, benchmarks have shown that a ringbuffer with a power-of-two capacity constructed with with_capacity_non_power_of_two (so which don’t get the same optimization as the ones constructed with with_capacity) can be up to 3x slower

Panics

if the capacity is zero

impl<T> AllocRingBuffer<T, PowerOfTwo>

pub fn with_capacity_power_of_2(cap_power_of_two: usize) -> Self

Creates a AllocRingBuffer with a certain capacity. The actual capacity is the input to the function raised to the power of two (effectively the input is the log2 of the actual capacity)

pub fn with_capacity(cap: usize) -> Self

Creates a AllocRingBuffer with a certain capacity. The capacity must be a power of two.

Panics

Panics when capacity is zero or not a power of two

pub fn new() -> Self

Creates an AllocRingBuffer with a capacity of RINGBUFFER_DEFAULT_CAPACITY.

Trait Implementations

impl<T: Clone, SIZE: RingbufferSize> Clone for AllocRingBuffer<T, SIZE>

fn clone(&self) -> Self

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<T: Debug, SIZE: Debug + RingbufferSize> Debug for AllocRingBuffer<T, SIZE>

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

Formats the value using the given formatter.

impl<T, SIZE: RingbufferSize> Default for AllocRingBuffer<T, SIZE>

fn default() -> Self

Creates a buffer with a capacity of RINGBUFFER_DEFAULT_CAPACITY.

impl<T, SIZE: RingbufferSize> Drop for AllocRingBuffer<T, SIZE>

fn drop(&mut self)

Executes the destructor for this type.

impl<T, SIZE: RingbufferSize> Extend<T> for AllocRingBuffer<T, SIZE>

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

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: Clone> From<&[T]> for AllocRingBuffer<T, NonPowerOfTwo>

fn from(value: &[T]) -> Self

Converts to this type from the input type.

impl<T: Clone, const N: usize> From<&[T; N]> for AllocRingBuffer<T, NonPowerOfTwo>

fn from(value: &[T; N]) -> Self

Converts to this type from the input type.

impl<T: Clone> From<&mut [T]> for AllocRingBuffer<T, NonPowerOfTwo>

fn from(value: &mut [T]) -> Self

Converts to this type from the input type.

impl<T, const N: usize> From<[T; N]> for AllocRingBuffer<T, NonPowerOfTwo>

fn from(value: [T; N]) -> Self

Converts to this type from the input type.

impl<T, SIZE: RingbufferSize> From<AllocRingBuffer<T, SIZE>> for GrowableAllocRingBuffer<T>

fn from(v: AllocRingBuffer<T, SIZE>) -> GrowableAllocRingBuffer<T>

Converts to this type from the input type.

impl<T> From<GrowableAllocRingBuffer<T>> for AllocRingBuffer<T, NonPowerOfTwo>

fn from(v: GrowableAllocRingBuffer<T>) -> AllocRingBuffer<T, NonPowerOfTwo>

Converts to this type from the input type.

impl<RB, SIZE: RingbufferSize> FromIterator<RB> for AllocRingBuffer<RB, SIZE>

fn from_iter<T: IntoIterator<Item = RB>>(iter: T) -> Self

Creates a value from an iterator.

impl<T, SIZE: RingbufferSize> Index<isize> for AllocRingBuffer<T, SIZE>

type Output = T

The returned type after indexing.

fn index(&self, index: isize) -> &Self::Output

Performs the indexing (container[index]) operation.

impl<T, SIZE: RingbufferSize> IndexMut<isize> for AllocRingBuffer<T, SIZE>

fn index_mut(&mut self, index: isize) -> &mut Self::Output

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

impl<T: PartialEq, SIZE: RingbufferSize> PartialEq<AllocRingBuffer<T, SIZE>> for AllocRingBuffer<T, SIZE>

fn eq(&self, other: &Self) -> bool

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

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

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<T, SIZE: RingbufferSize> RingBuffer<T> for AllocRingBuffer<T, SIZE>

fn len(&self) -> usize

Returns the length of the internal buffer. This length grows up to the capacity and then stops growing. This is because when the length is reached, new items are appended at the start.

fn is_empty(&self) -> bool

Returns true if the buffer is entirely empty.

fn is_full(&self) -> bool

Returns true when the length of the ringbuffer equals the capacity. This happens whenever more elements than capacity have been pushed to the buffer.

fn capacity(&self) -> usize

Returns the capacity of the buffer.

impl<T, SIZE: RingbufferSize> RingBufferExt<T> for AllocRingBuffer<T, SIZE>

fn get(&self, index: isize) -> Option<&T>

Gets a value relative to the current index. 0 is the next index to be written to with push. -1 and down are the last elements pushed and 0 and up are the items that were pushed the longest ago.

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

👎Deprecated: cannot find a valid usecase for this, hard to implement for some ringbuffers

Gets a value relative to the start of the array (rarely useful, usually you want Self::get)

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

👎Deprecated: cannot find a valid usecase for this, hard to implement for some ringbuffers

Gets a value mutably relative to the start of the array (rarely useful, usually you want Self::get_mut)

fn clear(&mut self)

Empties the buffer entirely. Sets the length to 0 but keeps the capacity allocated.

fn fill_with<F: FnMut() -> T>(&mut self, f: F)

Sets every element in the ringbuffer to the value returned by f.

fn get_mut(&mut self, index: isize) -> Option<&mut T>

Gets a value relative to the current index mutably. 0 is the next index to be written to with push. -1 and down are the last elements pushed and 0 and up are the items that were pushed the longest ago.

fn peek(&self) -> Option<&T>

Returns the value at the current index. This is the value that will be overwritten by the next push and also the value pushed the longest ago. (alias of Self::front)

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

Returns the value at the front of the queue. This is the value that will be overwritten by the next push and also the value pushed the longest ago. (alias of peek)

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

Returns a mutable reference to the value at the back of the queue. This is the value that will be overwritten by the next push. (alias of peek)

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

Returns the value at the back of the queue. This is the item that was pushed most recently.

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

Returns a mutable reference to the value at the back of the queue. This is the item that was pushed most recently.

fn iter_mut(&mut self) -> RingBufferMutIterator<'_, T, Self>

Creates a mutable iterator over the buffer starting from the item pushed the longest ago, and ending at the element most recently pushed.

fn iter(&self) -> RingBufferIterator<'_, T, Self>

Creates an iterator over the buffer starting from the item pushed the longest ago, and ending at the element most recently pushed.

impl<T, SIZE: RingbufferSize> RingBufferRead<T> for AllocRingBuffer<T, SIZE>

fn dequeue(&mut self) -> Option<T>

dequeues the top item off the ringbuffer, and moves this item out.

fn skip(&mut self)

dequeues the top item off the queue, but does not return it. Instead it is dropped. If the ringbuffer is empty, this function is a nop.

fn drain(&mut self) -> RingBufferDrainingIterator<'_, T, Self>

Returns an iterator over the elements in the ringbuffer, dequeueing elements as they are iterated over.

impl<T, SIZE: RingbufferSize> RingBufferWrite<T> for AllocRingBuffer<T, SIZE>

fn push(&mut self, value: T)

Pushes a value onto the buffer. Cycles around if capacity is reached.

fn enqueue(&mut self, value: T)

alias for push, forming a more natural counterpart to dequeue

impl<T: Eq + PartialEq, SIZE: RingbufferSize> Eq for AllocRingBuffer<T, SIZE>