flatty

扁平消息缓冲区，直接映射到 Rust 类型，无需打包/解包。

概述

当类型占用单个连续内存区域时称为 flat 类型。这种类型在需要以二进制数据形式存储或发送对象，同时又方便访问其内容而不需要序列化/反序列化时非常有用。

此 crate 提供了基本的 flat 类型以及创建新的用户定义复合 flat 类型的方法（使用 #[flat] 属性宏），这些类型可以像常规 Rust struct 或 enum 一样使用。

此外，此 crate 可以在无需 std 的情况下使用，甚至无需 alloc。

概念

转换

可以使用 as_bytes（和 unsafe as_mut_bytes）从 flat 类型的实例获得二进制表示。也可以将字节转换为 flat 类型，请参阅 就地初始化 和 验证。

DST

flat 类型可以是动态大小的（如 FlatVec），在这种情况下，它利用 Rust 操作 ?Sized 类型的能力。用户定义的 flat 结构也可以是无大小的（仅允许最后一个字段是无大小的）。即使 flat 枚举也可以是无大小的，但 Rust 目前不支持它们，因此其内容只能通过返回包含对原始枚举内容引用的常规枚举的 as_ref/as_mut 方法来访问。

就地初始化

尺寸类型可以像普通的Rust类型一样实例化。但在DST的情况下，Rust不能以通常的方式在栈上构造它，因为其大小在编译时是未知的。相反，我们可以将这些类型初始化到指定的内存区域。

为此，我们可以使用所谓的emplacer——一种可以初始化对象到指定内存的东西。对于尺寸类型，其实例也是emplacer。

emplacer可以应用于原始字节数据，使用new_in_place，或使用assign_in_place替换现有的结构内容。此外，一些类型具有默认的emplacer，可以通过default_in_place以默认状态初始化。

验证

不是任何字节的组合都是扁平类型的有效表示。例如，Bool只有两种有效状态：0和1，或者FlatVec的长度不能大于其容量。validate可以用来检查数据对于特定的扁平类型是否有效，或者from_bytes/from_mut_bytes也会进行此类检查。

当您信任您的数据时，您可以使用不安全的from_bytes_unchecked/from_mut_bytes_unchecked省略验证，但如果不正确，这将导致未定义行为。

可移植性

扁平类型保证它在具有相同字节顺序、对齐和地址宽度的平台上具有相同的二进制表示。如果您需要更强的保证，您可以使用Portable类型——它们在任何平台上都具有相同的二进制表示，并且始终对齐到字节。要使自己的扁平类型可移植，请使用#[flat(portable = true)]。此外，这也可以用来创建没有对齐问题的紧凑扁平类型。

示例

您可以在tests目录中找到有关如何创建和使用扁平类型的示例：tests。

许可

根据您的选择，许可如下：

• Apache License，版本2.0（LICENSE-APACHE或https://apache.ac.cn/licenses/LICENSE-2.0）
• MIT许可（LICENSE-MIT或http://opensource.org/licenses/MIT）

。

贡献

除非您明确声明，否则您有意提交以包含在作品中的任何贡献，根据Apache-2.0许可定义，将根据上述内容双许可，而无需任何附加条款或条件。