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)?);

贡献

有关如何提供帮助的信息，请参阅CONTRIBUTING文件。

许可证

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