Struct BStackSlice 

pub struct BStackSlice<'a, A: BStackAllocator> { /* private fields */ }

A lifetime-coupled handle to a contiguous region of a BStack payload.

BStackSlice<'a, A> is a lightweight Copy value that holds a shared reference to the allocator A together with a logical offset and len. It is the primary handle type produced by BStackAllocator::alloc and consumed by BStackAllocator::realloc and BStackAllocator::dealloc.

Lifetime

'a is tied to the allocator borrow, not to the BStack directly. This means the borrow checker prevents calling into_stack — which consumes the allocator by value — while any slice is still alive.

After dealloc

Once a slice has been passed to BStackAllocator::dealloc, the handle must not be used for further I/O. The type system enforces this when the slice is consumed by value, but callers who Copy the handle before deallocating must uphold this invariant themselves.

Implementations

impl<'a, A: BStackAllocator> BStackSlice<'a, A>

pub fn new(allocator: &'a A, offset: u64, len: u64) -> Self

👎Deprecated since 0.1.10:

Use unsafe { BStackSlice::from_raw_parts(allocator, offset, len) } instead; see BStackSlice::from_raw_parts for the required safety contract.

Create a new BStackSlice.

Does not validate that offset + len <= stack.len(). Invalid slices produce errors on the first I/O call.

Deprecation

This constructor is deprecated in favour of the explicitly-unsafe BStackSlice::from_raw_parts, which makes the caller’s responsibility visible at the call site. Replace any call BStackSlice::new(allocator, offset, len) with unsafe { BStackSlice::from_raw_parts(allocator, offset, len) } and ensure the # Safety contract of from_raw_parts is upheld.

pub unsafe fn from_raw_parts(allocator: &'a A, offset: u64, len: u64) -> Self

Construct a BStackSlice from raw parts.

This is the explicitly-unsafe replacement for the deprecated BStackSlice::new. The name reflects that an arbitrary (offset, len) pair can bypass invariants that allocators rely on.

Safety

The caller must uphold all of the following:

• offset + len must not overflow u64.
• For I/O calls (read, write, read_range, etc.) the range [offset, offset + len) should lie within the current payload of the backing stack. Out-of-bounds accesses produce io::Error rather than unsound behaviour, so this is a correctness requirement, not a soundness one.
• If the slice will be passed to BStackAllocator::realloc or BStackAllocator::dealloc, (offset, len) must describe an allocation that was directly returned by BStackAllocator::alloc or by a prior BStackAllocator::realloc on the same allocator instance. Passing an arbitrary offset or a sub-slice derived via subslice / subslice_range may silently corrupt the allocator’s persistent metadata in a way that is difficult or impossible to recover from.

pub fn empty(allocator: &'a A) -> Self

Construct a zero-length BStackSlice anchored at offset 0.

The resulting slice spans no bytes and all I/O methods on it are no-ops or return empty results. It is safe to construct because an empty slice cannot produce out-of-bounds reads or writes and carries no allocator-origin requirement.

Useful as a sentinel or default value when a slice field must be initialized before a real allocation is available.

pub fn to_bytes(&self) -> [u8; 16]

Serialize this slice to a 16-byte array for on-disk storage.

Layout: offset as 8 bytes little-endian, then len as 8 bytes little-endian. Reconstruct with BStackSlice::from_bytes.

pub unsafe fn from_bytes(allocator: &'a A, bytes: [u8; 16]) -> Self

Reconstruct a BStackSlice from a 16-byte array produced by BStackSlice::to_bytes.

Safety

The caller must ensure that bytes encodes a valid offset and length that lie within the bounds of the underlying allocator’s payload. Passing an arbitrary or corrupted byte array is undefined behaviour.

pub fn start(&self) -> u64

Returns the start offset of this slice within the payload.

pub fn end(&self) -> u64

The exclusive end offset of this slice within the payload (self.start() + self.len()).

pub fn range(&self) -> Range<u64>

Returns the range of this slice as start..end within the payload.

pub fn len(&self) -> u64

Returns the length of this slice in bytes.

pub fn is_empty(&self) -> bool

Returns true if this slice spans zero bytes.

pub fn allocator(&self) -> &'a A

Return the underlying allocator.

pub fn stack(&self) -> &BStack

Return the underlying stack.

Note: Bstack does not require mutability for any of its operations, and directly mutating the stack without the knowledge of the allocator risks violating invariants. Therefore, use this method with caution and prefer methods on BStackSlice such as read and write that delegate to the stack internally.

pub fn subslice(&self, start: u64, end: u64) -> BStackSlice<'a, A>

Create a subslice of this slice.

Returns a new BStackSlice that refers to the subrange [start, end) within this slice. The start and end parameters are relative to this slice’s start.

Panics

Panics if start > end or end > self.len().

pub fn subslice_range(&self, range: Range<u64>) -> BStackSlice<'a, A>

Create a subslice of this slice.

Returns a new BStackSlice that refers to the subrange range within this slice. The range is relative to this slice’s start.

Panics

Panics if range.start > range.end or range.end > self.len().

pub fn read(&self) -> Result<Vec<u8>>

Read the entire slice into a newly allocated Vec<u8>.

Delegates to BStack::get.

Errors

Returns an error if the range exceeds the current payload size.

pub fn read_into(&self, buf: &mut [u8]) -> Result<()>

Read bytes from this slice into the caller-supplied buf.

Reads min(buf.len(), self.len() as usize) bytes starting at self.start(). If buf is shorter than the slice, only the first buf.len() bytes are read. If buf is longer, only self.len() bytes are filled and the remainder of buf is left untouched.

pub fn read_range(&self, start: u64, end: u64) -> Result<Vec<u8>>

Read a sub-range [start, end) relative to this slice into a newly allocated Vec<u8>.

start and end are relative to self.start(), not the payload start.

Errors

Returns an error if start > end or if end exceeds self.len().

pub fn read_range_into(&self, start: u64, buf: &mut [u8]) -> Result<()>

Read a sub-range [start, start + buf.len()) relative to this slice into the caller-supplied buffer.

start is relative to self.start(), not the payload start.

Errors

Returns io::ErrorKind::InvalidInput if start + buf.len() exceeds self.len().

pub fn write(&self, data: impl AsRef<[u8]>) -> Result<()>

Overwrite the beginning of this slice in place with data.

Writes min(data.len(), self.len() as usize) bytes starting at self.start(). If data is shorter than the slice, the remainder of the slice is left untouched. If data is longer, only self.len() bytes are written.

Requires the set feature.

pub fn write_range(&self, start: u64, data: impl AsRef<[u8]>) -> Result<()>

Overwrite a sub-range [start, start + data.len()) within this slice in place.

start is relative to self.start().

Requires the set feature.

Errors

Returns io::ErrorKind::InvalidInput if start + data.len() exceeds self.len().

pub fn zero(&self) -> Result<()>

Zero out the entire slice in place.

Requires the set feature.

pub fn zero_range(&self, start: u64, n: u64) -> Result<()>

Zero a sub-range [start, start + n) within this slice in place.

start is relative to self.start().

Requires the set feature.

Errors

Returns io::ErrorKind::InvalidInput if start + n exceeds self.len().

pub fn reader(&self) -> BStackSliceReader<'a, A>

Create a cursor-based reader positioned at the start of this slice.

The reader implements io::Read and io::Seek in the coordinate space [0, self.len()).

pub fn reader_at(&self, offset: u64) -> BStackSliceReader<'a, A>

Create a cursor-based reader positioned at offset bytes into this slice.

offset is relative to self.start(). Seeking past self.len() is allowed; subsequent reads return Ok(0).

pub fn writer(&self) -> BStackSliceWriter<'a, A>

Create a cursor-based writer positioned at the start of this slice.

Requires the set feature.

pub fn writer_at(&self, offset: u64) -> BStackSliceWriter<'a, A>

Create a cursor-based writer positioned at offset bytes into this slice.

offset is relative to self.start(). Writing past self.len() returns Ok(0).

Requires the set feature.

Trait Implementations

impl<'a, A: BStackAllocator> Clone for BStackSlice<'a, A>

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<'a, A: BStackAllocator> Debug for BStackSlice<'a, A>

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

Formats the value using the given formatter.

impl<'a, A: BStackAllocator> From<BStackSlice<'a, A>> for [u8; 16]

Serialize the slice to its 16-byte on-disk representation.

Equivalent to BStackSlice::to_bytes.

fn from(slice: BStackSlice<'a, A>) -> Self

Converts to this type from the input type.

impl<'a, A: BStackAllocator> From<BStackSlice<'a, A>> for BStackSliceReader<'a, A>

Convert a slice into a reader positioned at the start.

Equivalent to BStackSlice::reader.

fn from(slice: BStackSlice<'a, A>) -> Self

Converts to this type from the input type.

impl<'a, A: BStackAllocator> From<BStackSlice<'a, A>> for BStackSliceWriter<'a, A>

Available on crate feature set only.

Convert a slice into a writer positioned at the start.

Equivalent to BStackSlice::writer.

fn from(slice: BStackSlice<'a, A>) -> Self

Converts to this type from the input type.

impl<'a, A: BStackAllocator> From<BStackSliceReader<'a, A>> for BStackSlice<'a, A>

Convert a reader back into its underlying slice, discarding the cursor.

Equivalent to BStackSliceReader::slice.

fn from(reader: BStackSliceReader<'a, A>) -> Self

Converts to this type from the input type.

impl<'a, A: BStackAllocator> From<BStackSliceWriter<'a, A>> for BStackSlice<'a, A>

Available on crate feature set only.

Convert a writer back into its underlying slice, discarding the cursor.

Equivalent to BStackSliceWriter::slice.

fn from(writer: BStackSliceWriter<'a, A>) -> Self

Converts to this type from the input type.

impl<'a, A: BStackAllocator> Hash for BStackSlice<'a, A>

Hashes (offset, len), consistent with PartialEq.

fn hash<H: Hasher>(&self, state: &mut H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl<'a, A: BStackAllocator> Ord for BStackSlice<'a, A>

Slices are ordered by start offset, then by length — consistent with Eq.

fn cmp(&self, other: &Self) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized,

Restrict a value to a certain interval.

impl<'a, A: BStackAllocator> PartialEq<BStackSlice<'a, A>> for BStackSliceReader<'a, A>

fn eq(&self, other: &BStackSlice<'a, A>) -> bool

Tests for self and other values to be equal, and is used by ==.

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

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

impl<'a, A: BStackAllocator> PartialEq<BStackSlice<'a, A>> for BStackSliceWriter<'a, A>

Available on crate feature set only.

fn eq(&self, other: &BStackSlice<'a, A>) -> bool

Tests for self and other values to be equal, and is used by ==.

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

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

impl<'a, A: BStackAllocator> PartialEq<BStackSliceReader<'a, A>> for BStackSlice<'a, A>

fn eq(&self, other: &BStackSliceReader<'a, A>) -> bool

Tests for self and other values to be equal, and is used by ==.

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

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

impl<'a, A: BStackAllocator> PartialEq<BStackSliceWriter<'a, A>> for BStackSlice<'a, A>

Available on crate feature set only.

fn eq(&self, other: &BStackSliceWriter<'a, A>) -> bool

Tests for self and other values to be equal, and is used by ==.

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

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

impl<'a, A: BStackAllocator> PartialEq for BStackSlice<'a, A>

Two slices are equal when their offset and len match.

The allocator is not compared — callers working across allocators should compare start and len explicitly if allocator identity matters.

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

Tests for self and other values to be equal, and is used by ==.

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

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

impl<'a, A: BStackAllocator> PartialOrd<BStackSlice<'a, A>> for BStackSliceReader<'a, A>

fn partial_cmp(&self, other: &BStackSlice<'a, A>) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

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

Tests less than (for self and other) and is used by the < operator.

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

Tests less than or equal to (for self and other) and is used by the <= operator.

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

Tests greater than (for self and other) and is used by the > operator.

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

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl<'a, A: BStackAllocator> PartialOrd<BStackSlice<'a, A>> for BStackSliceWriter<'a, A>

Available on crate feature set only.

fn partial_cmp(&self, other: &BStackSlice<'a, A>) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

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

Tests less than (for self and other) and is used by the < operator.

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

Tests less than or equal to (for self and other) and is used by the <= operator.

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

Tests greater than (for self and other) and is used by the > operator.

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

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl<'a, A: BStackAllocator> PartialOrd<BStackSliceReader<'a, A>> for BStackSlice<'a, A>

fn partial_cmp(&self, other: &BStackSliceReader<'a, A>) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

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

Tests less than (for self and other) and is used by the < operator.

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

Tests less than or equal to (for self and other) and is used by the <= operator.

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

Tests greater than (for self and other) and is used by the > operator.

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

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl<'a, A: BStackAllocator> PartialOrd for BStackSlice<'a, A>

fn partial_cmp(&self, other: &Self) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

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

Tests less than (for self and other) and is used by the < operator.

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

Tests less than or equal to (for self and other) and is used by the <= operator.

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

Tests greater than (for self and other) and is used by the > operator.

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

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl<'a, A> TryInto<BStackSlice<'a, DebugCheckingAllocator<A>>> for DebugHandle<'a, A>

where A: BStackAllocator<Error = Error>,

type Error = Error

The type returned in the event of a conversion error.

fn try_into( self, ) -> Result<BStackSlice<'a, DebugCheckingAllocator<A>>, Self::Error>

Performs the conversion.

impl<'a, A: BStackAllocator> Copy for BStackSlice<'a, A>

impl<'a, A: BStackAllocator> Eq for BStackSlice<'a, A>