Module exonum::encoding

encoding is a serialization library supporting zero-copy (de)serialization of primitive types, heterogeneous structures and arrays.

See also the documentation page on serialization.

Structure serialization

Structures are in the root of any serializable Exonum object. Binary representation of structures is split into two main parts:

• Header: a fixed-sized part
• Body: dynamically sized part, known only after parsing the header

To create a structure type, you can use message! and encoding_struct! macros.

Examples

Consider a structure with two fields: String and u64. To implement Exonum (de)serialization for this structure you need to use macros like this:

encoding_struct! {
    struct MyAwesomeStructure {
        name: &str,
        age: u64,
    }
}

let student = MyAwesomeStructure::new("Andrew", 23);

Then the internal buffer of student is as follows:

Position	Stored data	Hexadecimal form	Comment
0 => 4	16	10 00 00 00	LE-encoded segment pointer to the data
4 => 8	6	06 00 00 00	LE-encoded segment size
8 => 16	23	17 00 00 00 00 00 00 00	number in little endian
16 => 24	Andrew	41 6e 64 72 65 77	Text bytes in UTF-8 encoding

Structure fields

Primitive types

Primitive types are all fixed-sized, and located fully in the header.

Type name	Size in Header	Info
u8	1	Regular byte
i8	1	Signed byte
u16	2	Short unsigned integer stored in little endian
i16	2	Short signed integer stored in little endian
u32	4	32-bit unsigned integer stored in little endian
i32	4	32-bit signed integer stored in little endian
u64	8	Long unsigned integer stored in little endian
i64	8	Long signed integer stored in little endian
F32	4	32-bit floating point type stored in little endian [1][2]
F64	8	64-bit floating point type stored in little endian [1][2]
bool	1	Stored as a byte, with 0x01 denoting true and 0x00 false [3]

[1] Special floating point values that cannot be represented as a sequences of digits (such as Infinity, NaN and signaling NaN) are not permitted.

[2] Floating point value serialization is hidden behind the float_serialize feature gate.

[3] Trying to represent other values as bool leads to undefined behavior.

Segment fields

All segment types take 8 bytes in the header: 4 for position in the buffer, and 4 for the segment field size.

Custom fields

These types can be implemented as per developer's design, but they should declare how many bytes they write in the header using the field_size() function.

Modules

serialize

Serialize structure into specific format. Currently support only json. This module is a pack of superstructures over serde Serializer`Deserializer`

Structs

CheckedOffset

CheckedOffset is a type that take control over overflow, so you can't panic without unwrap, and work with this value without overflow checks.

Enums

Error

This structure represent encoding specific errors. This errors returned by function check of each Field.

Traits

Field	Trait for all types that could be a field in encoding.
SegmentField	Trait for fields, that has unknown compile-time size. Usually important for arrays, or other types that in rust is always at HEAP

Type Definitions

Offset	Type alias usable for reference in buffer
Result	Type alias that should be returned in check method of Field