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.
The backing storage is fully initialized up front, so T is constrained to
Clone + Default. Cloning is used when values enter or leave the
buffer, while default initialization keeps every spare slot valid for the
slice-based stream traits.
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.
The unsafe methods are for code that has already validated ranges at a higher level. They keep debug assertions for development builds, but those assertions are not a substitute for the documented safety preconditions.
§Window model
Self::consumed—data[..position], already-consumed elements.Self::readable—data[position..limit], readable elements.Self::spare/Self::spare_mut—data[limit..capacity], 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");
// SAFETY: Two initialized spare elements fit in this buffer.
unsafe {
buffer.advance(2);
}
assert_eq!(b"ab", buffer.readable());
// SAFETY: One readable element is currently available.
unsafe {
buffer.consume(1);
}
assert_eq!(b"b", buffer.readable());§Type Parameters
T: Cloneable item type used for initialized backing storage.
Implementations§
Source§impl<T> Buffer<T>
impl<T> Buffer<T>
Sourcepub fn with_capacity(capacity: usize) -> Self
pub fn with_capacity(capacity: usize) -> Self
Creates an empty buffer with at least the requested capacity.
A requested capacity of 0 is raised to 1.
§Parameters
capacity: Requested element capacity.
§Returns
Returns a buffer with position == 0 and limit == 0.
§Panics
Panics if T::default() or T::clone() panics, or the requested
backing length exceeds Vec’s supported capacity.
Sourcepub fn try_with_capacity(capacity: usize) -> Result<Self, TryReserveError>
pub fn try_with_capacity(capacity: usize) -> Result<Self, TryReserveError>
Tries to create an empty buffer with at least the requested capacity.
A requested capacity of 0 is raised to 1.
§Parameters
capacity: Requested element capacity.
§Returns
Returns an empty buffer with at least one element of capacity.
§Errors
Returns the original allocation error when the backing storage cannot reserve the requested capacity.
§Panics
Panics if T::default() or T::clone() panics.
Sourcepub fn try_reserve_capacity(
&mut self,
capacity: usize,
) -> Result<(), TryReserveError>
pub fn try_reserve_capacity( &mut self, capacity: usize, ) -> Result<(), TryReserveError>
Tries to ensure that the total element capacity is at least capacity.
Existing consumed, readable, and spare windows retain their positions.
§Parameters
capacity: Required total element capacity.
§Returns
Returns Ok(()) after the requested capacity is available.
§Errors
Returns the original allocation error when the backing storage cannot reserve the additional capacity.
§Panics
Panics if growing the backing storage requires T::default() or
T::clone() and either operation panics.
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 spare_raw_parts_mut(&mut self) -> (&mut [T], usize, usize)
pub fn spare_raw_parts_mut(&mut self) -> (&mut [T], usize, usize)
Returns raw spare-tail parts for hot-path callers.
The returned slice is the full backing storage. index is the start of
the spare window, and count is the number of spare elements. Callers
that need a slice can use Self::spare_mut; callers that already
validated bounds can pass buffer and index directly to indexed
unchecked operations that write from index.
§Returns
The backing storage, the spare start index, and the spare element count.
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 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(
&mut self,
input: &[T],
input_index: usize,
count: usize,
)
pub unsafe fn copy_from( &mut self, input: &[T], input_index: usize, count: usize, )
Copies values from an external slice into the spare tail.
The cloned 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.
§Panics
Panics if cloning an input item panics. Debug builds also panic if the
requested input range does not fit or count > self.spare_capacity().
§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(
&mut self,
output: &mut [T],
output_index: usize,
count: usize,
)
pub unsafe fn copy_to( &mut self, output: &mut [T], output_index: usize, count: usize, )
Copies readable values into an external slice.
The cloned values are consumed by advancing the position by count.
§Parameters
output: Destination storage.output_index: Start index insideoutput.count: Number of values to copy.
§Panics
Panics if cloning a readable item panics. Debug builds also panic if the
requested output range does not fit or count > self.available().
§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.