1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201
//! Common traits and helper macros for binary encoding and decoding.
//!
//! This crate provides common [`Encode`] and [`Decode`] traits for describing binary encode/decode-able objects, as well as [`#[derive(Encode)]`][encdec_macros::Encode] and [`#[derive(Decode)]`][encdec_macros::Decode] macros to reduce boilerplate when propagating these and little-endian implementations for primitive types.
//! For more implementation see the module-level documentation.
//!
//! This is intended to provide a reusable base for implementing binary encodable objects to match a particular protocol or specification (and mitigate embedded `pub trait (Encode|Decode) {..}` bankruptcy)
//!
//! If you don't need to control the encoded layout directly you might like to look at [serde](https://crates.io/crates/serde), with [postcard](https://crates.io/crates/postcard) for efficient binary encoding between rust components.
//! If you're creating a new protocol for cross-language use you may wish to consider creating a specification using [protocol buffers](https://developers.google.com/protocol-buffers) and [prost](https://crates.io/crates/prost).
//!
#![no_std]
// Re-export base traits
pub use encdec_base::{EncDec, Error};
// Re-export traits from modules here
pub use crate::decode::{Decode, DecodeExt, DecodeOwned};
pub use crate::encode::{Encode, EncodeExt};
pub mod encode {
//! [`Encode`] traits and helper macros
//!
//! ## Example
//! ```
//! # use encdec::{Encode, Decode, Error};
//! #[derive(Debug, PartialEq)]
//! struct Something {
//! a: u8,
//! b: u16,
//! c: [u8; 3],
//! }
//!
//! impl Encode for Something {
//! type Error = Error;
//!
//! /// Fetch encoded length for an encodable object
//! fn encode_len(&self) -> Result<usize, Self::Error> {
//! Ok(1 + 2 + 3)
//! }
//!
//! /// Encode object to the provided buffer,
//! /// returning the encoded length on success
//! fn encode(&self, buff: &mut [u8]) -> Result<usize, Self::Error> {
//! let mut index = 0;
//! buff[index] = self.a;
//! index += 1;
//!
//! buff[1] = self.b as u8;
//! buff[2] = (self.b >> 8) as u8;
//! index += 2;
//!
//! buff[3..][..3].copy_from_slice(&self.c);
//! index += 3;
//!
//! Ok(index)
//! }
//! }
//! ```
pub use encdec_base::encode::*;
pub use crate::derive::Encode;
}
pub mod decode {
//! [`Decode`] traits and helper macros
//!
//! ## Example
//! ```
//! # use encdec::{Encode, DecodeOwned, Error};
//! #[derive(Debug, PartialEq)]
//! struct SomethingOwned {
//! a: u8,
//! b: u16,
//! c: [u8; 3],
//! }
//!
//! /// [`DecodeOwned`] implementation for self-contained types.
//! impl DecodeOwned for SomethingOwned {
//! type Output = Self;
//! type Error = Error;
//!
//! /// Decode object from provided buffer, returning object and decoded
//! /// length on success
//! fn decode_owned(buff: &[u8]) -> Result<(Self::Output, usize), Self::Error> {
//! let mut index = 0;
//!
//! let a = buff[0];
//! index += 1;
//!
//! let b = buff[1] as u16 | (buff[2] as u16) << 8;
//! index += 2;
//!
//! let mut c = [0u8; 3];
//! c.copy_from_slice(&buff[3..][..3]);
//! index += 3;
//!
//! Ok((Self{a, b, c}, index))
//! }
//! }
//! ```
//!
//! ```
//! # use encdec::{Encode, Decode, Error};
//! #[derive(Debug, PartialEq)]
//! struct SomethingBorrowed<'a> {
//! a: u8,
//! l: u16,
//! c: &'a [u8],
//! }
//!
//! /// Base [`Decode`] implementation, lifetime support for views
//! /// into borrowed buffers. If you don't need this, see [`DecodeOwned`].
//! impl <'a>Decode<'a> for SomethingBorrowed<'a> {
//! type Output = SomethingBorrowed<'a>;
//! type Error = Error;
//!
//! /// Decode object from provided buffer, returning object and decoded
//! /// length on success
//! fn decode(buff: &'a [u8]) -> Result<(Self::Output, usize), Self::Error> {
//! let mut index = 0;
//!
//! let a = buff[0];
//! index += 1;
//!
//! // using `l` as the length of `c`
//! let l = buff[1] as u16 | (buff[2] as u16) << 8;
//! index += 2;
//!
//! let c = &buff[index..][..l as usize];
//!
//! Ok((Self{a, l, c}, index))
//! }
//! }
//! ```
pub use encdec_base::decode::*;
pub use crate::derive::{Decode, DecodeOwned};
}
// Re-export macros
pub mod derive {
//! Macros for deriving primitive [`Decode`] and [`Encode`] implementations on types containing decodable/encodable fields.
//!
//! These derivations are _intended_ to be stable, **however**, if you're using these macros to implement a specific protocol you _really should_ write tests to ensure the binary encoding matches your expectations.
//!
//! ## Example
//!
//! Derive macros provide a simple way to implement [`Encode`] and [`Decode`] for objects with (enc|dec)odable fields by (de)serializing each field in order.
//! For detail on derived implementations see the [Encode][encdec_macros::Encode] and [Decode][encdec_macros::Decode] macros.
//!
//! ```
//! # use encdec::{Encode, Decode, Error};
//! #[derive(Debug, PartialEq, Encode, Decode)]
//! struct Something {
//! a: u8,
//! b: u16,
//! c: u8,
//! }
//! # let mut buff = [0u8; 16];
//!
//! let a1 = Something{ a: 0x10, b: 0xabcd, c: 0x11 };
//! let n1 = a1.encode(&mut buff[..]).unwrap();
//!
//! // Encoded data is little endian, ordered by struct field
//! assert_eq!(&buff[..n1], &[0x10, 0xcd, 0xab, 0x11]);
//!
//! let (a2, n2) = Something::decode(&buff[..n1]).unwrap();
//! assert_eq!(a1, a2);
//! ```
//!
//!
//! ## Customisation
//!
//! ### Error Types
//!
//! Derived error types may be overridden with a struct level attribute
//! `#[encdec(error = "E")]` where `E` is a user error type implementing
//! `From<encdec::Error>`
//!
//! ### Encode/Decode methods
//!
//! Field encode/decode methods may be overridden using a field level attribute
//! `#[encdec(with = "M")]` on a field of type `T`, where `M` is a module providing:
//! - `fn enc(&T, &mut [u8]) -> Result<usize, E>`
//! - `fn enc_len(&T) -> Result<usize, E>`
//! - `fn dec(&[u8]) -> Result<(T, usize), E>`
//!
//!
//! Individual methods may be overridden if required using `#[encdec(enc = "..", enc_len = "..", dec = "..")]` with the same type signatures / constraints as above.
pub use encdec_macros::{Decode, DecodeOwned, Encode};
}
// Re-export helpers
pub mod helpers {
//! Helpers for testing encode/decode objects as well as specialised encode/decode impls
pub use encdec_base::helpers::*;
}