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进行编码。这包括数组的长度切片以及枚举的判别式。

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

示例 - 序列化/反序列化

明信片可以像其他 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 的系统，用于修改明信片序列化或处理序列化数据的方式。这些风味在序列化或反序列化过程中充当“插件”或“中间件”，可以组合使用以获得复杂的协议格式。

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

设置 - Cargo.toml

不要忘记将 no-std 子集的 serde 与 postcard 一起添加到您的 [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 许可证定义），都将如上所述双许可，不附加任何额外条款或条件。