Trait Reader 

pub trait Reader<'a> {
    type Trusted<'b>: Reader<'a>
       where Self: 'b;

    // Required methods
    fn fill_buf(&mut self, n_bytes: usize) -> ReadResult<&[u8]>;
    unsafe fn consume_unchecked(&mut self, amt: usize);
    fn consume(&mut self, amt: usize) -> ReadResult<()>;
    unsafe fn as_trusted_for(
        &mut self,
        n_bytes: usize,
    ) -> ReadResult<Self::Trusted<'_>>;

    // Provided methods
    fn fill_exact(&mut self, n_bytes: usize) -> ReadResult<&[u8]> { ... }
    fn fill_array<const N: usize>(&mut self) -> ReadResult<&[u8; N]> { ... }
    fn borrow_exact(&mut self, len: usize) -> ReadResult<&'a [u8]> { ... }
    fn borrow_exact_mut(&mut self, len: usize) -> ReadResult<&'a mut [u8]> { ... }
    fn peek(&mut self) -> ReadResult<&u8> { ... }
    fn by_ref(&mut self) -> impl Reader<'a> { ... }
    fn copy_into_slice(&mut self, dst: &mut [MaybeUninit<u8>]) -> ReadResult<()> { ... }
    fn copy_into_array<const N: usize>(
        &mut self,
        dst: &mut MaybeUninit<[u8; N]>,
    ) -> 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<()> { ... }
}

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

Advancement semantics

• fill_* methods never advance.
• copy_into_* and borrow_* methods advance by the number of bytes read.
• Reader::as_trusted_for advances the parent by the number of bytes requested.

Zero-copy semantics

Only implement Reader::borrow_exact for sources where stable borrows into the backing storage are possible. Callers should prefer Reader::fill_exact to remain compatible with readers that don’t support zero-copy. Returns ReadError::UnsupportedZeroCopy for readers that do not support zero-copy.

Required Associated Types

type Trusted<'b>: Reader<'a> where Self: 'b

A variant of the Reader that can elide bounds checking within a given window.

Trusted variants of the Reader should generally not be constructed directly, but rather by calling Reader::as_trusted_for on a trusted Reader. This will ensure that the safety invariants are upheld.

Required Methods

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

Return up to n_bytes from the internal buffer without advancing. Implementations may read more data internally to satisfy future requests. Returns fewer than n_bytes at EOF.

This is not required to return exactly n_bytes, it is required to return up to n_bytes. Use Reader::fill_exact if you need exactly n_bytes.

unsafe fn consume_unchecked(&mut self, amt: usize)

Advance by exactly amt bytes without bounds checks.

May panic if fewer than amt bytes remain.

Safety

• amt must be less than or equal to the number of bytes remaining in the reader.

fn consume(&mut self, amt: usize) -> ReadResult<()>

Advance the reader exactly amt bytes, returning an error if the source does not have enough bytes.

unsafe fn as_trusted_for( &mut self, n_bytes: usize, ) -> ReadResult<Self::Trusted<'_>>

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.
• If you simply want to advance the parent by n_bytes without using a trusted window, prefer consume(n_bytes) instead.

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 (fill_*, copy_into_*, consume, 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.

Provided Methods

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

Return exactly n_bytes without advancing.

Errors if the source cannot provide enough bytes.

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

Return exactly N bytes as &[u8; N] without advancing.

Errors if fewer than N bytes are available.

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

Zero-copy: return a borrowed slice of exactly len bytes and advance by len.

The returned slice is tied to 'a. Prefer Reader::fill_exact unless you truly need zero-copy. Errors for readers that don’t support zero-copy.

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

Zero-copy: return a borrowed mutable slice of exactly len bytes and advance by len.

Errors for readers that don’t support zero-copy.

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

Return a reference to the next byte without advancing.

May buffer more bytes if necessary. Errors if no bytes remain.

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(())
    }
}

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.

fn copy_into_array<const N: usize>( &mut self, dst: &mut MaybeUninit<[u8; N]>, ) -> ReadResult<()>

Copy and consume exactly N bytes from the Reader into dst.

Safety

• dst must not overlap with the internal buffer.

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]

type Trusted<'b> = TrustedSliceReaderZeroCopy<'a> where Self: 'b

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

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

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

unsafe fn consume_unchecked(&mut self, amt: usize)

fn consume(&mut self, amt: usize) -> ReadResult<()>

unsafe fn as_trusted_for(&mut self, n: usize) -> ReadResult<Self::Trusted<'_>>

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

type Trusted<'b> = TrustedSliceReaderZeroCopyMut<'a> where Self: 'b

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

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

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

unsafe fn consume_unchecked(&mut self, amt: usize)

fn consume(&mut self, amt: usize) -> ReadResult<()>

unsafe fn as_trusted_for(&mut self, n: usize) -> ReadResult<Self::Trusted<'_>>

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

type Trusted<'b> = <R as Reader<'a>>::Trusted<'b> where Self: 'b

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

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

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

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

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

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

unsafe fn consume_unchecked(&mut self, amt: usize)

fn consume(&mut self, amt: usize) -> ReadResult<()>

unsafe fn as_trusted_for( &mut self, n_bytes: usize, ) -> ReadResult<Self::Trusted<'_>>

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

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

fn copy_into_array<const N: usize>( &mut self, dst: &mut MaybeUninit<[u8; N]>, ) -> 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<()>

Implementors

impl<'a> Reader<'a> for TrustedSliceReader<'a, '_>

type Trusted<'c> = TrustedSliceReader<'a, '_> where Self: 'c

impl<'a> Reader<'a> for TrustedSliceReaderZeroCopy<'a>

type Trusted<'b> = TrustedSliceReaderZeroCopy<'a> where Self: 'b

impl<'a> Reader<'a> for TrustedSliceReaderZeroCopyMut<'a>

type Trusted<'b> = TrustedSliceReaderZeroCopyMut<'a> where Self: 'b

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

where T: AsRef<[u8]>,

type Trusted<'b> = TrustedSliceReader<'a, 'b> where Self: 'b