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编码的元组数 precedes。

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许可证的条款下使用。Apache 2.0许可证。