Crate serde_smile

A Smile implementation for Serde.

Smile is a binary data format created by the developers of the Jackson serialization library for Java. It is designed to be a binary equivalent of JSON.

Serialization Options

Smile defines several optional features that can be enabled or disabled during serialization:

• Builder::raw_binary: If enabled, binary data will be encoded directly as “raw” bytes, rather than using Smile’s 7-bit “safe” encoding. The raw format is 14% smaller and faster to serialize and deserialize, but usage means that encoded values may contain Smile control characters such as the end-of-stream token 0xff. Disabled by default.
• Builder::shared_strings: If enabled, string values 64 bytes and smaller will be deduplicated in the encoded format. This increases the memory overhead of serialization and deserialization, but can significantly shrink the size of the encoded value when strings are repeated. Disabled by default.
• Builder::shared_properties: If enabled, map keys 64 bytes and smaller will be deduplicated in the encoded format. This increases the memory overhead of serialization and deserialization, but can significantly shrink the size of the encoded value when keys are repeated (particularly struct field names). Enabled by default.
• Serializer::end: A sequence of Smile values can optionally be terminated by the end-of-stream token 0xff. Calling this method will write the token into the output stream.

Special Types

Smile supports two kinds of values that Serde does not natively handle: arbitrary precision integer and decimals. This crate defines special types BigInteger and BigDecimal which will serialize to and deserialize from their respective Smile types. However, they should only be used with the serializers and deserializers defined within this crate as they will produce nonsensical values when used with other Serde libraries.

Encoding Notes

Rust integer values that cannot be stored in an i64 will be serialized as Smile BigInteger values. In the other direction, BigInteger values will be deserialized to Rust integer types if the value is small enough.

Examples

Serialize a Rust object into a Smile value:

use serde::Serialize;
use serde_smile::Error;

#[derive(Serialize)]
struct Address {
    number: u32,
    street: String,
}

fn main() -> Result<(), Error> {
    let address = Address {
        number: 1600,
        street: "Pennsylvania Avenue".to_string(),
    };

    let value = serde_smile::to_vec(&address)?;

    Ok(())
}

Deserialize a Smile value into a Rust object:

use serde::Deserialize;
use serde_smile::Error;

#[derive(Deserialize)]
struct Address {
    number: u32,
    street: String,
}

fn main() -> Result<(), Error> {
    let smile = b":)\n\x01\xfa\x85number\x24\x32\x80\x85street\x52Pennsylvania Avenue\xfb";

    let address: Address = serde_smile::from_slice(smile)?;

    println!("{} {}", address.number, address.street);

    Ok(())
}

Modules

• de
  Deserialize Smile data into a Rust data structure.
• ser
  Serialize a Rust data structure into Smile data.
• value
  Definition of a Smile value.

Structs

• Deserializer
  A structure that deserializes Smile into Rust values.
• Error
  An error encountered when serializing or deserializing to or from Smile.
• Serializer
  A structure for serializing Rust values into Smile.

Functions

• from_mut_slice
  Deserializes an instance of type T from a mutable slice of Smile data.
• from_reader
  Deserializes an instance of type T from an IO stream of Smile data.
• from_slice
  Deserializes an instance of type T from a slice of Smile data.
• to_vec
  Serializes the given data structure to a Smile byte vector using default serializer settings.
• to_writer
  Serializes the given data structure as Smile into the IO stream using default serializer settings.