Enumflags

enumflags2 实现了经典的位标志数据结构。使用 #[bitflags] 注释枚举，BitFlags<YourEnum> 就可以存储任意组合的枚举值，占用单个整数的空间。

功能

• 使用枚举表示单个标志，一组标志是一个独立的类型。
• 如果没有指定，自动选择一个空闲位。
• 在编译时检测到不正确的 BitFlags。
• 与流行的 bitflags crate 具有相似的 API。
• 不显式暴露生成的类型。用户只与 struct BitFlags<Enum>; 进行交互。
• 调试格式化程序同时打印二进制标志值以及标志枚举： BitFlags(0b1111, [A, B, C, D])。
• 可选支持使用 serde 功能标志进行序列化。

示例

use enumflags2::{bitflags, make_bitflags, BitFlags};

#[bitflags]
#[repr(u8)]
#[derive(Copy, Clone, Debug, PartialEq)]
enum Test {
    A = 0b0001,
    B = 0b0010,
    C, // unspecified variants pick unused bits automatically
    D = 0b1000,
}

// Flags can be combined with |, this creates a BitFlags of your type:
let a_b: BitFlags<Test> = Test::A | Test::B;
let a_c = Test::A | Test::C;
let b_c_d = make_bitflags!(Test::{B | C | D});

// The debug output lets you inspect both the numeric value and
// the actual flags:
assert_eq!(format!("{:?}", a_b), "BitFlags<Test>(0b11, A | B)");

// But if you'd rather see only one of those, that's available too:
assert_eq!(format!("{}", a_b), "A | B");
assert_eq!(format!("{:04b}", a_b), "0011");

// Iterate over the flags like a normal set
assert_eq!(a_b.iter().collect::<Vec<_>>(), &[Test::A, Test::B]);

// Query the contents with contains and intersects
assert!(a_b.contains(Test::A));
assert!(b_c_d.contains(Test::B | Test::C));
assert!(!(b_c_d.contains(a_b)));

assert!(a_b.intersects(a_c));
assert!(!(a_b.intersects(Test::C | Test::D)));

可选功能标志

• serde 实现了为 BitFlags<T> 提供 Serialize 和 Deserialize 功能。
• std 为 FromBitsError 实现了 std::error::Error。

const fn-兼容的 API

背景： 目前稳定下来的 const fn 功能子集相当有限。最值得注意的是，const 特性仍然处于 RFC 阶段，这使得在 const 上下文中无法使用任何重载运算符。

命名约定： 如果为 const fn 提供了一个单独的、更有限的功能，则该名称后缀为 _c。

泛型实现： 如果您尝试编写一个遍历 T: BitFlag 的 const fn，您将遇到一个错误，解释说目前，const fn 的唯一允许特性约束是 ?Sized。您可能想为 BitFlags<T, u8>、BitFlags<T, u16> 等编写单独的实现——这些实现可能由宏生成。这种策略经常被 enumflags2 本身使用；为了避免混乱，文档中只显示了其中一个副本。

#[bitflags(default = B | C)]
#[repr(u8)]
#[derive(Copy, Clone, Debug, PartialEq)]
enum Test {
    A = 0b0001,
    B = 0b0010,
    C = 0b0100,
    D = 0b1000,
}

assert_eq!(BitFlags::default(), Test::B | Test::C);