Crate serde_brief 

Serde-Brief

Serde-Brief (German for letter) is a crate for encoding and decoding data into a binary format that is self-descriptive and serde-compatible.

Design Goals

Not necessarily in order of importance:

• Convenient to use for developers: Integrates into the Rust ecosystem via serde, supporting all of its features in its derived implementations (e.g. renaming, flattening, ..).
• Compatibility: Easy to add or re-order fields/variants without breakage. Detects wrong data types.
• #![no_std] and std compatible.
• Resource efficient: High performance, low memory usage.
• Interoperability: Different architectures can communicate flawlessly.

More Detailed Documentation

See more detailed documentation in the docs module. It also contains information on the binary representation format.

Feature Flags

This library is both no-std and std compatible. Additionally, there are some other features to enable additional functionality:

Feature Flag	Default	Description
alloc	no	Enables the use of alloc types like serialization to a Vec.
heapless	no	Enables serialization to a heapless::Vec.
std	no	Enables the use of std types like serialization to a Writer and deserialization from a Reader.
tracing	no	Enables tracing instrumentation.

Flavors / Modes

By default, structs’ field names and enums’ variant names are encoded as strings. This can be configured to be encoded as unsigned integers of their indices instead. However, this has compatibility implications and some serde features do not work with the index representation. See the format specification for more info.

Usage

Add the library to your project with cargo add serde-brief. By default, no features are enabled (currently), so it is no-std by default. You can enable use of Vecs and such with features like alloc or std.

Example Serialization/Deserialization

The heapless feature was enabled for this example. It is similarly possible with std’s Vec or just slices.

use heapless::Vec;
use serde::{Deserialize, Serialize};

#[derive(Debug, PartialEq, Eq, Serialize, Deserialize)]
struct MyBorrowedData<'a> {
	name: &'a str,
	age: u8,
}

let data = MyBorrowedData { name: "Holla", age: 21 };
let mut output: Vec<u8, 22> = serde_brief::to_heapless_vec(&data).unwrap();

assert_eq!(
	output,
	[
		17, 11, 4, b'n', b'a', b'm', b'e', 11, 5, b'H', b'o', b'l', b'l', b'a', 11, 3, b'a',
		b'g', b'e', 3, 21, 18
	]
);

let parsed: MyBorrowedData = serde_brief::from_slice(&output).unwrap();
assert_eq!(parsed, data);

Bytes Serialization/Deserialization

Serde serializes byte arrays, such as [u8; N] or Vec<u8>, as sequences by default (due to missing specialization support in Rust). To serialize these types as proper bytes, making the format way more efficient, you can use serde_bytes or your own serde-trait-implementations.

Example using serde_bytes:

use serde::{Deserialize, Serialize};
use serde_bytes::{ByteBuf, Bytes};

#[derive(Debug, PartialEq, Eq, Serialize, Deserialize)]
struct MyData<'a> {
	owned_bytes: ByteBuf,
	#[serde(borrow)]
	borrowed_bytes: &'a Bytes,
	#[serde(with = "serde_bytes")]
	byte_vec: Vec<u8>,
}

Performance

If you are interested in maximum performance, please take a look at the PGO usage documentation.

Re-exports

pub use self::value::from_value;

pub use self::value::from_value_with_config;

pub use self::value::to_value;

pub use self::value::to_value_with_config;

pub use self::de::Deserializer;

pub use self::ser::Serializer;

Modules

de

Deserialization implementation.

docs

Here lives more detailed documentation and explanations for this crate and its binary format.

ser

Serialization implementation.

value

Generic value that can contain any value in our data format.

Structs

Config

Configuration for (de-)serialization.

Enums

Error

Error when (de-)serializing.

Functions

from_reader

Deserialize a type from a Reader.

from_reader_with_config

Deserialize a type from a Reader using the given configuration.

from_slice

Deserialize a type from a slice of bytes.

from_slice_with_config

Deserialize a type from a slice of bytes using the given configuration.

to_heapless_vec

Serialize a type into a heapless::Vec of bytes.

to_heapless_vec_with_config

Serialize a type into a heapless::Vec of bytes using the given configuration.

to_slice

Serialize a type into a slice of bytes. Returns the slice with the serialized data.

to_slice_with_config

Serialize a type into a slice of bytes using the given configuration. Returns the slice with the serialized data.

to_vec

Serialize a type into a Vec of bytes.

to_vec_with_config

Serialize a type into a Vec of bytes using the given configuration.

to_writer

Serialize a type into a Writer.

to_writer_with_config

Serialize a type into a Writer using the given configuration.

Type Aliases

Result

Result type that uses the serde-brief error.