Module descriptive

Available on crate feature descriptive only.

A fully self-descriptive format for Müsli.

Descriptive encoding is fully upgrade stable:

• ✔ Can tolerate missing fields if they are annotated with #[musli(default)].
• ✔ Can skip over unknown fields.
• ✔ Can be fully converted back and forth between dynamic containers such as the Value type.
• ✔ Can handle coercion from different types of primitive types, such as signed to unsigned integers. So primitive field types can be assuming they only inhabit compatible values.

This means that it’s suitable as a wire and general interchange format. It’s also suitable for dynamically translating to and from different wire formats such as JSON without having access to the data model.

use musli::{Encode, Decode};

#[derive(Debug, PartialEq, Encode, Decode)]
struct Version1 {
    name: String,
}

#[derive(Debug, PartialEq, Encode, Decode)]
struct Version2 {
    name: String,
    #[musli(default)]
    age: Option<u32>,
}

let version2 = musli::descriptive::to_vec(&Version2 {
    name: String::from("Aristotle"),
    age: Some(61),
})?;

let version1: Version1 = musli::descriptive::decode(version2.as_slice())?;

assert_eq!(version1, Version1 {
    name: String::from("Aristotle"),
});

Configuring

To configure the behavior of the wire format you can use the Encoding type:

use musli::{Encode, Decode};
use musli::descriptive::Encoding;

const CONFIG: Encoding = Encoding::new();

#[derive(Debug, PartialEq, Encode, Decode)]
struct Person<"a> {
    name: &"a str,
    age: u32,
}

let mut out = Vec::new();

let expected = Person {
    name: "Aristotle",
    age: 61,
};

CONFIG.encode(&mut out, &expected)?;
let actual = CONFIG.decode(&out[..])?;

assert_eq!(expected, actual);

Implementation details

Each field is prefix typed with a single byte tag that describes exactly the type which is contained in the field.

Structs

• Encoding
  Setting up encoding with parameters.
• Error
  Error raised during wire encoding.

Constants

• DEFAULT
  The default encoding instance using the default OPTIONS.
• OPTIONS
  The default flavor used by the DEFAULT configuration.

Functions

• decodealloc
  Decode the given type T from the given Reader using the DEFAULT Encoding.
• encodealloc
  Encode the given value to the given Writer using the DEFAULT Encoding.
• from_slicealloc
  Decode the given type T from the given slice using the DEFAULT Encoding.
• to_fixed_bytesalloc
  Encode the given value to a fixed-size bytes using the DEFAULT Encoding.
• to_slicealloc
  Encode the given value to the given slice using the DEFAULT Encoding and return the number of bytes encoded.
• to_vecalloc
  Encode the given value to a Vec using the DEFAULT Encoding.
• to_writerstd and alloc
  Encode the given value to the given Write using the DEFAULT Encoding.

Type Aliases

• Resultalloc
  Convenient result alias for use with musli::descriptive.