Struct pigeon::Writer

pub struct Writer<T: Target> { /* fields omitted */ }

A type which can be used for writing to a type that implements Target.

Implementations

impl<T: Target> Writer<T>

pub fn new(buf: T) -> Writer<T>

Create a new Writer from a type implementing Target.

Examples

let mut buf = [0; 8];
let mut writer = Writer::new(&mut buf[..]);

writer.write(12u8).unwrap();
writer.write(24u8).unwrap();
writer.write(554u16).unwrap();
writer.write(12345678u32).unwrap();

writer.finish();

assert_eq!(buf[0], 12);
assert_eq!(buf[1], 24);
assert_eq!(u16::from_be_bytes(buf[2..4].try_into().unwrap()), 554);
assert_eq!(u32::from_be_bytes(buf[4..8].try_into().unwrap()), 12345678);

pub fn bit_offset(&self) -> u8

Get the bit offset that the writer is at.

This is 0 when the writer is aligned.

Examples

let mut buf = [0; 2];
let mut writer = Writer::new(&mut buf[..]);

assert_eq!(writer.bit_offset(), 0);
writer.write_u8_bits(1, 0xFF).unwrap();
assert_eq!(writer.bit_offset(), 1);
writer.write_u8_bits(4, 0x00).unwrap();
assert_eq!(writer.bit_offset(), 5);
writer.write_u8_bits(5, 0xFF).unwrap();
assert_eq!(writer.bit_offset(), 2);
writer.write_u8_bits(8, 0xAA).unwrap();
assert_eq!(writer.bit_offset(), 2);

pub fn position(&self) -> usize

Get the position of the Writer in its buffer.

This rounds upwards, so, for example, if you're at position 3 bytes and 2 bits, this will return 4.

Examples

let mut buf = [0; 10];
let mut writer = Writer::new(&mut buf[..]);

assert_eq!(writer.position(), 0);

writer.write(0u8).unwrap();

assert_eq!(writer.position(), 1);

writer.write(0u16).unwrap();

assert_eq!(writer.position(), 3);

writer.write_u8_bits(3, 0x05).unwrap();

assert_eq!(writer.position(), 4);

writer.write_bytes(b"coucou").unwrap();

assert_eq!(writer.position(), 10);

pub fn write_u8(&mut self, byte: u8) -> Result<()>

Write a byte.

Position

This advances the writer only if the write succeeds.

No data will be written if the write does not succeed.

Returns

On success, this returns Ok(()).

If there is not enough space to write the whole buffer, this returns Err(Error::UnexpectedEof).

Examples

let mut buf = [0; 4];
let mut writer = Writer::new(&mut buf[..]);

writer.write_u8(0b1011_0101).unwrap();
writer.write_u8_bits(1, 0b0000_0001).unwrap();
writer.write_u8(0b1100_1010).unwrap();
writer.write_u8_bits(5, 0b0001_0111).unwrap();
writer.write_u8(0b0110_1001).unwrap();

assert!(writer.write_u8(0x00).is_err());

writer.finish();

assert_eq!(&buf[..], &[0b1011_0101, 0b1110_0101, 0b0101_1101, 0b1010_0100]);

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

Write the bits_count least significant bits of a byte.

Position

This advances the writer only if the write succeeds.

No data will be written if the write does not succeed.

Returns

On success, this returns Ok(()).

If there is not enough space to write the whole buffer, this returns Err(Error::UnexpectedEof).

Panics

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

Examples

let mut buf = [0; 3];
let mut writer = Writer::new(&mut buf[..]);

writer.write_u8_bits(4, 0b0000_1010).unwrap();
writer.write_u8_bits(1, 0b0000_0001).unwrap();
writer.write_u8_bits(7, 0b0011_1100).unwrap();
writer.write_u8_bits(4, 0b0000_1100).unwrap();
writer.write_u8_bits(3, 0b0000_0101).unwrap();
writer.write_u8_bits(5, 0b0001_1011).unwrap();

assert!(writer.write_u8_bits(1, 0x00).is_err());

writer.finish();

assert_eq!(&buf[..], &[0b1010_1011, 0b1100_1100, 0b1011_1011]);

pub fn pad_align(&mut self)

Pad until aligned.

Position

This advances the position by either 0 or 1, depending on whether the writer was aligned.

Examples

let mut buf = [0; 3];
let mut writer = Writer::new(&mut buf[..]);

writer.pad_align();
writer.write_u8_bits(2, 0xFF).unwrap();
writer.pad_align();
writer.write_u8_bits(4, 0xFF).unwrap();
writer.pad_align();
writer.write_u8_bits(8, 0xFF).unwrap();
writer.pad_align();

writer.finish();

assert_eq!(&buf[..], &[0xC0, 0xF0, 0xFF]);

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

Write a byte slice into the Writer at the current offset.

Position

This advances the writer only if the write succeeds.

No data will be written if the write does not succeed.

Returns

On success, this returns Ok(()). If there is not enough space to write the whole buffer, this returns Err(Error::UnexpectedEof).

Examples

let mut buf = [0; 13];
let mut writer = Writer::new(&mut buf[..]);

writer.write_bytes(b"Hello, world!").unwrap();

assert!(writer.write_bytes(b"Hewwo").is_err());

writer.finish();

assert_eq!(&buf, b"Hello, world!");

pub fn write<D: Pack>(&mut self, data: D) -> Result<()>

Write a type implementing Pack into the Writer at the current offset.

Position

This advances the writer only if all the underlying writes succeed.

On failure, there may be incomplete data written to the buffer, the writer's position will not include that data.

Returns

On success, this returns an Ok(()). If there is not enough space to write all the data, this returns Err(Error::UnexpectedEof).

Examples

let mut buf = [0; 6];
let mut writer = Writer::new(&mut buf[..]);

writer.write(4242u16).unwrap();
writer.write(56789u32).unwrap();

writer.finish();

assert_eq!(&buf[..], &[16, 146, 0, 0, 221, 213]);

pub fn fits<D: Pack>(&mut self, data: D) -> bool

Check whether a type implementing Pack fits into the rest of the buffer.

Examples

let mut buf = [0; 4];
let mut writer = Writer::new(&mut buf[..]);

assert!(writer.fits(0u32));
assert!(!writer.fits(0u64));

writer.write(0u8).unwrap();

assert!(writer.fits(0u16));
assert!(!writer.fits(0u32));

writer.write(0u16).unwrap();

assert!(writer.fits(0u8));
assert!(!writer.fits(0u16));

writer.write(0u8).unwrap();

assert!(!writer.fits(0u8));

pub fn fits_bytes(&mut self, bytes: &[u8]) -> bool

Check whether a byteslice can fit into the buffer.

Examples

let mut buf = [0; 4];
let mut writer = Writer::new(&mut buf[..]);

assert!(writer.fits_bytes(b"hewo"));
assert!(!writer.fits_bytes(b"hallo, iedereen!"));

writer.write_bytes(b"mew").unwrap();

assert!(writer.fits_bytes(&[12]));
assert!(!writer.fits_bytes(b"hewo"));

pub fn fits_bytes_count(&mut self, count: usize) -> bool

Check whether an amount of bytes can fit into the buffer.

Examples

let mut buf = [0; 4];
let mut writer = Writer::new(&mut buf[..]);

assert!(writer.fits_bytes_count(4));
assert!(!writer.fits_bytes_count(5));

writer.write_bytes(b"mew").unwrap();

assert!(writer.fits_bytes_count(1));
assert!(!writer.fits_bytes_count(4));

pub fn with(
    buf: T,
    cb: impl FnOnce(&mut Writer<T>) -> Result<()>
) -> Result<usize>

Create a Writer on a buffer and pass it into a closure.

This will implicitly finalize the inner writer.

Position

This advances the writer only if all the underlying writes succeed.

On failure, there may be incomplete data written to the buffer, the writer's position will not include that data.

Returns

On success, this returns an Ok with the amount of bytes written. If there is not enough space to write all the data, this returns Err(Error::UnexpectedEof).

Examples

let mut buf = [0; 32];

let size = Writer::with(&mut buf[..], |writer| {
    writer.write(U4(0x1))?;
    writer.write(0x23u8)?;
    writer.write(U4(0x4))?;
    Ok(())
}).unwrap();

assert_eq!(&buf[0..size], &[0x12, 0x34]);

pub fn finish(self) -> Result<usize>

Finalize writing. This will flush the bit buffer if the writer is not aligned.

Returns

This returns the amount of bytes that were written to.

Currently, this cannot fail, but it might have failure modes in the future.

Examples

let mut buf = [0; 32];

let mut writer = Writer::new(&mut buf[..]);

writer.write_bytes(&[0xAB, 0xCD, 0xEF]).unwrap();
writer.write_u8_bits(5, 0x0E).unwrap();

let len = writer.finish().unwrap();

assert_eq!(len, 4);

Trait Implementations

impl<T: Debug + Target> Debug for Writer<T>

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

Formats the value using the given formatter.