commonware_codec/
lib.rs

1//! Serialize structured data.
2//!
3//! # Overview
4//!
5//! A binary serialization library designed to efficiently and safely:
6//! - Serialize structured data into a binary format
7//! - Deserialize untrusted binary input into structured data
8//!
9//! # Supported Types
10//!
11//! Natively supports:
12//! - Primitives: `u8`, `u16`, `u32`, `u64`, `i8`, `i16`, `i32`, `i64`, `f32`, `f64`, `bool`
13//! - Collections: `Vec<T>`, `Option<T>`, tuples, and fixed-size arrays like `[u8; N]`
14//! - Recursive serialization of nested structs and enums via trait implementations
15//!
16//! User-defined types can be serialized and deserialized by implementing the `Codec` trait.
17//! For types with a constant encoded size, optionally implement the `SizedCodec` trait.
18//!
19//! # Example
20//!
21//! ```
22//! use bytes::{Buf, BufMut};
23//! use commonware_codec::{Codec, Error};
24//!
25//! // Define a custom struct
26//! #[derive(Debug, Clone, PartialEq)]
27//! struct Point {
28//!     xy: (u64, u64),
29//!     z: Option<u32>,
30//!     metadata: [u8; 11],
31//! }
32//!
33//! // Implement the Codec trait
34//! impl Codec for Point {
35//!     fn write(&self, buf: &mut impl BufMut) {
36//!         // Basic types can be written by inferring the type
37//!         self.xy.write(buf);
38//!         self.z.write(buf);
39//!         self.metadata.write(buf);
40//!     }
41//!
42//!     fn read(buf: &mut impl Buf) -> Result<Self, Error> {
43//!         // Basic types can be inferred by the return type
44//!         let xy = <(u64, u64)>::read(buf)?;
45//!         let z = <Option<u32>>::read(buf)?;
46//!         let metadata = <[u8; 11]>::read(buf)?;
47//!         Ok(Self { xy, z, metadata })
48//!     }
49//!
50//!     fn len_encoded(&self) -> usize {
51//!       self.xy.len_encoded() + self.z.len_encoded() + self.metadata.len_encoded()
52//!     }
53//! }
54//! ```
55
56pub mod codec;
57pub mod error;
58pub mod types;
59pub mod util;
60pub mod varint;
61
62// Re-export main types and traits
63pub use codec::{Codec, SizedCodec};
64pub use error::Error;
65pub use types::{net, primitives};