Trait Source

Source

pub trait Source: Sealed {
    // Required methods
    fn read_bits(&mut self, n: u32) -> Result<u128, BitError>;
    fn bit_pos(&self) -> usize;

    // Provided methods
    fn byte_order(&self) -> ByteOrder { ... }
    fn bit_order(&self) -> BitOrder { ... }
    fn seek_to_bit(&mut self, _pos: usize) -> Result<(), BitError> { ... }
    fn read<T: Bits>(&mut self) -> Result<T, BitError> { ... }
    fn read_bytes(&mut self, n: usize) -> Result<Vec<u8>, BitError> { ... }
    fn read_into(&mut self, buf: &mut [u8]) -> Result<(), BitError> { ... }
    fn as_read(&mut self) -> SourceReader<'_, Self> ⓘ
       where Self: Sized { ... }
}

Expand description

A bit-level input the codec recurses over. Implemented by BitReader (in-memory slice), StreamBitReader (forward Read), BufSource (a retain-and-seek socket adapter), and SeekReader (Read + Seek); the codec is generic over Source, so one decoder runs over any of them — see guide::io.

§Examples

use bnb::{BitReader, Source, u4};

// A reader generic over any `Source`.
fn first_nibble<S: Source>(s: &mut S) -> u4 { s.read().unwrap() }

let mut r = BitReader::new(&[0xA5]);
assert_eq!(first_nibble(&mut r), u4::new(0xA));

Required Methods§

Source

fn read_bits(&mut self, n: u32) -> Result<u128, BitError>

Reads n (<= 128) bits into the low bits of a u128, in the source’s bit order (MSB-first by default).

§Errors

Propagates the reader’s BitError.

Source

fn bit_pos(&self) -> usize

The current absolute bit offset (for position-aware errors).

Provided Methods§

Source

fn byte_order(&self) -> ByteOrder

The byte order applied to a byte-multiple value (default big-endian).

Source

fn bit_order(&self) -> BitOrder

The bit order this source reads in (default MSB-first). Paired with byte_order to decide whether a byte-multiple value needs its bytes swapped — each bit order has a natural byte layout (big-endian under MSB, little-endian under LSB), and only the opposite declaration swaps.

Source

fn seek_to_bit(&mut self, _pos: usize) -> Result<(), BitError>

Moves the cursor to absolute bit pos. The default — for a forward-only source — fails with ErrorKind::NotSeekable; seekable sources (the slice BitReader) override it. A SeekSource guarantees this works.

§Errors

ErrorKind::NotSeekable unless the source is seekable.

Source

fn read<T: Bits>(&mut self) -> Result<T, BitError>

Reads one Bits value of its declared width, applying the byte order.

§Errors

As read_bits.

Source

fn read_bytes(&mut self, n: usize) -> Result<Vec<u8>, BitError>

Reads n bytes into a fresh Vec (at any bit offset — the bytes need not be aligned). The bulk form of the per-byte read::<u8>() loop, for blob/payload reads in custom codecs and container formats.

n is often attacker-controlled, so nothing is pre-allocated from it: bytes are pushed as they are read, bounded by the input — a hostile huge n against a short source is a fast UnexpectedEof, not an allocation. (An implementation may override with a byte-aligned fast path; the default is the correct-first per-byte loop.)

§Errors

As read_bits.

Source

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

Fills buf with bytes from the source — the no-alloc dual of read_bytes, for fixed scratch buffers and tight no_std paths.

§Errors

As read_bits.

Source

fn as_read(&mut self) -> SourceReader<'_, Self> ⓘ
where Self: Sized,

Available on crate feature std only.

Borrows this source as a std::io::Read over its bytes — for handing the cursor to std::io-based code from a #[br(parse_with = …)] (e.g. a decoder, or a Read-based parser). Reads 8 bits per byte; see SourceReader. Only with the std feature.