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 Aliases

ReadResult

A type alias for a Result that returns an Error.

WriteResult

A type alias for a Result that returns an Error.