Crate byteio

byteio

byteio is a simple crate that exposes lightweight abstractions for read/write operations on contiguous slices of memory.

The crate is based around two core traits: ReadBytes and WriteBytes. Two extension traits which add functionality for reading and writing numbers also have blanket implementations for any types that implement the core traits.

Installation

To start using byteio add it to your Cargo.toml like so:

[dependencies]
byteio = "0.2"

By default this will active the std feature which enables functionality in the crate which is only available when compiling with the standard library.

To use the crate in a no_std environment you just need to disable this feature. This can be done by adjusting your Cargo.toml:

[dependencies]
byteio = { version = "0.2", default-features = false }

The crate has a final feature: alloc. This should be used when you are building in a no_std environment, have an allocator, and want functionality for working with Vec<u8>. You can activate this by adjusting your Cargo.toml again:

[dependencies]
byteio = { version = "0.2", default-features = false, features = ["alloc"] }

Usage

Manual serialization and deserialization of a simple network packet:

use std::convert::TryInto;

use byteio::prelude::*; // ReadBytes, ReadBytesExt, WriteBytes, WriteBytesExt

/// A packet whose payload is encoded as `[n_msb, n_lsb, b_0, b_1, ..., b_n-1]`.
struct Packet<'a> {
   payload: &'a [u8],
}

impl<'a> Packet<'a> {
    fn decode<R: ReadBytes<'a>>(mut reader: R) -> byteio::Result<Self> {
        let len: usize = reader.try_read_u16_be()?.into();
        let payload = reader.try_read_exact(len)?;

        Ok(Self { payload })
    }

    fn encode<W: WriteBytes>(&self, mut writer: W) -> byteio::Result<()> {
        let len: u16 = self.payload.len().try_into().unwrap_or_else(|_| !0);

        writer.try_write_u16_be(len)?;
        writer.try_write_exact(&self.payload[..usize::from(len)])?;

        Ok(())
    }
}

fn main() -> byteio::Result<()> {
    let data = b"\x00\x0Chello, world";

    let packet = Packet::decode(&data[..])?;
    assert_eq!(packet.payload, b"hello, world");

    let mut buf = Vec::new();
    packet.encode(&mut buf)?;
    assert_eq!(&*buf, data);

    Ok(())
}

Modules

prelude

The byteio prelude.

Structs

Reader

A convenience structure used for counting the number of bytes read.

Writer

A convenience structure used for counting the number of bytes written.

Enums

Error

The errors that can occur during byteio operations.

Traits

ReadBytes

Read a slice of bytes from a buffer.

ReadBytesExt

Extends ReadBytes with functions for reading numbers.

WriteBytes

Write a slice of bytes into a buffer.

WriteBytesExt

Extends WriteBytes with functions for writing numbers.

Type Aliases

Result

A specialized Result type for byteio operations.