Crate pigeon

A crate for reading/writing from/to byte buffers.

This crate uses big-endian for all numbers.

Usage Example

use {
    pigeon::{
        Writer,
        Reader,
        Target,
        Unpack,
        Pack,
        WriteResult,
        ReadResult,
        ReadError,
        U3,
        U5,
    },
};

#[derive(Debug, PartialEq)]
pub struct Animal {
    pub position: (u8, u8, u8),
    pub fluffy: bool,
    pub name: String,
    pub weight: f32,
}

impl Pack for Animal {
    fn pack<T: Target>(&self, writer: &mut Writer<T>) -> WriteResult<()> {
        writer.write((U3(self.position.0), U3(self.position.1), U3(self.position.2)))?;
        writer.write(self.fluffy)?;
        let name_bytes = self.name.as_bytes();
        writer.write(U5(name_bytes.len() as u8))?;
        writer.write_bytes(name_bytes)?;
        writer.write(self.weight)?;
        Ok(())
    }
}

impl<'a> Unpack<'a> for Animal {
    fn unpack(reader: &mut Reader<'a>) -> ReadResult<Self> {
        let (U3(x), U3(y), U3(z)) = reader.read()?;
        let position = (x, y, z);
        let fluffy = reader.read()?;
        let U5(name_len_u8) = reader.read()?;
        let name_len = name_len_u8 as usize;
        let name_bytes_unaligned = reader.read_bytes(name_len)?;
        let mut name_bytes = [0; 256];
        name_bytes_unaligned.copy_to_slice(&mut name_bytes[0..name_len]);
        let name = String::from_utf8(name_bytes[0..name_len].to_vec()).map_err(|_| ReadError::UnexpectedData)?;
        let weight = reader.read()?;
        Ok(Animal {
            position,
            fluffy,
            name: name.to_owned(),
            weight,
        })
    }
}

let kitty = Animal {
    position: (3, 2, 7),
    fluffy: true,
    name: "Joseph Joestar".to_owned(),
    weight: 12.,
};

let mut buf = [0; 128];

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

writer.write(&kitty).unwrap();

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

let mut reader = Reader::new(&buf[..len]);

let kitty_: Animal = reader.read().unwrap();

assert_eq!(kitty, kitty_);

Structs

Iter	An iterator over the bytes in an UnalignedSlice.
Reader	A type that can be used to read from a buffer.
U1	Adapter for reading/writing a single bit.
U2	Adapter for reading/writing a 2-bit unsigned integer.
U3	Adapter for reading/writing a 3-bit unsigned integer.
U4	Adapter for reading/writing a 4-bit unsigned integer.
U5	Adapter for reading/writing a 5-bit unsigned integer.
U6	Adapter for reading/writing a 6-bit unsigned integer.
U7	Adapter for reading/writing a 7-bit unsigned integer.
UnalignedSlice	A byte slice which is not aligned, but does contain a whole number of bytes.
Writer	A type which can be used for writing to a type that implements Target.

Enums

ReadError	An error which can be emitted when a read fails.
WriteError	An error which can be emitted when a write fails.

Traits

Pack	Types which can get written to a Writer.
Target	A type which can be written to by a Writer.
Unpack	Types which can get read from a Reader.

Functions

pack_buffer	Pack the type to a buffer directly.
unpack_buffer	Read a type which implement Unpack from the buffer.

Type Definitions

ReadResult	A type alias for a Result that returns an Error.
WriteResult	A type alias for a Result that returns an Error.