Crate abomonation [] [src]

Abomonation (spelling intentional) is a fast serialization / deserialization crate.

Abomonation takes typed elements and simply writes their contents as binary. It then gives the element the opportunity to serialize more data, which is useful for types with owned memory such as String and Vec. The result is effectively a copy of reachable memory, where pointers are zero-ed out and vector capacities are set to the vector length. Deserialization results in a shared reference to the type, pointing at the binary data itself.

Abomonation does several unsafe things, and should ideally be used only through the methods encode and decode on types implementing the Abomonation trait. Implementing the Abomonation trait is highly discouraged, unless you use the abomonate! macro

Very important: Abomonation reproduces the memory as laid out by the serializer, which can reveal architectural variations. Data encoded on a 32bit big-endian machine will not decode properly on a 64bit little-endian machine. Moreover, it could result in undefined behavior if the deserialization results in invalid typed data. Please do not do this.

Examples

use abomonation::{encode, decode};

// create some test data out of abomonation-approved types
let vector = (0..256u64).map(|i| (i, format!("{}", i)))
                        .collect::<Vec<_>>();

// encode a Vec<(u64, String)> into a Vec<u8>
let mut bytes = Vec::new();
encode(&vector, &mut bytes);

// decode a &[(u64, String)] from &mut [u8] binary data
if let Ok(result) = decode::<Vec<(u64, String)>>(&mut bytes) {
    assert!(result == &vector);
}

Macros

abomonate!

The abomonate! macro takes a type name with an optional list of fields, and implements 'Abomonation' for the type, following the pattern of the tuple implementations: each method calls the equivalent method on each of its fields.

Traits

Abomonation

Abomonation provides methods to serialize any heap data the implementor owns.

Functions

decode

Decodes a binary buffer into a reference to a typed element.

decode_slice

Decodes a binary buffer into a reference to a typed slice.

encode

Encodes a typed element into a binary buffer.

encode_slice

Encodes a typed slice into a binary buffer.