Struct slice_ring_buf::SliceRB
source · pub struct SliceRB<T: Copy + Clone + Default> { /* private fields */ }
Expand description
A fast ring buffer implementation optimized for working with slices. Copies/reads with slices are implemented with memcpy.
Implementations§
source§impl<T: Copy + Clone + Default> SliceRB<T>
impl<T: Copy + Clone + Default> SliceRB<T>
sourcepub fn from_len(len: usize) -> Self
pub fn from_len(len: usize) -> Self
Creates a new SliceRB
. All data will be initialized with the default value.
len
- The length of the ring buffer.
Example
use slice_ring_buf::SliceRB;
let rb = SliceRB::<u32>::from_len(3);
assert_eq!(rb.len(), 3);
assert_eq!(rb[0], 0);
assert_eq!(rb[1], 0);
assert_eq!(rb[2], 0);
Panics
- This will panic if
len = 0
. - This will panic if this tries to allocate more than
isize::MAX
bytes.
sourcepub fn from_len_with_capacity(len: usize, capacity: usize) -> Self
pub fn from_len_with_capacity(len: usize, capacity: usize) -> Self
Creates a new SliceRB
, while reserving extra capacity for future changes
to len
. All data from [0..len)
will be initialized with the default value.
len
- The length of the ring buffer.capacity
- The allocated capacity of the ring buffer. If this is less thanlen
, then it will be ignored.
Example
use slice_ring_buf::SliceRB;
let rb = SliceRB::<u32>::from_len_with_capacity(3, 10);
assert_eq!(rb.len(), 3);
assert!(rb.capacity() >= 10);
Panics
- This will panic if
len = 0
. - This will panic if this tries to allocate more than
isize::MAX
bytes.
sourcepub unsafe fn from_len_uninit(len: usize) -> Self
pub unsafe fn from_len_uninit(len: usize) -> Self
Creates a new SliceRB
without initializing data.
len
- The length of the ring buffer.
Safety
- Undefined behavior may occur if uninitialized data is read from. By using this you assume the responsibility of making sure any data is initialized before it is read.
Example
use slice_ring_buf::SliceRB;
unsafe {
let rb = SliceRB::<u32>::from_len_uninit(3);
assert_eq!(rb.len(), 3);
}
Panics
- This will panic if
len = 0
. - This will panic if this tries to allocate more than
isize::MAX
bytes.
sourcepub unsafe fn from_len_with_capacity_uninit(len: usize, capacity: usize) -> Self
pub unsafe fn from_len_with_capacity_uninit(len: usize, capacity: usize) -> Self
Creates a new SliceRB
without initializing data, while reserving extra
capacity for future changes to len
.
len
- The length of the ring buffer.capacity
- The allocated capacity of the ring buffer. If this is less thanlen
, then it will be ignored.
Safety
- Undefined behavior may occur if uninitialized data is read from. By using this you assume the responsibility of making sure any data is initialized before it is read.
Example
use slice_ring_buf::SliceRB;
unsafe {
let rb = SliceRB::<u32>::from_len_with_capacity_uninit(3, 10);
assert_eq!(rb.len(), 3);
assert!(rb.capacity() >= 10);
}
Panics
- This will panic if
len = 0
. - This will panic if this tries to allocate more than
isize::MAX
bytes.
sourcepub fn clear_set_len(&mut self, len: usize)
pub fn clear_set_len(&mut self, len: usize)
Sets the length of the ring buffer while clearing all values to the default value.
Example
use slice_ring_buf::SliceRB;
let mut rb = SliceRB::<u32>::from_len(2);
rb[0] = 1;
rb[1] = 2;
rb.clear_set_len(4);
assert_eq!(rb.len(), 4);
assert_eq!(rb[0], 0);
assert_eq!(rb[1], 0);
assert_eq!(rb[2], 0);
assert_eq!(rb[3], 0);
Panics
- This will panic if
len = 0
. - This will panic if this tries to allocate more than
isize::MAX
bytes.
sourcepub fn set_len(&mut self, len: usize)
pub fn set_len(&mut self, len: usize)
Sets the length of the ring buffer.
- If
len
is less than the current length, then the data will be truncated. - If
len
is larger than the current length, then all newly allocated elements appended to the end will be initialized with the default value.
Example
use slice_ring_buf::SliceRB;
let mut rb = SliceRB::<u32>::from_len(2);
rb[0] = 1;
rb[1] = 2;
rb.set_len(4);
assert_eq!(rb.len(), 4);
assert_eq!(rb[0], 1);
assert_eq!(rb[1], 2);
assert_eq!(rb[2], 0);
assert_eq!(rb[3], 0);
Panics
- This will panic if
len = 0
. - This will panic if this tries to allocate more than
isize::MAX
bytes.
sourcepub unsafe fn set_len_uninit(&mut self, len: usize)
pub unsafe fn set_len_uninit(&mut self, len: usize)
Sets the length of the ring buffer without initializing any newly allocated data.
- If
len
is less than the current length, then the data will be truncated. - If
len
is larger than the current length, then all newly allocated elements appended to the end will be unitialized.
Safety
- Undefined behavior may occur if uninitialized data is read from. By using this you assume the responsibility of making sure any data is initialized before it is read.
Example
use slice_ring_buf::SliceRB;
let mut rb = SliceRB::<u32>::from_len(2);
rb[0] = 1;
rb[1] = 2;
unsafe {
rb.set_len_uninit(4);
assert_eq!(rb.len(), 4);
assert_eq!(rb[0], 1);
assert_eq!(rb[1], 2);
}
Panics
- This will panic if
len = 0
. - This will panic if this tries to allocate more than
isize::MAX
bytes.
sourcepub fn clear(&mut self)
pub fn clear(&mut self)
Clears all values in the ring buffer to the default value.
Example
use slice_ring_buf::SliceRB;
let mut rb = SliceRB::<u32>::from_len(2);
rb[0] = 1;
rb[1] = 2;
rb.clear();
assert_eq!(rb[0], 0);
assert_eq!(rb[1], 0);
sourcepub fn reserve(&mut self, additional: usize)
pub fn reserve(&mut self, additional: usize)
Reserves capacity for at least additional
more elements to be inserted
in the internal Vec
. This is equivalant to Vec::reserve()
.
The collection may reserve more space to avoid frequent reallocations. After calling reserve, capacity will be greater than or equal to self.len() + additional. Does nothing if capacity is already sufficient.
Example
use slice_ring_buf::SliceRB;
let mut rb = SliceRB::<u32>::from_len(2);
rb.reserve(8);
assert!(rb.capacity() >= 10);
Panics
- Panics if the new capacity overflows
usize
.
sourcepub fn reserve_exact(&mut self, additional: usize)
pub fn reserve_exact(&mut self, additional: usize)
Reserves capacity for exactly additional
more elements to be inserted
in the internal Vec
. This is equivalant to Vec::reserve_exact()
.
The collection may reserve more space to avoid frequent reallocations. After calling reserve, capacity will be greater than or equal to self.len() + additional. Does nothing if capacity is already sufficient.
Note that the allocator may give the collection more space than it requests. Therefore,
capacity can not be relied upon to be precisely minimal. Prefer reserve
if future
insertions are expected.
Example
use slice_ring_buf::SliceRB;
let mut rb = SliceRB::<u32>::from_len(2);
rb.reserve_exact(8);
assert!(rb.capacity() >= 10);
Panics
- Panics if the new capacity overflows
usize
.
sourcepub fn shrink_to_fit(&mut self)
pub fn shrink_to_fit(&mut self)
Shrinks the capacity of the internal Vec
as much as possible. This is equivalant to
Vec::shrink_to_fit
.
It will drop down as close as possible to the length but the allocator may still inform the vector that there is space for a few more elements.
Example
use slice_ring_buf::SliceRB;
let mut rb = SliceRB::<u32>::from_len(2);
rb.reserve(8);
assert!(rb.capacity() >= 10);
rb.shrink_to_fit();
assert!(rb.capacity() >= 2);
sourcepub fn as_slices(&self, start: isize) -> (&[T], &[T])
pub fn as_slices(&self, start: isize) -> (&[T], &[T])
Returns two slices that contain all the data in the ring buffer
starting at the index start
.
Returns
- The first slice is the starting chunk of data. This will never be empty.
- The second slice is the second contiguous chunk of data. This may or may not be empty depending if the buffer needed to wrap around to the beginning of its internal memory layout.
Performance
Prefer to use this to manipulate data in bulk over indexing one element at a time.
Example
use slice_ring_buf::SliceRB;
let mut rb = SliceRB::<u32>::from_len(4);
rb[0] = 1;
rb[1] = 2;
rb[2] = 3;
rb[3] = 4;
let (s1, s2) = rb.as_slices(-4);
assert_eq!(s1, &[1, 2, 3, 4]);
assert_eq!(s2, &[]);
let (s1, s2) = rb.as_slices(3);
assert_eq!(s1, &[4]);
assert_eq!(s2, &[1, 2, 3]);
sourcepub fn as_slices_len(&self, start: isize, len: usize) -> (&[T], &[T])
pub fn as_slices_len(&self, start: isize, len: usize) -> (&[T], &[T])
Returns two slices of data in the ring buffer
starting at the index start
and with length len
.
start
- The starting indexlen
- The length of data to read. Iflen
is greater than the length of the ring buffer, then that length will be used instead.
Returns
- The first slice is the starting chunk of data.
- The second slice is the second contiguous chunk of data. This may or may not be empty depending if the buffer needed to wrap around to the beginning of its internal memory layout.
Performance
Prefer to use this to manipulate data in bulk over indexing one element at a time.
Example
use slice_ring_buf::SliceRB;
let mut rb = SliceRB::<u32>::from_len(4);
rb[0] = 1;
rb[1] = 2;
rb[2] = 3;
rb[3] = 4;
let (s1, s2) = rb.as_slices_len(-4, 3);
assert_eq!(s1, &[1, 2, 3]);
assert_eq!(s2, &[]);
let (s1, s2) = rb.as_slices_len(3, 5);
assert_eq!(s1, &[4]);
assert_eq!(s2, &[1, 2, 3]);
sourcepub fn as_slices_latest(&self, start: isize, len: usize) -> (&[T], &[T])
pub fn as_slices_latest(&self, start: isize, len: usize) -> (&[T], &[T])
Returns two slices of data in the ring buffer
starting at the index start
and with length len
. If len
is greater
than the length of the ring buffer, then the buffer’s length will be used
instead, while still preserving the position of the last element.
start
- The starting indexlen
- The length of data to read. Iflen
is greater than the length of the ring buffer, then the buffer’s length will be used instead, while still preserving the position of the last element.
Returns
- The first slice is the starting chunk of data.
- The second slice is the second contiguous chunk of data. This may or may not be empty depending if the buffer needed to wrap around to the beginning of its internal memory layout.
Performance
Prefer to use this to manipulate data in bulk over indexing one element at a time.
Example
use slice_ring_buf::SliceRB;
let mut rb = SliceRB::<u32>::from_len(4);
rb[0] = 1;
rb[1] = 2;
rb[2] = 3;
rb[3] = 4;
let (s1, s2) = rb.as_slices_latest(-4, 3);
assert_eq!(s1, &[1, 2, 3]);
assert_eq!(s2, &[]);
let (s1, s2) = rb.as_slices_latest(0, 5);
assert_eq!(s1, &[2, 3, 4]);
assert_eq!(s2, &[1]);
sourcepub fn as_mut_slices(&mut self, start: isize) -> (&mut [T], &mut [T])
pub fn as_mut_slices(&mut self, start: isize) -> (&mut [T], &mut [T])
Returns two mutable slices that contain all the data in the ring buffer
starting at the index start
.
Returns
- The first slice is the starting chunk of data. This will never be empty.
- The second slice is the second contiguous chunk of data. This may or may not be empty depending if the buffer needed to wrap around to the beginning of its internal memory layout.
Performance
Prefer to use this to manipulate data in bulk over indexing one element at a time.
Example
use slice_ring_buf::SliceRB;
let mut rb = SliceRB::<u32>::from_len(4);
rb[0] = 1;
rb[1] = 2;
rb[2] = 3;
rb[3] = 4;
let (s1, s2) = rb.as_mut_slices(-4);
assert_eq!(s1, &mut [1, 2, 3, 4]);
assert_eq!(s2, &mut []);
let (s1, s2) = rb.as_mut_slices(3);
assert_eq!(s1, &mut [4]);
assert_eq!(s2, &mut [1, 2, 3]);
sourcepub fn as_mut_slices_len(
&mut self,
start: isize,
len: usize
) -> (&mut [T], &mut [T])
pub fn as_mut_slices_len( &mut self, start: isize, len: usize ) -> (&mut [T], &mut [T])
Returns two mutable slices of data in the ring buffer
starting at the index start
and with length len
.
start
- The starting indexlen
- The length of data to read. Iflen
is greater than the length of the ring buffer, then that length will be used instead.
Returns
- The first slice is the starting chunk of data.
- The second slice is the second contiguous chunk of data. This may or may not be empty depending if the buffer needed to wrap around to the beginning of its internal memory layout.
Performance
Prefer to use this to manipulate data in bulk over indexing one element at a time.
Example
use slice_ring_buf::SliceRB;
let mut rb = SliceRB::<u32>::from_len(4);
rb[0] = 1;
rb[1] = 2;
rb[2] = 3;
rb[3] = 4;
let (s1, s2) = rb.as_mut_slices_len(-4, 3);
assert_eq!(s1, &mut [1, 2, 3]);
assert_eq!(s2, &mut []);
let (s1, s2) = rb.as_mut_slices_len(3, 5);
assert_eq!(s1, &mut [4]);
assert_eq!(s2, &mut [1, 2, 3]);
sourcepub fn as_mut_slices_latest(
&mut self,
start: isize,
len: usize
) -> (&mut [T], &mut [T])
pub fn as_mut_slices_latest( &mut self, start: isize, len: usize ) -> (&mut [T], &mut [T])
Returns two mutable slices of data in the ring buffer
starting at the index start
and with length len
. If len
is greater
than the length of the ring buffer, then the buffer’s length will be used
instead, while still preserving the position of the last element.
start
- The starting indexlen
- The length of data to read. Iflen
is greater than the length of the ring buffer, then the buffer’s length will be used instead, while still preserving the position of the last element.
Returns
- The first slice is the starting chunk of data.
- The second slice is the second contiguous chunk of data. This may or may not be empty depending if the buffer needed to wrap around to the beginning of its internal memory layout.
Performance
Prefer to use this to manipulate data in bulk over indexing one element at a time.
Example
use slice_ring_buf::SliceRB;
let mut rb = SliceRB::<u32>::from_len(4);
rb[0] = 1;
rb[1] = 2;
rb[2] = 3;
rb[3] = 4;
let (s1, s2) = rb.as_mut_slices_latest(-4, 3);
assert_eq!(s1, &mut [1, 2, 3]);
assert_eq!(s2, &mut []);
let (s1, s2) = rb.as_mut_slices_latest(0, 5);
assert_eq!(s1, &mut [2, 3, 4]);
assert_eq!(s2, &mut [1]);
sourcepub fn read_into(&self, slice: &mut [T], start: isize)
pub fn read_into(&self, slice: &mut [T], start: isize)
Copies the data from the ring buffer starting from the index start
into the given slice. If the length of slice
is larger than the
length of the ring buffer, then the data will be reapeated until
the given slice is filled.
slice
- This slice to copy the data into.start
- The index of the ring buffer to start copying from.
Performance
Prefer to use this to manipulate data in bulk over indexing one element at a time.
Example
use slice_ring_buf::SliceRB;
let mut rb = SliceRB::<u32>::from_len(4);
rb[0] = 1;
rb[1] = 2;
rb[2] = 3;
rb[3] = 4;
let mut read_buf = [0u32; 3];
rb.read_into(&mut read_buf[..], -3);
assert_eq!(read_buf, [2, 3, 4]);
let mut read_buf = [0u32; 9];
rb.read_into(&mut read_buf[..], 2);
assert_eq!(read_buf, [3, 4, 1, 2, 3, 4, 1, 2, 3]);
sourcepub fn write_latest(&mut self, slice: &[T], start: isize)
pub fn write_latest(&mut self, slice: &[T], start: isize)
Copies data from the given slice into the ring buffer starting from
the index start
.
Earlier data will not be copied if it will be overwritten by newer data, avoiding unecessary memcpy’s. The correct placement of the newer data will still be preserved.
slice
- This slice to copy data from.start
- The index of the ring buffer to start copying from.
Performance
Prefer to use this to manipulate data in bulk over indexing one element at a time.
Example
use slice_ring_buf::SliceRB;
let mut rb = SliceRB::<u32>::from_len(4);
let input = [1u32, 2, 3];
rb.write_latest(&input[..], -3);
assert_eq!(rb[0], 0);
assert_eq!(rb[1], 1);
assert_eq!(rb[2], 2);
assert_eq!(rb[3], 3);
let input = [1u32, 2, 3, 4, 5, 6, 7, 8, 9];
rb.write_latest(&input[..], 2);
assert_eq!(rb[0], 7);
assert_eq!(rb[1], 8);
assert_eq!(rb[2], 9);
assert_eq!(rb[3], 6);
sourcepub fn write_latest_2(&mut self, first: &[T], second: &[T], start: isize)
pub fn write_latest_2(&mut self, first: &[T], second: &[T], start: isize)
Copies data from two given slices into the ring buffer starting from
the index start
. The first
slice will be copied first then second
will be copied next.
Earlier data will not be copied if it will be overwritten by newer data, avoiding unecessary memcpy’s. The correct placement of the newer data will still be preserved.
first
- This first slice to copy data from.second
- This second slice to copy data from.start
- The index of the ring buffer to start copying from.
Performance
Prefer to use this to manipulate data in bulk over indexing one element at a time.
Example
use slice_ring_buf::SliceRB;
let mut input_rb = SliceRB::<u32>::from_len(4);
input_rb[0] = 1;
input_rb[1] = 2;
input_rb[2] = 3;
input_rb[3] = 4;
let mut output_rb = SliceRB::<u32>::from_len(4);
// s1 == &[1, 2], s2 == &[]
let (s1, s2) = input_rb.as_slices_len(0, 2);
output_rb.write_latest_2(s1, s2, -3);
assert_eq!(output_rb[0], 0);
assert_eq!(output_rb[1], 1);
assert_eq!(output_rb[2], 2);
assert_eq!(output_rb[3], 0);
let mut output_rb = SliceRB::<u32>::from_len(2);
// s1 == &[4], s2 == &[1, 2, 3]
let (s1, s2) = input_rb.as_slices_len(3, 4);
// rb[1] = 4 -> rb[0] = 1 -> rb[1] = 2 -> rb[0] = 3
output_rb.write_latest_2(s1, s2, 1);
assert_eq!(output_rb[0], 3);
assert_eq!(output_rb[1], 2);
sourcepub fn len(&self) -> usize
pub fn len(&self) -> usize
Returns the length of the ring buffer.
Example
use slice_ring_buf::SliceRB;
let rb = SliceRB::<u32>::from_len(4);
assert_eq!(rb.len(), 4);
sourcepub fn capacity(&self) -> usize
pub fn capacity(&self) -> usize
Returns the allocated capacity of the internal vector.
Please note this is not the same as the length of the buffer.
For that use SliceRB::len()
.
Example
use slice_ring_buf::SliceRB;
let rb = SliceRB::<u32>::from_len(4);
assert!(rb.capacity() >= 4);
sourcepub fn constrain(&self, i: isize) -> isize
pub fn constrain(&self, i: isize) -> isize
Returns the actual index of the ring buffer from the given
i
index.
- First, a bounds check will be performed. If it is within bounds, then it is simply returned.
- If it is not in bounds, then performance will
be limited by the modulo (remainder) operation on an
isize
value.
Performance
Prefer to manipulate data in bulk with methods that return slices. If you
need to index multiple elements one at a time, prefer to use
SliceRB::at(&mut i)
over SliceRB[i]
to reduce the number of
modulo operations to perform.
Example
use slice_ring_buf::SliceRB;
let rb = SliceRB::<u32>::from_len(4);
assert_eq!(rb.constrain(2), 2);
assert_eq!(rb.constrain(4), 0);
assert_eq!(rb.constrain(-3), 1);
assert_eq!(rb.constrain(7), 3);
sourcepub fn raw_data(&self) -> &[T]
pub fn raw_data(&self) -> &[T]
Returns all the data in the buffer. The starting index will
always be 0
.
Example
use slice_ring_buf::SliceRB;
let mut rb = SliceRB::<u32>::from_len(4);
rb[0] = 1;
rb[1] = 2;
rb[2] = 3;
rb[3] = 4;
let raw_data = rb.raw_data();
assert_eq!(raw_data, &[1u32, 2, 3, 4]);
sourcepub fn raw_data_mut(&mut self) -> &mut [T]
pub fn raw_data_mut(&mut self) -> &mut [T]
Returns all the data in the buffer as mutable. The starting
index will always be 0
.
Example
use slice_ring_buf::SliceRB;
let mut rb = SliceRB::<u32>::from_len(4);
rb[0] = 1;
rb[1] = 2;
rb[2] = 3;
rb[3] = 4;
let raw_data = rb.raw_data_mut();
assert_eq!(raw_data, &mut [1u32, 2, 3, 4]);
sourcepub fn raw_at(&self, i: usize) -> &T
pub fn raw_at(&self, i: usize) -> &T
Returns the element at the index of type usize
.
Please note this does NOT wrap around. This is equivalent to
indexing a normal Vec
.
Example
use slice_ring_buf::SliceRB;
let mut rb = SliceRB::<u32>::from_len(4);
rb[0] = 1;
rb[3] = 4;
assert_eq!(*rb.raw_at(0), 1);
assert_eq!(*rb.raw_at(3), 4);
// These will panic!
// assert_eq!(*rb.raw_at(-3), 2);
// assert_eq!(*rb.raw_at(4), 1);
Panics
- This will panic if
i
is out of bounds of the internalVec
.
sourcepub fn raw_at_mut(&mut self, i: usize) -> &mut T
pub fn raw_at_mut(&mut self, i: usize) -> &mut T
Returns the element at the index of type usize
as mutable.
Please note this does NOT wrap around. This is equivalent to
indexing a normal Vec
.
Example
use slice_ring_buf::SliceRB;
let mut rb = SliceRB::<u32>::from_len(4);
*rb.raw_at_mut(0) = 1;
*rb.raw_at_mut(3) = 4;
assert_eq!(rb[0], 1);
assert_eq!(rb[3], 4);
// These will panic!
// *rb.raw_at_mut(-3) = 2;
// *rb.raw_at_mut(4) = 1;
Panics
- This will panic if
i
is out of bounds of the internalVec
.
sourcepub fn at(&self, i: &mut isize) -> &T
pub fn at(&self, i: &mut isize) -> &T
Returns the element at the index of type usize
while also
constraining the index i
. This is more efficient
than calling both methods individually.
Performance
Prefer to manipulate data in bulk with methods that return slices. If you
need to index multiple elements one at a time, prefer to use
this over SliceRB[i]
to reduce the number of
modulo operations to perform.
Example
use slice_ring_buf::SliceRB;
let mut rb = SliceRB::<u32>::from_len(4);
rb[0] = 1;
rb[1] = 2;
rb[2] = 3;
rb[3] = 4;
let mut i = -3;
assert_eq!(*rb.at(&mut i), 2);
assert_eq!(i, 1);
sourcepub fn at_mut(&mut self, i: &mut isize) -> &mut T
pub fn at_mut(&mut self, i: &mut isize) -> &mut T
Returns the element at the index of type usize
as mutable while also
constraining the index i
. This is more efficient
than calling both methods individually.
Performance
Prefer to manipulate data in bulk with methods that return slices. If you
need to index multiple elements one at a time, prefer to use
this over SliceRB[i]
to reduce the number of
modulo operations to perform.
Example
use slice_ring_buf::SliceRB;
let mut rb = SliceRB::<u32>::from_len(4);
let mut i = -3;
*rb.at_mut(&mut i) = 2;
assert_eq!(rb[1], 2);
assert_eq!(i, 1);