[−][src]Crate ringbuffer

Ringbuffer

The ringbuffer crate provides safe fixed size circular buffers (ringbuffers) in rust.

Implementations for three kinds of ringbuffers, with a mostly similar API are provided:

type	description
`AllocRingBuffer`	Ringbuffer allocated on the heap at runtime. This ringbuffer is still fixed size and requires alloc.
`GenericRingBuffer`	Ringbuffer allocated on the stack. This is done using the [`typenum`] crate to provide a const-generic like interface without needing nightly
[`ConstGenericRingBuffer`]	Ringbuffer which uses const generics to allocate on the stack. This type is feature-gated behind `const_generics` and only works in nightly rust.

All of these ringbuffers also implement the RingBuffer trait for their shared API surface.

Usage

use ringbuffer::{AllocRingBuffer, RingBuffer};

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]);

Features

name	default	description
alloc	✓	Disable this feature to remove the dependency on alloc. Useful for kernels.
const_generics	✗	Enables the ConstGenericRingBuffer. This requires nightly.
generic_uninit	✗	Enables the unsafe `new_uninit` function on `GenericRingBuffer` and [`ConstGenericRingBuffer`] used for faster initialization
generic_array	✓	Disable this feature to remove the `generic_array` and [`typenum`] dependencies (and disables `GenericRingBuffer`).

License

Licensed under GNU Lesser General Public License v3.0

The AllocRingBuffer is a RingBuffer 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.

GenericRingBuffer

The GenericRingBuffer struct is a RingBuffer implementation which does not require alloc. However it does depend on the typenum crate, to provide compile time integers without needing nightly rust. Unfortunately this is the only way to provide a compile time ringbuffer which does not require nightly rust like ConstGenericRingBuffer. Once const-generics are stable this struct will be depricated.

Constants

RINGBUFFER_DEFAULT_CAPACITY

The capacity of a RingBuffer created by new or default (1024).

Traits

ArrayLength	Trait making `GenericArray` work, marking types to be used as length of an array
RingBuffer	RingBuffer is a trait defining the standard interface for all RingBuffer implementations (`AllocRingBuffer`, `GenericRingBuffer`, `ConstGenericRingBuffer`)