structview

structview 是一个 Rust 库，用于将二进制数据的引用转换为更高层次的数据结构的引用，例如结构体、联合体和数组。

实现的方法类似于在 C 中解析二进制数据格式时常用的模式，其中表示原始数据的 char * 直接转换为结构体指针等。这种技术具有简单和高效的优势。不幸的是，它也是不安全的，因为通常会忽略对齐和整数字节序的问题。 structview 通过为用户提供安全的接口来避免这些问题。

此 crate 的预期用例是解析二进制数据格式，尤其是如果只对某些字段的值感兴趣，而不是所有字段。在这些情况下，structview 可以用来高效地找到感兴趣的字段，而无需对无关的字段进行潜在的字节序转换。如果所有字段都需要解析，则直接使用 byteorder crate 可能更直接。

示例

以下示例演示了将二进制数据切片视为简单结构体的过程

use structview::{u32_le, View};

#[derive(Clone, Copy, View)]
#[repr(C)]
struct Animal {
    name: [u8; 4],
    number_of_heads: u8,
    number_of_legs: u32_le,
}

fn main() -> Result<(), structview::Error> {
    let data = [0x43, 0x61, 0x74, 0x00, 0x01, 0x04, 0x00, 0x00, 0x00];
    let animal = Animal::view(&data)?;

    assert_eq!(animal.name, *b"Cat\x00");
    assert_eq!(animal.number_of_heads, 1);
    assert_eq!(animal.number_of_legs.to_int(), 4);

    Ok(())
}

如示例所示，structview 通过提供 一个可自动派生的 trait View 以及 用于安全查看整数字段的类型，使得重新解释原始数据既安全又方便。

要求

需要 Rust 版本 1.38.0 或更高版本。

View Trait

通过实现 View trait，类型保证可以从原始二进制数据安全地转换为。该 trait 为实现类型添加了几个视图方法，使得可以从字节切片生成这些类型的实例的引用。

pub unsafe trait View: Copy {
    fn view(data: &[u8]) -> Result<&Self, structview::Error> { ... }
    fn view_slice(data: &[u8]) -> Result<&[Self], Error> { ... }
    fn view_boxed_slice(data: Box<[u8]>) -> Result<Box<[Self]>, Error> { ... }
}

所有视图方法都会检查给定 data 的长度，如果字节数太少，则返回 Error::NotEnoughData。此外，两个切片视图方法还要求 mem::size_of::<Self>() > 0，否则会引发恐慌。

实现 View 是不安全的，因为必须确保

• 每个可能的原始字节数值都构成实现类型的有效数据
• 实现类型是 1 字节对齐的
• 编译器不会改变实现类型字段的顺序（在复合类型的情况下）

structview 已经为 1 字节整数类型（i8 和 u8）、View 类型数组以及提供的整数视图（u32_le 和朋友）实现了 View。基于这些原语，用户可以为自己的结构体和联合体创建视图。

[dependencies.structview]
version = "1"
default-features = false