Crate abomonation

Expand description

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. 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; instead, you can use the abomonation_derive crate.

Very important: Abomonation reproduces the memory as laid out by the serializer, which will 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();
unsafe { encode(&vector, &mut bytes); }

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

Modules§

abomonated

Macros§

unsafe_abomonateDeprecated
The unsafe_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§