pub struct Buffer<T>{ /* private fields */ }Expand description
Low-level contiguous storage with a readable window and spare tail capacity.
Buffer stores initialized values and tracks a readable window as
data[position..limit]. Values before position are considered consumed,
and values after limit are spare capacity that callers may fill before
advancing the limit.
This type is intentionally a low-level, hot-path API. It exposes the full
backing storage through Self::data and Self::data_mut so
higher-level buffering code can avoid repeated slicing and bounds checks.
Callers that mutate the backing storage directly must preserve the position <= limit <= capacity invariant and must only make initialized spare
elements readable by calling Self::advance or
Self::advance_unchecked.
The unchecked methods are for code that has already validated ranges at a
higher level. They keep debug assertions for development builds, but safe
callers should use Self::consume, Self::advance, and checked slice
operations instead.
§Window model
data[..position]contains consumed elements.data[position..limit]contains readable elements.data[limit..capacity]is spare initialized storage.
§Examples
use qubit_io::Buffer;
let mut buffer = Buffer::<u8>::with_capacity(4);
buffer.data_mut()[0..2].copy_from_slice(b"ab");
buffer.advance(2);
assert_eq!(b"ab", &buffer.data()[buffer.position()..buffer.limit()]);
buffer.consume(1);
assert_eq!(b"b", &buffer.data()[buffer.position()..buffer.limit()]);Implementations§
Source§impl<T> Buffer<T>
impl<T> Buffer<T>
Sourcepub fn with_capacity(capacity: usize) -> Self
pub fn with_capacity(capacity: usize) -> Self
Sourcepub fn data_mut(&mut self) -> &mut [T]
pub fn data_mut(&mut self) -> &mut [T]
Returns the mutable backing storage.
Mutating elements outside the current readable or spare operation may invalidate higher-level assumptions about buffered contents.
§Returns
The full initialized backing slice.
Sourcepub fn spare_capacity(&self) -> usize
pub fn spare_capacity(&self) -> usize
Sourcepub const fn is_empty(&self) -> bool
pub const fn is_empty(&self) -> bool
Returns whether the readable window is empty.
§Returns
true when no elements are available for consumption.
Sourcepub fn clear(&mut self)
pub fn clear(&mut self)
Clears all buffered contents.
This resets both cursors to zero without modifying stored values.
Sourcepub fn consume(&mut self, count: usize)
pub fn consume(&mut self, count: usize)
Advances the readable cursor by count elements.
§Parameters
count- Number of readable elements to consume.
§Panics
Panics when count exceeds Self::available.
Sourcepub unsafe fn consume_unchecked(&mut self, count: usize)
pub unsafe fn consume_unchecked(&mut self, count: usize)
Sourcepub fn advance(&mut self, count: usize)
pub fn advance(&mut self, count: usize)
Advances the readable limit by count elements.
§Parameters
count- Number of initialized spare elements to make readable.
§Panics
Panics when count exceeds Self::spare_capacity.
Sourcepub unsafe fn advance_unchecked(&mut self, count: usize)
pub unsafe fn advance_unchecked(&mut self, count: usize)
Sourcepub fn compact(&mut self)
pub fn compact(&mut self)
Moves unread elements to the front of the backing storage.
Consumed elements are discarded. The unread element count is preserved, and the readable window starts at zero after compaction.
Sourcepub unsafe fn copy_from_unchecked(
&mut self,
input: &[T],
input_index: usize,
count: usize,
)
pub unsafe fn copy_from_unchecked( &mut self, input: &[T], input_index: usize, count: usize, )
Copies values from an external slice into the spare tail.
The copied values are made readable by advancing the limit by count.
§Parameters
input- Source storage.input_index- Start index insideinput.count- Number of values to copy.
§Safety
The caller must guarantee that input_index..input_index + count is a
valid range inside input, that the addition does not overflow, that
count <= self.spare_capacity(), and that the source range does not
overlap with this buffer’s destination range.
Sourcepub unsafe fn copy_to_unchecked(
&mut self,
output: &mut [T],
output_index: usize,
count: usize,
)
pub unsafe fn copy_to_unchecked( &mut self, output: &mut [T], output_index: usize, count: usize, )
Copies readable values into an external slice.
The copied values are consumed by advancing the position by count.
§Parameters
output- Destination storage.output_index- Start index insideoutput.count- Number of values to copy.
§Safety
The caller must guarantee that output_index..output_index + count is
a valid range inside output, that the addition does not overflow, that
count <= self.available(), and that the source range does not overlap
with the destination range.