Module exonum::encoding [−] [src]

encoding is a lazy serialization library, it allows to keep struct serialized in place, and deserialize fields on demand.

Binary representation of structure is split into two main parts:

Header - fixed sized part.
Body - dynamic sized, known only after parsing header, part.

For easy creating this structures, in exonum you can use macros message! and encoding_struct!

Examples

Imagine structure with just two field's

First one is String
second one is u64

To create message for this structure now, you need to know how many bytes this fields took in header. See Fields layout.

We know that u64 took 8 bytes, and string took 8 segment bytes.

Then to create, for example storage value, you need to use macros like this:

encoding_struct! {
    struct MyAwesomeStructure {
        const SIZE = 16;

        field name: &str [0 => 8]
        field age:  u64  [8 => 16]
    }
}
// now if we create it in memory

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

Then in internal buffer of student you will get:

Position	Stored data	Hexadecimal form	Comment
`0 => 4`	16	`10 00 00 00`	LE stored segment pointer to the data
`4 => 8`	6	`06 00 00 00`	LE stored 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`	Real text bytes

Fields layout

Fields could be splitted into tree main parts:

Primitive types

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

Type name	Size in Header	Info
`u8`	1	Regular byte
`i8`	1	Signed byte
`u16`	2	Short unsigned number stored in little endian
`i16`	2	Short signed number stored in little endian
`u32`	4	32-bit unsigned number stored in little endian
`i32`	4	32-bit signed number stored in little endian
`u64`	8	long unsigned number stored in little endian
`i64`	8	long signed number stored in little endian
`bool`	1	stored as single byte, where `0x01` - true `0x00` - false [1]

[1]

Trying to represent other values as bool leads to undefined behavior.

Segment fields

All segment types took 8 bytes in header, 4 for position in buffer, and 4 for segment field size

Custom fields

This types could be implemented as creator want, but they should declare how many bytes they will write on header in function field_size()

Modules

serialize

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

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`