Trait Reader 

pub trait Reader<'a> {
    const BORROW_KINDS: u8 = 0;

    // Required method
    fn copy_into_slice(&mut self, dst: &mut [MaybeUninit<u8>]) -> ReadResult<()>;

    // Provided methods
    fn supports_borrow(&self, kind: BorrowKind) -> bool { ... }
    fn take_array<const N: usize>(&mut self) -> ReadResult<[u8; N]> { ... }
    fn take_byte(&mut self) -> ReadResult<u8> { ... }
    fn take_borrowed(&mut self, len: usize) -> ReadResult<&'a [u8]> { ... }
    fn take_borrowed_mut(&mut self, len: usize) -> ReadResult<&'a mut [u8]> { ... }
    fn take_scoped(&mut self, len: usize) -> ReadResult<&[u8]> { ... }
    unsafe fn as_trusted_for(
        &mut self,
        n_bytes: usize,
    ) -> ReadResult<impl Reader<'a>> { ... }
    unsafe fn as_trusted_for_seq(
        &mut self,
        len: usize,
        size: usize,
    ) -> Result<impl Reader<'a>, ReadError> { ... }
    fn by_ref(&mut self) -> impl Reader<'a> { ... }
    unsafe fn copy_into_t<T>(
        &mut self,
        dst: &mut MaybeUninit<T>,
    ) -> ReadResult<()> { ... }
    unsafe fn copy_into_slice_t<T>(
        &mut self,
        dst: &mut [MaybeUninit<T>],
    ) -> ReadResult<()> { ... }
}

Trait for structured reading of bytes from a source into potentially uninitialized memory.

Borrowing semantics

• Only implement Reader::take_borrowed or Reader::take_borrowed_mut for sources where stable borrows into the backing storage are possible.
• Callers should prefer Reader::copy_into_slice or take_* methods to remain compatible with readers that don’t support borrowing, if possible.
• Returns ReadError::UnsupportedBorrow for readers that do not support borrowing.

Provided Associated Constants

const BORROW_KINDS: u8 = 0

Borrow capabilities of this reader.

A bitmask of BorrowKind values indicating which kinds of borrows are supported.

Users of Reader can call Reader::supports_borrow to check if a borrow kind is supported.

Required Methods

fn copy_into_slice(&mut self, dst: &mut [MaybeUninit<u8>]) -> ReadResult<()>

Copy and consume exactly dst.len() bytes from the Reader into dst.

Safety

• dst must not overlap with the internal buffer.

Provided Methods

fn supports_borrow(&self, kind: BorrowKind) -> bool

Checks if this reader supports the given borrow kind.

Examples

let reader = [1, 2, 3, 4, 5];
assert!(reader.as_slice().supports_borrow(BorrowKind::Backing));

let mut reader = [1, 2, 3, 4, 5];
assert!(reader.as_mut_slice().supports_borrow(BorrowKind::BackingMut));

let reader = Cursor::new([1, 2, 3, 4, 5]);
assert!(reader.supports_borrow(BorrowKind::CallSite));
assert!(!reader.supports_borrow(BorrowKind::Backing));

fn take_array<const N: usize>(&mut self) -> ReadResult<[u8; N]>

Return exactly N bytes as [u8; N] and advance by N.

Errors if fewer than N bytes are available.

fn take_byte(&mut self) -> ReadResult<u8>

Return the next byte and advance by 1.

Errors if the reader is exhausted.

fn take_borrowed(&mut self, len: usize) -> ReadResult<&'a [u8]>

Return a borrowed slice of exactly len bytes and advance the reader by len.

The returned slice is tied to the reader’s backing lifetime 'a. This means the slice may outlive the borrow of the call, and is valid after the reader is dropped or reborrowed.

This stronger guarantee is typically only possible for readers backed by stable storage (for example &'a [u8] or memory-mapped buffers).

Prefer Reader::take_scoped unless you specifically require a slice that lives for 'a. Prefer Reader::copy_into_slice if you ultimately intend to copy the slice.

Errors if the reader cannot provide len bytes or does not support borrowing into stable storage that outlives the reader.

fn take_borrowed_mut(&mut self, len: usize) -> ReadResult<&'a mut [u8]>

Return a mutably borrowed slice of exactly len bytes and advance the reader by len.

The returned slice is tied to the reader’s backing lifetime 'a. This means the slice may outlive the borrow of the call, and is valid after the reader is dropped or reborrowed.

This stronger guarantee is typically only possible for readers backed by stable storage (for example &'a mut [u8] or memory-mapped buffers).

Errors if the reader cannot provide len bytes or does not support mutable borrowing into stable, mutable storage that outlives the reader.

fn take_scoped(&mut self, len: usize) -> ReadResult<&[u8]>

Return a call-site scoped slice of exactly len bytes and advance by len.

The returned slice is tied to the borrow of self, meaning it is only valid while the current borrow of the reader is alive. Implementations are free to return slices backed by internal buffers or transient windows into the underlying source.

Prefer Reader::copy_into_slice if you ultimately intend to copy the slice.

Errors for readers that don’t support call-site scoped borrowing.

unsafe fn as_trusted_for( &mut self, n_bytes: usize, ) -> ReadResult<impl Reader<'a>>

Advance the parent by n_bytes and return a Reader that can elide bounds checks within that n_bytes window.

Implementors must:

• Ensure that either at least n_bytes bytes are available backing the returned reader, or return an error.
• Arrange that the returned Trusted reader’s methods operate within that n_bytes window (it may buffer or prefetch arbitrarily).

Note:

• as_trusted_for is intended for callers that know they will operate within a fixed-size window and want to avoid intermediate bounds checks.

Safety

The caller must ensure that, through the returned reader, they do not cause more than n_bytes bytes to be logically read or consumed without performing additional bounds checks.

Concretely:

• The total number of bytes accessed/consumed via the Trusted reader (copy_into_*, take_*, etc.) must be <= n_bytes.

Violating this is undefined behavior, because Trusted readers are permitted to elide bounds checks within the n_bytes window; reading past the n_bytes window may read past the end of the underlying buffer.

unsafe fn as_trusted_for_seq( &mut self, len: usize, size: usize, ) -> Result<impl Reader<'a>, ReadError>

Construct a trusted window for a sequence of length len and serialized element size size.

Always prefer this over manual unchecked arithmetic.

Safety

The caller must ensure that operations through the returned reader do not logically read or consume more than len * size bytes without performing additional bounds checks.

See Reader::as_trusted_for.

fn by_ref(&mut self) -> impl Reader<'a>

Get a mutable reference to the Reader.

Useful in situations where one only has an impl Reader<'de> that needs to be passed to mulitple functions requiring impl Reader<'de>.

Always prefer this over &mut reader to avoid recursive borrows.

struct FooBar {
    foo: u32,
    bar: u32,
}

unsafe impl<'de, C: Config> SchemaRead<'de, C> for FooBar {
    type Dst = Self;

    fn read(mut reader: impl Reader<'de>, dst: &mut MaybeUninit<Self>) -> ReadResult<()> {
        // `reader.by_ref()`; Good ✅
        let foo = <u32 as SchemaRead<'de, C>>::get(reader.by_ref())?;
        let bar = <u32 as SchemaRead<'de, C>>::get(reader)?;
        dst.write(FooBar { foo, bar });
        Ok(())
    }
}

unsafe fn copy_into_t<T>(&mut self, dst: &mut MaybeUninit<T>) -> ReadResult<()>

Copy and consume exactly size_of::<T>() bytes from the Reader into dst.

Safety

• T must be initialized by reads of size_of::<T>() bytes.
• dst must not overlap with the internal buffer.

unsafe fn copy_into_slice_t<T>( &mut self, dst: &mut [MaybeUninit<T>], ) -> ReadResult<()>

Copy and consume exactly dst.len() * size_of::<T>() bytes from the Reader into dst.

Safety

• T must be initialized by reads of size_of::<T>() bytes.
• dst must not overlap with the internal buffer.

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementations on Foreign Types

impl<'a> Reader<'a> for &'a [u8]

const BORROW_KINDS: u8

fn take_borrowed(&mut self, len: usize) -> ReadResult<&'a [u8]>

fn take_scoped(&mut self, len: usize) -> ReadResult<&[u8]>

fn copy_into_slice(&mut self, dst: &mut [MaybeUninit<u8>]) -> ReadResult<()>

fn take_array<const N: usize>(&mut self) -> ReadResult<[u8; N]>

unsafe fn as_trusted_for( &mut self, n_bytes: usize, ) -> ReadResult<impl Reader<'a>>

impl<'a> Reader<'a> for &'a mut [u8]

const BORROW_KINDS: u8

unsafe fn as_trusted_for( &mut self, n_bytes: usize, ) -> ReadResult<impl Reader<'a>>

fn take_borrowed_mut(&mut self, len: usize) -> ReadResult<&'a mut [u8]>

fn take_borrowed(&mut self, len: usize) -> ReadResult<&'a [u8]>

fn take_scoped(&mut self, len: usize) -> ReadResult<&[u8]>

fn copy_into_slice(&mut self, dst: &mut [MaybeUninit<u8>]) -> ReadResult<()>

fn take_array<const N: usize>(&mut self) -> ReadResult<[u8; N]>

impl<'a, R: Reader<'a> + ?Sized> Reader<'a> for &mut R

const BORROW_KINDS: u8 = R::BORROW_KINDS

fn supports_borrow(&self, kind: BorrowKind) -> bool

fn by_ref(&mut self) -> impl Reader<'a>

fn take_array<const N: usize>(&mut self) -> ReadResult<[u8; N]>

fn take_scoped(&mut self, len: usize) -> ReadResult<&[u8]>

fn take_borrowed(&mut self, len: usize) -> ReadResult<&'a [u8]>

fn take_borrowed_mut(&mut self, len: usize) -> ReadResult<&'a mut [u8]>

fn take_byte(&mut self) -> ReadResult<u8>

unsafe fn as_trusted_for( &mut self, n_bytes: usize, ) -> ReadResult<impl Reader<'a>>

unsafe fn as_trusted_for_seq( &mut self, len: usize, size: usize, ) -> Result<impl Reader<'a>, ReadError>

fn copy_into_slice(&mut self, dst: &mut [MaybeUninit<u8>]) -> ReadResult<()>

unsafe fn copy_into_t<T>(&mut self, dst: &mut MaybeUninit<T>) -> ReadResult<()>

unsafe fn copy_into_slice_t<T>( &mut self, dst: &mut [MaybeUninit<T>], ) -> ReadResult<()>

impl<'a, T> Reader<'a> for Cursor<T>

where T: AsRef<[u8]>,

Available on crate feature std only.

const BORROW_KINDS: u8

fn copy_into_slice(&mut self, dst: &mut [MaybeUninit<u8>]) -> ReadResult<()>

fn take_array<const N: usize>(&mut self) -> ReadResult<[u8; N]>

fn take_scoped(&mut self, len: usize) -> ReadResult<&[u8]>

unsafe fn as_trusted_for( &mut self, n_bytes: usize, ) -> ReadResult<impl Reader<'a>>

impl<R: Read + ?Sized> Reader<'_> for BufReader<R>

Available on crate feature std only.

fn copy_into_slice(&mut self, dst: &mut [MaybeUninit<u8>]) -> ReadResult<()>

Implementors

impl<'a> Reader<'a> for SliceMutUnchecked<'a, u8>

const BORROW_KINDS: u8

impl<'a> Reader<'a> for SliceScopedUnchecked<'a, '_, u8>

const BORROW_KINDS: u8

impl<'a> Reader<'a> for SliceUnchecked<'a, u8>

const BORROW_KINDS: u8

impl<'a, T> Reader<'a> for wincode::io::Cursor<T>

where T: AsRef<[u8]>,

const BORROW_KINDS: u8

impl<R: Read + ?Sized> Reader<'_> for ReadAdapter<R>

Available on crate feature std only.