byteable

Byte-level serialization and deserialization for Rust types.

What is byteable?

byteable gives you two paths for working with binary data:

• Fixed-size path — For types whose byte representation is known at compile time. Derive Byteable and get zero-copy into_byte_array() / from_byte_array() with a compile-time BYTE_SIZE constant. Under the hood this uses #[repr(C, packed)] raw structs and transmute, so no allocation or iteration is involved.

• Dynamic path — For types that contain variable-length data (strings, vecs, maps). Add #[byteable(io_only)] to derive Readable / Writable instead, which stream data through any std::io::Read / Write (or their async tokio equivalents).

Both paths share the same derive macro and attribute syntax, and both produce deterministic, self-describing wire formats.

Installation

[dependencies]
# default: derive macro + std I/O support
byteable = "0.31"

# with async (tokio) support
byteable = { version = "0.31", features = ["tokio"] }

# with ordered-float support
byteable = { version = "0.31", features = ["ordered-float"] }

# everything
byteable = { version = "0.31", features = ["all"] }

Quick Start

Fixed-size struct (zero-copy)

use byteable::{Byteable, IntoByteArray, TryFromByteArray};

#[derive(Byteable)]
struct Point3D {
    x: f32,
    y: f32,
    z: f32,
}

let p = Point3D { x: 1.0, y: 2.0, z: 3.0 };

// Serialize to a fixed-size byte array — no allocation
let bytes: [u8; 12] = p.into_byte_array();

// Deserialize back
let p2 = Point3D::try_from_byte_array(bytes).unwrap();
assert_eq!(p.x, p2.x);

Dynamic struct (I/O streaming)

use byteable::{Byteable, Writable, Readable};
use byteable::io::{WriteValue, ReadValue};

#[derive(Byteable)]
#[byteable(io_only)]
struct Waypoint {
    id: u32,
    label: String,
    tags: Vec<String>,
}

let wp = Waypoint {
    id: 42,
    label: "home".into(),
    tags: vec!["start".into()],
};

let mut buf = Vec::new();
buf.write_value(&wp).unwrap();

let wp2 = std::io::Cursor::new(&buf).read_value::<Waypoint>().unwrap();
assert_eq!(wp.id, wp2.id);
assert_eq!(wp.label, wp2.label);

Controlling endianness

use byteable::Byteable;

#[derive(Byteable)]
#[byteable(big_endian)]          // default for all fields
struct NetworkHeader {
    #[byteable(big_endian)]
    magic: u32,
    #[byteable(little_endian)]   // field-level override
    payload_len: u16,
    version: u8,
}

Feature Flags

Wire Format Reference

Trait Reference

Fixed-size byte-array traits

These traits form the fixed-size serialization pipeline. #[derive(Byteable)] generates impls for all of them automatically.

Raw representation traits

The "raw repr" layer sits between a typed value and its final bytes. It lets the derive macro insert endian wrappers transparently before transmuting.

I/O streaming traits (std feature)

These traits power the #[byteable(io_only)] derive path and the std collection impls.

Extension traits that add ergonomic methods to any reader/writer:

Async I/O traits (tokio feature)

Async counterparts of the sync traits above, backed by tokio::io.

Endianness traits

These traits underpin per-field endian control in the derive macro and the BigEndian<T> / LittleEndian<T> wrapper types.

Low-level traits

Error types

License

MIT — see LICENSE.