Skip to main content

Crate pack_io

Crate pack_io 

Source
Expand description

§pack-io

Compact binary wire format for Rust. Combines speed, schema evolution, and zero-copy deserialization under a single coherent contract.

§At a glance

§Primitive support

Integers (u8 … u128, i8 … i128, usize / isize), bool, f32, f64, String / &str, fixed-size arrays [T; N], tuples of arity 1…12, Option<T>, Result<T, E>, and ().

§Collection support

Vec<T> / &[T], BTreeMap<K, V>, BTreeSet<T>, and (with the default std feature) HashMap<K, V> and HashSet<T>. Hash-based collections encode in canonical key-sorted order so that hashing, signing, or content-addressing the output is safe regardless of insertion order or hash randomisation.

§Stability

The public API and wire format are frozen for the entire 1.x line. Any 1.x decoder reads any 1.x-or-earlier encoding. See the normative spec at docs/WIRE_FORMAT.md and the frozen public surface at docs/API.md.

§Quick start

use pack_io::{encode, decode};

let bytes = encode(&(7_u64, true, String::from("hello"))).unwrap();
let back: (u64, bool, String) = decode(&bytes).unwrap();
assert_eq!(back, (7, true, String::from("hello")));

§Invariants

  • Round-trip integrity — decode(encode(v)) == v for every supported type, under any input.
  • Determinism — the same value always produces the same bytes, regardless of insertion order, platform, or build flags.
  • Safe decode — no panic, no unbounded allocation, no read past the input, on any byte sequence.
  • Wire-format stability — any 1.x decoder reads any 1.x-or-earlier encoding.

§no_std

pack-io is no_std-capable. The default build enables std for the std::error::Error impl, HashMap / HashSet integration, and the io module. Disable the default feature to compile against core + alloc only:

pack-io = { version = "1", default-features = false }

Re-exports§

pub use crate::io::IoDecoder;std
pub use crate::io::IoEncoder;std
pub use crate::io::decode_from;std
pub use crate::io::encode_into;std

Modules§

iostd
std::io::Read / std::io::Write integration: the streaming Tier-2 encoder and decoder pair, plus convenience free functions.

Structs§

Config
Configuration for a decode session.
Decoder
In-memory decoder. Borrows from an input slice and advances a position pointer as values are read. Bounds-checked on every operation.
Encoder
In-memory encoder. Writes into an owned Vec<u8>; the buffer can be reused across encodes by calling Encoder::take to swap it out.

Enums§

SerialError
Every error returned by the codec.

Constants§

VERSION
Semantic version of this crate, as declared in Cargo.toml.

Traits§

Decode
Source that a Deserialize implementation reads its wire-format bytes from.
Deserialize
Types that know how to read themselves from any Decode source.
DeserializeView
Types that decode by borrowing directly from the input slice rather than allocating owned copies.
Encode
Sink that a Serialize implementation writes its wire-format bytes into.
Serialize
Types that know how to write themselves into any Encode sink.

Functions§

decode
Decode a value of type T from bytes, requiring the input to be fully consumed.
decode_view
Decode a borrowed value of type T from bytes, requiring the input to be fully consumed.
encode
Encode value into a freshly allocated Vec<u8>.
peek_version
Peek the schema version of a payload produced by a #[pack_io(version = N)] type without consuming the buffer.

Type Aliases§

Result
Convenience alias for Result<T, SerialError>.

Derive Macros§

Deserializederive
Derive pack_io::Deserialize for a struct or enum (owning decode).
DeserializeViewderive
Derive pack_io::DeserializeView for a struct or enum (zero-copy decode).
Serializederive
Derive pack_io::Serialize for a struct or enum.