Parity SCALE Codec

Parity Substrate 框架中使用的类型所采用的 SCALE (Simple Concatenating Aggregate Little-Endian) 数据格式的 Rust 实现。

SCALE 是一种轻量级格式，允许进行编码（和解码），使其非常适合资源受限的执行环境，如区块链运行时和低功耗、低内存设备。

需要注意的是，编码上下文（了解类型和数据结构的外观）需要在编码和解析端分别单独知道。编码的数据不包含此上下文信息。

要更好地了解不同类型的编码方式，请参阅 Substrate 文档中的“类型编码（SCALE）”页面。

实现

该编码器使用以下特质实现：

编码

Encode 特质用于将数据编码为 SCALE 格式。该 Encode 特质包含以下函数：

• size_hint(&self) -> usize：获取编码数据的容量（以字节为单位）。这是为了避免编码所需内存的重复分配。这可以是一个估计值，不需要是精确数字。如果大小未知，甚至没有良好的最大值，则我们可以从特性行为中省略此函数。这需要是一个低成本操作，因此不应该涉及迭代等。
• encode_to<T: Output>(&self, dest: &mut T)：将值编码并附加到目标缓冲区。
• encode<Vec<u8>>(&self) -> Vec<u8>：将类型数据编码并返回一个切片。
• using_encoded<R, F: FnOnce(&[u8]) -> R>(&self, f: F) -> R：将类型数据编码并执行一个闭包在编码值上。返回执行闭包的结果。

注意：实现应覆盖using_encoded用于值类型和encode_to用于分配类型。size_hint应尽可能实现所有类型，包装类型应覆盖所有方法。

解码

使用Decode特性行为用于将编码数据反序列化/解码到相应类型。

• fn decode<I: Input>(value: &mut I) -> Result<Self, Error>：尝试将值从SCALE格式解码到被调用的类型。如果解码失败，则返回一个Err。

CompactAs

CompactAs特性行为用于将自定义类型/结构封装为紧凑类型，这使得它们在空间/内存效率上更高。紧凑编码的描述在这里。

• encode_as(&self) -> &Self::As：将类型（self）编码为紧凑类型。类型As在相同的特性中定义，并且其实现应该是紧凑编码可用的。
• decode_from(_: Self::As) -> Result<Self, Error>：从紧凑编码类型解码类型（self）。

HasCompact

如果实现了HasCompact特性，则表示相应的类型是紧凑编码类型。

EncodeLike

需要为每个类型手动实现EncodeLike特性。当使用derive时，它会自动为您完成。基本上，这个特性为您提供了一个机会，可以将多个类型传递给一个函数，这些类型都编码为相同的表示。

使用示例

以下是一些演示编码器使用的示例。

简单类型

# // Import macros if derive feature is not used.
# #[cfg(not(feature="derive"))]
# use parity_scale_codec_derive::{Encode, Decode};

use parity_scale_codec::{Encode, Decode};

#[derive(Debug, PartialEq, Encode, Decode)]
enum EnumType {
    #[codec(index = 15)]
    A,
    B(u32, u64),
    C {
        a: u32,
        b: u64,
    },
}

let a = EnumType::A;
let b = EnumType::B(1, 2);
let c = EnumType::C { a: 1, b: 2 };

a.using_encoded(|ref slice| {
    assert_eq!(slice, &b"\x0f");
});

b.using_encoded(|ref slice| {
    assert_eq!(slice, &b"\x01\x01\0\0\0\x02\0\0\0\0\0\0\0");
});

c.using_encoded(|ref slice| {
    assert_eq!(slice, &b"\x02\x01\0\0\0\x02\0\0\0\0\0\0\0");
});

let mut da: &[u8] = b"\x0f";
assert_eq!(EnumType::decode(&mut da).ok(), Some(a));

let mut db: &[u8] = b"\x01\x01\0\0\0\x02\0\0\0\0\0\0\0";
assert_eq!(EnumType::decode(&mut db).ok(), Some(b));

let mut dc: &[u8] = b"\x02\x01\0\0\0\x02\0\0\0\0\0\0\0";
assert_eq!(EnumType::decode(&mut dc).ok(), Some(c));

let mut dz: &[u8] = &[0];
assert_eq!(EnumType::decode(&mut dz).ok(), None);

# fn main() { }

具有HasCompact的紧凑类型

# // Import macros if derive feature is not used.
# #[cfg(not(feature="derive"))]
# use parity_scale_codec_derive::{Encode, Decode};

use parity_scale_codec::{Encode, Decode, Compact, HasCompact};

#[derive(Debug, PartialEq, Encode, Decode)]
struct Test1CompactHasCompact<T: HasCompact> {
    #[codec(compact)]
    bar: T,
}

#[derive(Debug, PartialEq, Encode, Decode)]
struct Test1HasCompact<T: HasCompact> {
    #[codec(encoded_as = "<T as HasCompact>::Type")]
    bar: T,
}

let test_val: (u64, usize) = (0u64, 1usize);

let encoded = Test1HasCompact { bar: test_val.0 }.encode();
assert_eq!(encoded.len(), test_val.1);
assert_eq!(<Test1CompactHasCompact<u64>>::decode(&mut &encoded[..]).unwrap().bar, test_val.0);

# fn main() { }

具有CompactAs的类型

# // Import macros if derive feature is not used.
# #[cfg(not(feature="derive"))]
# use parity_scale_codec_derive::{Encode, Decode};

use serde_derive::{Serialize, Deserialize};
use parity_scale_codec::{Encode, Decode, Compact, HasCompact, CompactAs, Error};

#[cfg_attr(feature = "std", derive(Serialize, Deserialize, Debug))]
#[derive(PartialEq, Eq, Clone)]
struct StructHasCompact(u32);

impl CompactAs for StructHasCompact {
    type As = u32;

    fn encode_as(&self) -> &Self::As {
        &12
    }

    fn decode_from(_: Self::As) -> Result<Self, Error> {
        Ok(StructHasCompact(12))
    }
}

impl From<Compact<StructHasCompact>> for StructHasCompact {
    fn from(_: Compact<StructHasCompact>) -> Self {
        StructHasCompact(12)
    }
}

#[derive(Debug, PartialEq, Encode, Decode)]
enum TestGenericHasCompact<T> {
    A {
        #[codec(compact)] a: T
    },
}

let a = TestGenericHasCompact::A::<StructHasCompact> {
    a: StructHasCompact(12325678),
};

let encoded = a.encode();
assert_eq!(encoded.len(), 2);

# fn main() { }

Derive属性

derive实现支持以下属性

• codec(dumb_trait_bound)：这个属性需要放在应该实现其中一个特性的类型之上。它将使确定要添加的特性边界的算法回退到仅使用类型的类型参数。这可以在算法包括私有类型在公共接口中的情况下很有用。通过使用此属性，您应该不会再收到此错误/警告。
• codec(skip)：需要放在字段或变体之上，使其在编码/解码时被跳过。
• codec(compact)：需要放在字段之上，使该字段使用紧凑编码。（类型需要支持紧凑编码。）
• codec(encoded_as = "OtherType")：需要放在字段之上，使该字段使用OtherType进行编码。
• codec(index = 0)：需要放在枚举变体之上，使变体在编码时使用指定的索引。默认情况下，索引从0开始计算，以第一个变体为起点。
• codec(encode_bound)、codec(decode_bound) 和 codec(mel_bound)：这3个属性分别接受用于注解类型的 where 子句，以实现 Encode、Decode 和 MaxEncodedLen 特性。
• codec(encode_bound(skip_type_params))、codec(decode_bound(skip_type_params)) 和 codec(mel_bound(skip_type_params))：这3个子属性接受类型作为参数，以跳过相应特质的特质的推导，例如在 codec(encode_bound(skip_type_params(T))) 中，将不会包含 Encode 特质约束，即使正在为注解类型推导 Encode。
• codec(crate = path::to::crate)：指定在从生成的代码引用 Codec API 时使用的 parity-scale-codec crate 实例的路径。这通常仅在调用来自不同 crate 的公共宏重新导出的 Codec derive 时适用。