1个不稳定版本

0.11.2	2021年5月22日

#728 在数据结构

2,418 每月下载
用于 5 个crate (3 直接)

MIT/Apache

58KB
686 行

用于Rust的模块化位字段（MSB优先）

持续集成	文档	Crates.io	LoC

no_std：支持无需std库的嵌入式开发。
该crate使用并生成100%安全的Rust代码。

MSB优先版本

该crate是modular-bitfield的分支。用法与原版相同，但有两大关键区别

字段按MSB到LSB的顺序排列。
跨越多个字节的字段以大端格式存储。

描述

允许拥有类似于C和C++位字段的位字段结构和枚举作为位字段说明符。

优点

安全性：宏包含的枚举和结构在编译时检查有效结构。
速度：生成的代码与手写代码一样快。（见下面的基准测试。）
模块化：枚举可以在位字段结构内部使用模块化。

归属

实现了David Tolnay在过程宏研讨会中引入和指定的#[bitfield]宏。

感谢David Tolnay设计了该crate中实现的宏的规范。

用法

使用#[bitfield]属性注释Rust结构体，以便将其转换为位字段。可以使用B1、B2、... B128预lude类型作为原语来声明每个字段的位数。

#[bitfield]
pub struct PackedData {
    header: B4,
    body: B9,
    is_alive: B1,
    status: B2,
}

这会生成一个new构造函数以及各种获取器和设置器，允许以安全的方式与位字段交互

示例：构造函数

let data = PackedData::new()
    .with_header(1)
    .with_body(2)
    .with_is_alive(0)
    .with_status(3);
assert_eq!(data.header(), 1);
assert_eq!(data.body(), 2);
assert_eq!(data.is_alive(), 0);
assert_eq!(data.status(), 3);

示例：原语类型

实现了 Specifier 特性的任何类型都可以用作位域字段。除了已经提到的 B1，.. B128，还可以使用从预定义中引入的 bool、u8、u16、u32、u64 或 u128 原始类型。

我们可以利用这个知识将 is_alive 编码为 bool 类型，而不是使用 B1

#[bitfield]
pub struct PackedData {
    header: B4,
    body: B9,
    is_alive: bool,
    status: B2,
}

let mut data = PackedData::new()
    .with_is_alive(true);
assert!(data.is_alive());
data.set_is_alive(false);
assert!(!data.is_alive());

示例：枚举指定符

可以为枚举类型轻松派生 Specifier 特性，使它们也可以作为位域类型中的字段使用。

#[derive(BitfieldSpecifier)]
pub enum Status {
    Red, Green, Yellow, None,
}

#[bitfield]
pub struct PackedData {
    header: B4,
    body: B9,
    is_alive: bool,
    status: Status,
}

示例：额外的安全性保护

为了确保我们的 Status 枚举恰好需要 2 位，我们可以向其字段添加 #[bits = 2]

#[bitfield]
pub struct PackedData {
    header: B4,
    body: B9,
    is_alive: bool,
    #[bits = 2]
    status: Status,
}

设置和获取新的 status 字段是自然而然的，如下所示

let mut data = PackedData::new()
    .with_status(Status::Green);
assert_eq!(data.status(), Status::Green);
data.set_status(Status::Red);
assert_eq!(data.status(), Status::Red);

示例：递归位域

可以将 #[bitfield] 结构体用作 #[bitfield] 结构体的字段。如果多个位域有共同的字段，这通常很有用，可以通过向具有 #[derive(BitfieldSpecifier)] 属性的 #[bitfield] 标注结构体添加 #[derive(BitfieldSpecifier)] 来实现。

#[bitfield] #[derive(BitfieldSpecifier)] pub struct Header { is_compact: bool, is_secure: bool, pre_status: Status, } #[bitfield] pub struct PackedData { header: Header, body: B9, is_alive: bool, status: Status, } 通过 Header 结构体上的 #[bitfield] 宏和 #[derive(BitfieldSpecifier)] 上 Status 枚举的 #[bits: int] 属性，我们可以对结果的位宽有额外的编译时保证。 #[derive(BitfieldSpecifier)] #[bits = 2] pub enum Status { Red, Green, Yellow } #[bitfield(bits = 4)] #[derive(BitfieldSpecifier)] pub struct Header { is_compact: bool, is_secure: bool, #[bits = 2] pre_status: Status, } #[bitfield(bits = 16)] pub struct PackedData { #[bits = 4] header: Header, body: B9, is_alive: bool, #[bits = 2] status: Status, } 示例：高级枚举指定符对于我们的Status枚举，我们实际上只需要3个状态变体：Green、Yellow和Red。我们引入了None状态变体，因为默认情况下，Specifier枚举需要具有2的幂次方数量的变体。我们可以通过在顶部指定#[bits = 2]来规避这个问题，从而去除我们的占位符None变体，同时保持它需要2位的不可变特性。 # use modular_bitfield_msb::prelude::*; #[derive(BitfieldSpecifier)] #[bits = 2] pub enum Status { Red, Green, Yellow, } 然而，现在拥有这样的枚举可能会导致位字段可能包含此类字段无效的位模式。我们可以安全地使用受保护的getter访问这些字段。为了演示，我们将使用生成的from_bytes构造函数，它使我们能够轻松构造可能包含无效位模式的位字段。 let mut data = PackedData::from_bytes([0b0000_0000, 0b1100_0000]); // The 2 status field bits are invalid -----^^ // as Red = 0x00, Green = 0x01 and Yellow = 0x10 assert_eq!(data.status_or_err(), Err(InvalidBitPattern { invalid_bytes: 0b11 })); data.set_status(Status::Green); assert_eq!(data.status_or_err(), Ok(Status::Green)); 基准测试以下是一些基准测试，比较了手写代码和为一些示例getter和setter生成的宏代码，这些getter和setter涵盖了相当广泛的使用场景。我们可以得出结论，宏生成的代码与手写代码一样快。如果您看到改进任何一方的途径，请提交PR。 cargo bench以运行基准测试 cargo test --benches以运行基准测试测试点击此处查看所有基准测试结果。摘要 modular_bitfield_msb包生成的位字段与... 手写代码一样高效。与替代的bitfield包同样高效或更高效。展示：生成与手写我们测试了以下#[bitfield] struct #[bitfield] pub struct Generated { pub a: B9, // Spans 2 bytes. pub b: B6, // Within 2nd byte. pub c: B13, // Spans 3 bytes. pub d: B1, // Within 4rd byte. pub e: B3, // Within 4rd byte. pub f: B32, // Spans rest 4 bytes. } 注意：所有基准测试时间结果总计为10次运行。 getter性能 get_a/generated time: [3.0990 ns 3.1119 ns 3.1263 ns] get_a/handwritten time: [3.1072 ns 3.1189 ns 3.1318 ns] get_b/generated time: [3.0859 ns 3.0993 ns 3.1140 ns] get_b/handwritten time: [3.1062 ns 3.1154 ns 3.1244 ns] get_c/generated time: [3.0892 ns 3.1140 ns 3.1491 ns] get_c/handwritten time: [3.1031 ns 3.1144 ns 3.1266 ns] get_d/generated time: [3.0937 ns 3.1055 ns 3.1182 ns] get_d/handwritten time: [3.1109 ns 3.1258 ns 3.1422 ns] get_e/generated time: [3.1009 ns 3.1139 ns 3.1293 ns] get_e/handwritten time: [3.1217 ns 3.1366 ns 3.1534 ns] get_f/generated time: [3.1064 ns 3.1164 ns 3.1269 ns] get_f/handwritten time: [3.1067 ns 3.1221 ns 3.1404 ns] setter性能 set_a/generated time: [15.784 ns 15.855 ns 15.932 ns] set_a/handwritten time: [15.841 ns 15.907 ns 15.980 ns] set_b/generated time: [20.496 ns 20.567 ns 20.643 ns] set_b/handwritten time: [20.319 ns 20.384 ns 20.454 ns] set_c/generated time: [19.155 ns 19.362 ns 19.592 ns] set_c/handwritten time: [19.265 ns 19.383 ns 19.523 ns] set_d/generated time: [12.325 ns 12.376 ns 12.429 ns] set_d/handwritten time: [12.416 ns 12.472 ns 12.541 ns] set_e/generated time: [20.460 ns 20.528 ns 20.601 ns] set_e/handwritten time: [20.473 ns 20.534 ns 20.601 ns] set_f/generated time: [6.1466 ns 6.1769 ns 6.2127 ns] set_f/handwritten time: [6.1467 ns 6.1962 ns 6.2670 ns] 许可证根据您的选择，许可协议为Apache License, Version 2.0或MIT许可证。除非您明确说明，否则根据Apache-2.0许可证定义的，您有意提交以包含在此代码库中的任何贡献，都将按照上述方式双重许可，而无需任何额外条款或条件。

依赖关系 ~1.5MB ~36K SLoC modular-bitfield-msb-impl static_assertions dev bitfield dev criterion 0.3 dev trybuild