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.
• #![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 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);

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_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.