bytekey_fix/
lib.rs

1//! Binary encoding for Rust values which preserves lexicographic sort order. Order-preserving
2//! encoding is useful for creating keys for sorted key-value stores with byte string typed keys,
3//! such as [leveldb](https://github.com/google/leveldb) and
4//! [sled](https://github.com/spacejam/sled).
5//!
6//! `bytekey` is *not* a self-describing format. In other words, Type information is *not*
7//! serialized alongside values, and thus the type of serialized data must be known in order to
8//! perform deserialization.
9//!
10//! #### Supported Data Types
11//!
12//! `bytekey` currently supports all Rust primitives, strings, options, structs, enums, vecs, and
13//! tuples. See **Serializer** for details on the serialization format.
14//!
15//! #### Usage
16//!
17//! ```
18//! #[macro_use]
19//! extern crate serde_derive;
20//! extern crate bytekey;
21//! use bytekey::{deserialize, serialize};
22//!
23//! #[derive(Debug, PartialEq, Serialize, Deserialize)]
24//! struct MyKey { a: u32, b: String }
25//!
26//! # fn main() {
27//! let a = MyKey { a: 1, b: "foo".to_string() };
28//! let b = MyKey { a: 2, b: "foo".to_string() };
29//! let c = MyKey { a: 2, b: "fooz".to_string() };
30//!
31//! assert!(serialize(&a).unwrap() < serialize(&b).unwrap());
32//! assert!(serialize(&b).unwrap() < serialize(&c).unwrap());
33//! assert_eq!(a, deserialize(&serialize(&a).unwrap()).unwrap());
34//! # }
35//! ```
36//!
37//! #### Type Evolution
38//!
39//! In general, the exact type of a serialized value must be known in order to correctly
40//! deserialize it. For structs and enums, the type is effectively frozen once any values of the
41//! type have been serialized: changes to the struct or enum will cause deserialization of already
42//! serialized values to fail or return incorrect values. The only exception is adding new variants
43//! to the end of an existing enum. Enum variants may *not* change type, be removed, or be
44//! reordered. All changes to structs, including adding, removing, reordering, or changing the type
45//! of a field are forbidden.
46//!
47//! These restrictions lead to a few best-practices when using `bytekey` serialization:
48//!
49//! * Don't use `bytekey` unless you need lexicographic ordering of serialized values! A more
50//!   general encoding library such as [Cap'n Proto](https://github.com/dwrensha/capnproto-rust) or
51//!   [bincode](https://github.com/TyOverby/binary-encode) will serve you better if this feature is
52//!   not necessary.
53//! * If you persist serialized values for longer than the life of a process (i.e. you write the
54//!   serialized values to a file or a database), consider using an enum as a top-level wrapper
55//!   type. This will allow you to seamlessly add a new variant when you need to change the key
56//!   format in a backwards-compatible manner (the different key types will sort seperately). If
57//!   your enum has less than 16 variants, then the overhead is just a single byte in serialized
58//!   output.
59
60extern crate byteorder;
61extern crate serde;
62
63pub mod de;
64pub mod ser;
65
66pub use crate::de::{deserialize, deserialize_from, Deserializer};
67pub use crate::ser::{serialize, serialize_into, Serializer};
68use std::error::Error as StdError;
69use std::{fmt, result};
70
71/// An error type that encompasses both serialization and deserialization errors.
72#[derive(Debug)]
73pub enum Error {
74    Serialize(ser::Error),
75    Deserialize(de::Error),
76}
77
78/// A short-hand for `result::Result<T, bytekey::Error>`.
79pub type Result<T> = result::Result<T, Error>;
80
81impl From<ser::Error> for Error {
82    fn from(error: ser::Error) -> Error {
83        Error::Serialize(error)
84    }
85}
86
87impl From<de::Error> for Error {
88    fn from(error: de::Error) -> Error {
89        Error::Deserialize(error)
90    }
91}
92
93impl fmt::Display for Error {
94    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
95        write!(f, "{}", self.source().unwrap())
96    }
97}
98
99impl StdError for Error {
100    fn source(&self) -> Option<&(dyn StdError + 'static)> {
101        match *self {
102            Error::Serialize(ref err) => Some(err),
103            Error::Deserialize(ref err) => Some(err),
104        }
105    }
106
107    fn cause(&self) -> Option<&dyn StdError> {
108        match *self {
109            Error::Serialize(ref err) => Some(err),
110            Error::Deserialize(ref err) => Some(err),
111        }
112    }
113}
bytekey_fix/lib.rs

bytekey_fix/
lib.rs
