Struct Reader 

pub struct Reader<'a> { /* private fields */ }

A cursor that reads ABI values out of a byte slice.

The reader borrows its input and hands back borrowed slices, so decoding a record does not allocate and does not copy the payload.

Implementations

impl Reader<'_>

pub fn capability_set(&mut self) -> Result<CapabilitySet>

Reads a length-prefixed capability set.

Errors

Returns the same errors as Reader::var_bytes.

impl<'a> Reader<'a>

pub fn message(&mut self) -> Result<Message<'a>>

Reads the next record and decodes it.

An unrecognised tag comes back as Message::Unknown rather than an error, and the reader is left pointing at the record after it. That is the extension point: adding a record to the ABI does not break anything that was compiled before it existed.

Errors

Returns Error::Truncated if the buffer ends inside the record, or whatever the individual record’s decoder returns.

impl<'a> Reader<'a>

pub fn record(&mut self) -> Result<(Header, Reader<'a>)>

Reads a record header and returns a reader over just that record’s payload.

The outer reader is left pointing at the next record, past the payload and its padding, so a caller that does not care about this record can simply drop the payload reader.

Errors

Returns Error::Truncated if the header or the payload runs off the end, or Error::LengthOverflow if the declared length does not fit in a usize.

impl<'a> Reader<'a>

pub const fn new(buf: &'a [u8]) -> Self

Starts reading at the beginning of buf.

pub const fn remaining(&self) -> usize

How many bytes are left.

pub const fn is_empty(&self) -> bool

Whether the reader has consumed everything.

pub const fn position(&self) -> usize

How far into the buffer the cursor is.

pub fn u8(&mut self) -> Result<u8>

Reads one byte.

Errors

Returns Error::Truncated if the buffer is exhausted.

pub fn u16(&mut self) -> Result<u16>

Reads a little-endian u16.

Errors

Returns Error::Truncated if fewer than two bytes are left.

pub fn u32(&mut self) -> Result<u32>

Reads a little-endian u32.

Errors

Returns Error::Truncated if fewer than four bytes are left.

pub fn u64(&mut self) -> Result<u64>

Reads a little-endian u64.

Errors

Returns Error::Truncated if fewer than eight bytes are left.

pub fn opt_u64(&mut self) -> Result<Option<u64>>

Reads a u64 that a later version of a record appended, if the writer knew about it.

This is the other half of the grow-at-the-end rule. A reader that does not care about a new field just stops early and the framing puts it on the next record. A reader that does care has to tell two situations apart: a writer that predates the field, which is fine and means the field is absent, and a payload that was cut in half, which is not fine. Nothing left is the first, something but not enough is the second.

Errors

Returns Error::Truncated if there is at least one byte left but fewer than eight.

pub fn bytes(&mut self, n: usize) -> Result<&'a [u8]>

Reads exactly n bytes and borrows them from the input.

Errors

Returns Error::Truncated if fewer than n bytes are left.

pub fn skip(&mut self, n: usize) -> Result<()>

Skips n bytes.

This is how a reader gets past a field it does not understand, which is the whole reason the format carries lengths.

Errors

Returns Error::Truncated if fewer than n bytes are left.

pub fn align(&mut self) -> Result<()>

Skips forward to the next alignment boundary.

Errors

Returns Error::Truncated if the padding runs off the end of the buffer.

pub fn var_bytes(&mut self) -> Result<&'a [u8]>

Reads a length-prefixed byte string, including its trailing padding.

Errors

Returns Error::Truncated if the buffer ends inside the field, or Error::LengthOverflow if the declared length does not fit in a usize.

pub fn var_str(&mut self) -> Result<&'a str>

Reads a length-prefixed UTF-8 string.

Errors

Returns Error::NotUtf8 if the bytes are not valid UTF-8, or the same errors as Reader::var_bytes.

pub fn sub(&mut self, n: usize) -> Result<Reader<'a>>

Splits off a reader over the next n bytes and steps this one past them.

Errors

Returns Error::Truncated if fewer than n bytes are left.

Trait Implementations

impl<'a> Clone for Reader<'a>

fn clone(&self) -> Reader<'a>

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<'a> Debug for Reader<'a>

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

Formats the value using the given formatter.