rustdoc

bytekey

为 Rust 值提供二进制编码，同时保留字典序排序顺序。保留顺序的编码对于创建具有字节字符串类型键的排序键值存储键非常有用，例如 leveldb。 bytekey 尝试将值编码到尽可能少的字节数，同时保留顺序保证。类型信息 不会 与值一起序列化，因此必须知道序列化数据的类型才能进行解码（bytekey 不实现自描述格式）。

支持的数据类型

bytekey 编码目前支持所有 Rust 基本类型、字符串、选项、结构体、枚举和元组。 isize 和 usize 类型是可变长度编码。序列（Vec）和映射类型目前不支持（但将来可能支持）。有关序列化格式的详细信息，请参阅 Encoder。

使用方法

extern crate serialize;
extern crate bytekey;
use bytekey::{encode, decode};

#[deriving(Encodable, Decodable, Show, PartialEq)]
struct MyKey { a: usize, b: String }

let a = MyKey { a: 1, b: "foo".to_string() };
let b = MyKey { a: 2, b: "foo".to_string() };
let c = MyKey { a: 2, b: "fooz".to_string() };

assert!(encode(&a) < encode(&b));
assert!(encode(&b) < encode(&c));
assert_eq!(a, decode(encode(&a)).unwrap());

类型演变

通常，为了正确反序列化，必须知道序列化值的确切类型。对于结构和枚举，一旦序列化了该类型的任何值，类型实际上就固定了：结构或枚举的更改会导致已编码值的反序列化失败或返回错误值。唯一的例外是向现有枚举的末尾添加新变体。枚举变体 不能 改变类型、删除或重新排序。禁止对结构的所有更改，包括添加、删除、重新排序或更改字段的类型。

这些限制导致在使用 bytekey 编码时有一些最佳实践

• 除非你需要对编码值进行字典序排序，否则不要使用 bytekey！如果不需要此功能，则更通用的编码库（如 Cap'n Proto 或 binary-encode）将更适合您。
• 如果您需要持久化编码值超过进程的生命周期（即您将编码值写入文件或数据库），请考虑使用枚举作为顶级包装类型。这将允许您在向后兼容的方式下无缝地添加新变体，当您需要以向后兼容的方式更改键格式时（不同键类型将分别排序）。如果您的枚举有不到 16 个变体，那么开销只是编码输出中的单个字节。

许可证

bytekey 使用 Apache License 2.0 许可。有关完整的许可文本，请参阅 LICENSE。