Crate storekey

Crate storekey 

Source
Expand description

Binary serialization library for Rust values which preserves lexicographic sort order. Order-preserving encoding is useful for creating keys for sorted key-value stores with byte string typed keys, such as leveldb and sled.

storekey is not a self-describing format. In other words, Type information is not serialized alongside values, and thus the type of serialized data must be known in order to perform deserialization.

§Supported Data Types

storekey currently supports all Rust primitives, strings, options, structs, enums, vecs, and tuples. See Encode for details on the serialization format.

§Type Evolution

In general, the exact type of a serialized value must be known in order to correctly deserialize it. For structs and enums, the type is effectively frozen once any values of the type have been serialized: changes to the struct or enum will cause deserialization of already serialized values to fail or return incorrect values.

The only limited exception is adding new variants to the end of an existing enum. Enum variants may not change type, be removed, or be reordered. All changes to structs, including adding, removing, reordering, or changing the type of a field are forbidden.

Adding a new variant to an proc-macro derived encoded enum will not break serialization as long as the amount of variants does not overflow the current descriminator length. In this case adding a new variant after having 254 (u8::MAX - 2) variants is breaking so is adding one after already having u16::MAX variants.

These restrictions lead to a few best-practices when using storekey serialization:

  • Don’t use storekey unless you need lexicographic ordering of serialized values! A more general encoding library such as Cap’n Proto or bincode will serve you better if this feature is not necessary.

Structs§

BorrowReader
Struct used in [storekey::BorrowDecode] for reading types from the buffer.
EscapedChars
EscapedIter
EscapedSlice
A slice buffer which is in an escaped format: containing possible 0u8 and 1u8 bytes escaped with a 1u8 as well as a final terminating null byte.
EscapedStr
A slice buffer which is in an escaped format: containing possible 0u8 and 1u8 bytes escaped with a 1u8 as well as a final terminating null byte
MessageError
Reader
Struct used in [storekey::Decode] for reading types from the buffer.
Writer
The writer type used in [storekey::Encode].

Enums§

DecodeError
EncodeError

Traits§

BorrowDecode
Types which can be decoded from storekey format with borrowed ownership.
Decode
Types which can be decoded from storekey format with owned ownership.
Encode
Types which can be encoded to storekey format.
ToEscaped

Functions§

decode
Decode an decodable type from a type which implements std::io::BufRead.
decode_borrow
Decode a decodable type by borrowing from the given slice.
decode_borrow_format
Decode a decodable type by borrowing from the given slice with a given format type.
decode_format
Decode an decodable type from a type which implements std::io::BufRead with a given format type.
encode
Encode an encodable type into a type which implements std::io::Write.
encode_format
Encode an encodable type into a type which implements std::io::Write with a given format type.
encode_vec
Encode an encodable type into a vector.
encode_vec_format
Encode an encodable type into a vector with a given format type.

Derive Macros§

BorrowDecode
Decode
Encode
ToEscaped