Struct pigeon::Reader

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

A type that can be used to read from a buffer.

Implementations

impl<'a> Reader<'a>

pub fn new(buf: &'a [u8]) -> Reader<'a>

Create a new Reader from a buffer.

Examples

let buf = [0, 1, 2, 3];
let mut reader = Reader::new(&buf[..]);
let a = reader.read::<u8>().unwrap();
let b = reader.read::<u16>().unwrap();
let c = reader.read::<u8>().unwrap();
assert_eq!(a, 0);
assert_eq!(b, 258);
assert_eq!(c, 3);
assert!(reader.read::<u8>().is_err());

pub fn position(&self) -> usize

Get the position of the Reader in the buffer.

Examples

let buf = [0; 16];
let mut reader = Reader::new(&buf[..]);
assert_eq!(reader.position(), 0);
reader.read_bytes(2).unwrap();
assert_eq!(reader.position(), 2);
reader.read_bytes(5).unwrap();
assert_eq!(reader.position(), 7);
reader.read::<u32>().unwrap();
assert_eq!(reader.position(), 11);
reader.read::<u8>().unwrap();
assert_eq!(reader.position(), 12);
reader.read::<u32>().unwrap();
assert_eq!(reader.position(), 16);

pub fn skip_align(&mut self)

Skip bits until the reader is aligned to a byte boundary.

Position

This will advance the position by 1 if the reader is currently unaligned.

Examples

let buf = [0xF0, 0x0F, 0xFF];
let mut reader = Reader::new(&buf[..]);
reader.skip_align();
assert_eq!(reader.read_u8_bits(4).unwrap(), 0x0F);
reader.skip_align();
assert_eq!(reader.read_u8().unwrap(), 0x0F);
reader.skip_align();
assert_eq!(reader.read_u8_bits(4).unwrap(), 0x0F);
reader.skip_align();
assert!(reader.read_u8_bits(2).is_err());

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

Try to read a byte from the buffer.

Position

This will only advance the position if the read succeeds.

Returns

On success, this returns Ok with a slice of the bytes read. If there are not enough bytes remaining in the buffer, this returns Err(Error::UnexpectedEof).

Examples

let buf = [0x42, 0xFF, 0x0F];
let mut reader = Reader::new(&buf[..]);
assert_eq!(reader.read_u8().unwrap(), 0x42);
assert_eq!(reader.read_u8_bits(4).unwrap(), 0x0F);
assert_eq!(reader.read_u8().unwrap(), 0xF0);
assert!(reader.read_u8().is_err());

pub fn read_u8_bits(&mut self, bits_count: u8) -> Result<u8>

Try to read bits_count bits from the buffer, where bits_count is assumed to be less than or equal to 8.

Position

This will only advance the position if the read succeeds.

Returns

On success, this returns Ok with a u8. If there are not enough bytes remaining in the buffer, this returns Err(Error::UnexpectedEof).

Panics

This panics if bits_count is less than 1 or greater than 8.

Examples

let buf = [0xF0, 0x0F, 0x0F];
let mut reader = Reader::new(&buf[..]);
assert_eq!(reader.read_u8_bits(4).unwrap(), 0x0F);
assert_eq!(reader.read_u8_bits(8).unwrap(), 0x00);
assert_eq!(reader.read_u8_bits(4).unwrap(), 0x0F);
assert_eq!(reader.read_u8_bits(8).unwrap(), 0x0F);
assert!(reader.read_u8_bits(2).is_err());

pub fn read_bytes(&mut self, len: usize) -> Result<UnalignedSlice<'a>>

Try to read len bytes from the buffer.

Position

This will only advance the position if the read succeeds.

Returns

On success, this returns Ok with a slice of the bytes read. If there are not enough bytes remaining in the buffer, this returns Err(Error::UnexpectedEof).

Examples

let buf = [0, 1, 2, 3, 4, 5];
let mut reader = Reader::new(&buf[..]);
let bytes_a = reader.read_bytes(3).unwrap();
assert_eq!(bytes_a, &[0, 1, 2][..]);
let bytes_b = reader.read_bytes(2).unwrap();
assert_eq!(bytes_b, &[3, 4][..]);
assert!(reader.read_bytes(2).is_err());

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

Try to read buf.len() bytes into buf.

Position

This will only advance the position if the read succeeds.

Returns

On success, this returns Ok(()) and the buffer will be filled with the read data. If there are not enough bytes remaining in the buffer, this returns Err(Error::UnexpectedEof).

Examples

let buf = [0, 1, 2, 3, 4, 5];
let mut reader = Reader::new(&buf[..]);
let mut target = [0; 4];
reader.read_bytes_to(&mut target[..]).unwrap();
assert_eq!(&target[..4], &buf[..4]);
assert!(reader.read_bytes_to(&mut target[..]).is_err());

pub fn read<U: Unpack<'a>>(&mut self) -> Result<U>

Try to read an instance of a type implementing Unpack.

Position

This will advance the position only if all of the inner reads have succeeded.

Returns

On success, this returns Ok with an instance of U inside it. On failure, this returns Err.

Examples

let buf = [0, 1, 2, 3, 4, 5, 6];
let mut reader = Reader::new(&buf[..]);
let a: u32 = reader.read().unwrap();
assert_eq!(a, 66051);
let b: u8 = reader.read().unwrap();
assert_eq!(b, 4);
assert!(reader.read::<u32>().is_err());
let c: u16 = reader.read().unwrap();
assert_eq!(c, 1286);
assert!(reader.read::<u8>().is_err());

pub fn expect<U: Unpack<'a> + PartialEq>(&mut self, expected: U) -> Result<()>

Try to read an instance of a type implementing Unpack, and compare it to expected.

Position

This will advance the position if the read succeeded but doesn't match the expected value, but in all other cases it will not advance the position.

Returns

On success, returns Ok(()). When the read succeeds, but the values do not match, returns Err(Error::UnexpectedData). On an underlying failure, returns Err(_).

Examples

let buf = [0, 1, 2, 3, 4, 5, 5, 6];
let mut reader = Reader::new(&buf[..]);
reader.expect(66051u32).unwrap();
reader.expect(4u8).unwrap();
assert_eq!(reader.expect(4u8), Err(ReadError::UnexpectedData));
assert_eq!(reader.expect(12345678u32), Err(ReadError::UnexpectedEof));
reader.expect(1286u16).unwrap();

pub fn with<T>(
    buf: &'a [u8],
    cb: impl FnOnce(&mut Reader<'a>) -> Result<T>
) -> Result<T>

Create a Reader on a buffer and pass it into a closure, returning what the closure returns.

Examples

let buf = [0, 1, 2, 3, 4, 5, 6];
let value = Reader::with(&buf[..], |reader| {
    let a: u32 = reader.read()?;
    let b: u16 = reader.read()?;
    let c: u8 = reader.read()?;
    Ok((a, b, c))
}).unwrap();
assert_eq!(value, (66051, 1029, 6));

Trait Implementations

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

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

Formats the value using the given formatter.