Lib.rs

布尔值和整数

ULEB128编码的整数

BCS 格式也使用 ULEB128 编码 在内部表示无符号 32 位整数，在通常期望小值的情况下使用两种情况：(1) 可变长度序列的长度和(2) 枚举值的标记（请参阅下文相关部分）。

一般来说，ULEB128 编码由一系列基数为 128（7 位）的数字组成。每个数字通过将最高位设置为 1 来完成为字节，除了最后一个（最高有效位）数字，其最高位设置为 0。

在 BCS 中，解码 ULEB128 字节的结果必须适合 32 位无符号整数，并且是规范形式。例如，以下值被拒绝

• 80 80 80 80 80 01 (2^36) 太大了。
• 80 80 80 80 10 (2^33) 太大了。
• 80 00 不是 0 的最小编码。

可选数据

可选或可为空的数据要么以完整表示存在，要么不存在。BCS 将其表示为表示数据存在或不存在的一个字节，即 0x01 或 0x00。如果数据存在，则随后跟随着该数据的序列化形式。例如

let some_data: Option<u8> = Some(8);
assert_eq!(to_bytes(&some_data)?, vec![1, 8]);

let no_data: Option<u8> = None;
assert_eq!(to_bytes(&no_data)?, vec![0]);

固定和可变长度序列

序列可以由 BCS 支持的任何类型（甚至是复杂结构）组成，但序列中的所有元素必须是同一类型。如果序列的长度是固定的且已知，那么 BCS 将其表示为序列中每个单独元素序列化的简单连接。如果序列的长度是可变的，那么序列化的序列将使用一个 ULEB128 编码的无符号整数作为长度前缀，表示序列中的元素数量。所有可变长度序列必须小于或等于 MAX_SEQUENCE_LENGTH 个元素。

let fixed: [u16; 3] = [1, 2, 3];
assert_eq!(to_bytes(&fixed)?, vec![1, 0, 2, 0, 3, 0]);

let variable: Vec<u16> = vec![1, 2];
assert_eq!(to_bytes(&variable)?, vec![2, 1, 0, 2, 0]);

let large_variable_length: Vec<()> = vec![(); 9_487];
assert_eq!(to_bytes(&large_variable_length)?, vec![0x8f, 0x4a]);

字符串

只支持有效的 UTF-8 字符串。BCS 将此类字符串序列化为可变长度的字节序列，即以 ULEB128 编码的无符号整数作为长度前缀，后跟字符串的字节表示。

// Note that this string has 10 characters but has a byte length of 24
let utf8_str = "çå∞≠¢õß∂ƒ∫";
let expecting = vec![
    24, 0xc3, 0xa7, 0xc3, 0xa5, 0xe2, 0x88, 0x9e, 0xe2, 0x89, 0xa0, 0xc2,
    0xa2, 0xc3, 0xb5, 0xc3, 0x9f, 0xe2, 0x88, 0x82, 0xc6, 0x92, 0xe2, 0x88, 0xab,
];
assert_eq!(to_bytes(&utf8_str)?, expecting);

元组

元组是对象的类型化组合：(Type0, Type1)

元组被视为一个固定长度序列，其中序列中的每个元素可以是 BCS 支持的任何不同类型。元组的每个元素按在元组中定义的顺序序列化，即 [tuple.0, tuple.2]。

let tuple = (-1i8, "diem");
let expecting = vec![0xFF, 4, b'd', b'i', b'e', b'm'];
assert_eq!(to_bytes(&tuple)?, expecting);

结构体

结构体是由可能具有不同类型的字段组成的固定长度序列。结构体中的每个字段按照规范结构定义中指定的顺序序列化。结构体可以存在于其他结构体中，因此 BCS 会递归到每个结构体中并按顺序序列化它们。序列化格式中没有标签，结构体顺序定义了序列化流中的组织。

#[derive(Serialize)]
struct MyStruct {
    boolean: bool,
    bytes: Vec<u8>,
    label: String,
}

#[derive(Serialize)]
struct Wrapper {
    inner: MyStruct,
    name: String,
}

let s = MyStruct {
    boolean: true,
    bytes: vec![0xC0, 0xDE],
    label: "a".to_owned(),
};
let s_bytes = to_bytes(&s)?;
let mut expecting = vec![1, 2, 0xC0, 0xDE, 1, b'a'];
assert_eq!(s_bytes, expecting);

let w = Wrapper {
    inner: s,
    name: "b".to_owned(),
};
let w_bytes = to_bytes(&w)?;
assert!(w_bytes.starts_with(&s_bytes));

expecting.append(&mut vec![1, b'b']);
assert_eq!(w_bytes, expecting);

外部标记枚举

枚举通常表示为可以取许多不同变体的类型。在 BCS 中，每个变体都映射到一个变体索引，这是一个 ULEB128 编码的 32 位无符号整数，后跟如果有关联值的话，序列化的数据。关联类型可以是任何 BCS 支持的类型。变体索引是根据规范枚举定义中变体的顺序确定的，其中第一个变体索引为 0，第二个为 1，等等。

#[derive(Serialize)]
enum E {
    Variant0(u16),
    Variant1(u8),
    Variant2(String),
}

let v0 = E::Variant0(8000);
let v1 = E::Variant1(255);
let v2 = E::Variant2("e".to_owned());

assert_eq!(to_bytes(&v0)?, vec![0, 0x40, 0x1F]);
assert_eq!(to_bytes(&v1)?, vec![1, 0xFF]);
assert_eq!(to_bytes(&v2)?, vec![2, 1, b'e']);

如果您需要序列化 C 风格的枚举，应使用原始整数类型。

映射（键/值存储）

地图表示为一系列长度可变的、排序的（键，值）元组。键必须是唯一的，元组按照每个键的BCS字节按字典顺序递增排序。表示方式与可变长度序列类似。特别是，它以ULEB128编码的元组数量开头。

let mut map = HashMap::new();
map.insert(b'e', b'f');
map.insert(b'a', b'b');
map.insert(b'c', b'd');

let expecting = vec![(b'a', b'b'), (b'c', b'd'), (b'e', b'f')];

assert_eq!(to_bytes(&map)?, to_bytes(&expecting)?);

贡献

有关如何帮助的详细信息，请参阅贡献文件。

许可证

本项目可在Apache 2.0许可证的条款下使用。Apache 2.0许可证。