Postcard

Postcard 是一个专注于 Serde 的序列化和反序列化器 —— #![no_std]

Postcard 的目标是方便在受限环境中进行开发，同时允许根据需要灵活自定义行为。

设计目标

1. 主要设计用于 #![no_std] 使用，嵌入式或其他受限环境中
2. 支持最大的 serde 功能集，以便 postcard 可以用作即插即用的替代品
3. 避免为微控制器或桌面/服务器PC编写的通信代码之间的特殊差异
4. 资源高效 - 内存使用，代码大小，开发者时间和CPU时间；按此顺序
5. 允许库用户自定义序列化和反序列化行为以满足其特定需求

格式稳定性

自 v1.0.0 版本起，postcard 具有文档化和稳定的线格式。有关此线格式的更多信息，请参阅 Postcard 仓库中的 spec/ 文件夹，或在线查看 https://postcard.jamesmunns.com。

致力于 Postcard 规范，Postcard 1.0 版本的某些部分由 Mozilla 公司赞助。

变长数据

所有大于八位的有符号和无符号整数都使用 Varint 编码。这包括数组切片的长度以及 enums 的区分符。

有关更多信息，请参阅线规范中的 Varint 章节。

示例 - 序列化/反序列化

Postcard 可以序列化和反序列化与其它 serde 格式相似的消息。

使用默认的 heapless 功能将数据序列化为 heapless::Vec<u8>

use core::ops::Deref;
use serde::{Serialize, Deserialize};
use postcard::{from_bytes, to_vec};
use heapless::Vec;

#[derive(Serialize, Deserialize, Debug, Eq, PartialEq)]
struct RefStruct<'a> {
    bytes: &'a [u8],
    str_s: &'a str,
}
let message = "hElLo";
let bytes = [0x01, 0x10, 0x02, 0x20];
let output: Vec<u8, 11> = to_vec(&RefStruct {
    bytes: &bytes,
    str_s: message,
}).unwrap();

assert_eq!(
    &[0x04, 0x01, 0x10, 0x02, 0x20, 0x05, b'h', b'E', b'l', b'L', b'o',],
    output.deref()
);

let out: RefStruct = from_bytes(output.deref()).unwrap();
assert_eq!(
    out,
    RefStruct {
        bytes: &bytes,
        str_s: message,
    }
);

或者使用可选的 alloc 功能将数据序列化为 alloc::vec::Vec<u8>

use core::ops::Deref;
use serde::{Serialize, Deserialize};
use postcard::{from_bytes, to_allocvec};
extern crate alloc;
use alloc::vec::Vec;

#[derive(Serialize, Deserialize, Debug, Eq, PartialEq)]
struct RefStruct<'a> {
    bytes: &'a [u8],
    str_s: &'a str,
}
let message = "hElLo";
let bytes = [0x01, 0x10, 0x02, 0x20];
let output: Vec<u8> = to_allocvec(&RefStruct {
    bytes: &bytes,
    str_s: message,
}).unwrap();

assert_eq!(
    &[0x04, 0x01, 0x10, 0x02, 0x20, 0x05, b'h', b'E', b'l', b'L', b'o',],
    output.deref()
);

let out: RefStruct = from_bytes(output.deref()).unwrap();
assert_eq!(
    out,
    RefStruct {
        bytes: &bytes,
        str_s: message,
    }
);

风味

postcard 支持一个名为 Flavors 的系统，用于修改 postcard 序列化或处理序列化数据的方式。这些风味在序列化或反序列化过程中充当“插件”或“中间件”，可以组合使用以获得复杂的协议格式。

有关使用方法的更多信息，请参阅 ser_flavors 或 de_flavors 模块的文档。

设置 - Cargo.toml

别忘了将 serde 的 无标准子集 与 postcard 一起添加到您的 Cargo.toml 的 [dependencies] 部分中！

[dependencies]
postcard = "1.0.0"

# By default, `serde` has the `std` feature enabled, which makes it unsuitable for embedded targets
# disabling default-features fixes this
serde = { version = "1.0.*", default-features = false }

许可证

许可协议为以下之一

• Apache License，版本 2.0 (LICENSE-APACHE 或 http://www.apache.org/licenses/LICENSE-2.0)
• MIT 许可证 (LICENSE-MIT 或 http://opensource.org/licenses/MIT)

由您选择。

贡献

除非您明确声明，否则根据 Apache-2.0 许可证定义，您提交给工作以包含在内的任何有意贡献都应按上述方式双重许可，不附加任何额外条款或条件。