一个用于C样式位掩码标志集合的类型安全位掩码标志生成器。它可以用于在C API周围创建类型安全的包装器。

bitflags! 宏生成一个管理一组标志的 struct。标志应仅针对整数类型定义，否则在编译时可能会出现意外的类型错误。

示例

extern crate bitflags;

bitflags::bitflags! {
    struct Flags: u32 {
        const A = 0b00000001;
        const B = 0b00000010;
        const C = 0b00000100;
        const ABC = Self::A.bits | Self::B.bits | Self::C.bits;
    }
}

fn main() {
    let e1 = Flags::A | Flags::C;
    let e2 = Flags::B | Flags::C;
    assert_eq!((e1 | e2), Flags::ABC);   // union
    assert_eq!((e1 & e2), Flags::C);     // intersection
    assert_eq!((e1 - e2), Flags::A);     // set difference
    assert_eq!(!e2, Flags::A);           // set complement
}

有关上述 bitflags! 扩展生成的代码的文档，请参阅 example_generated::Flags。

生成的 struct 也可以通过类型和特性实现进行扩展

extern crate bitflags;

use std::fmt;

bitflags::bitflags! {
    struct Flags: u32 {
        const A = 0b00000001;
        const B = 0b00000010;
    }
}

impl Flags {
    pub fn clear(&mut self) {
        self.bits = 0;  // The `bits` field can be accessed from within the
                        // same module where the `bitflags!` macro was invoked.
    }
}

impl fmt::Display for Flags {
    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
        write!(f, "hi!")
    }
}

fn main() {
    let mut flags = Flags::A | Flags::B;
    flags.clear();
    assert!(flags.is_empty());
    assert_eq!(format!("{}", flags), "hi!");
    assert_eq!(format!("{:?}", Flags::A | Flags::B), "A | B");
    assert_eq!(format!("{:?}", Flags::B), "B");
}

可见性

默认情况下，生成的结构和相关的标志常量不会被导出至当前模块之外。可以通过在 flags 前添加 pub 将定义导出至当前模块之外。

extern crate bitflags;

mod example {
    bitflags::bitflags! {
        pub struct Flags1: u32 {
            const A = 0b00000001;
        }
    }
    bitflags::bitflags! {
        struct Flags2: u32 {
            const B = 0b00000010;
        }
    }
}

fn main() {
    let flag1 = example::Flags1::A;
    let flag2 = example::Flags2::B; // error: const `B` is private
}

属性

可以通过在 flags 关键字之前放置它们来将属性附加到生成的 struct。

特性实现

Copy、Clone、PartialEq、Eq 和 Hash 特性通过使用 derive 属性自动派生到 struct。可以通过在 flags 上提供显式的 derive 属性来派生其他特性。

为 struct 实现了 Extend 和 FromIterator 特性：Extend 添加了迭代过的 struct 实例的并集，而 FromIterator 计算并集。

通过显示内部结构的位值，还实现了 Binary、Debug、LowerExp、Octal 和 UpperExp 特性。

运算符

为生成的 struct 实现了以下运算符特性

• BitOr 和 BitOrAssign：并集
• BitAnd 和 BitAndAssign：交集
• BitXor 和 BitXorAssign：切换
• Sub 和 SubAssign：集合差
• Not：集合补

方法

以下方法定义于生成的 struct

• empty：空的标志集合
• all：所有标志的集合
• bits：当前存储的标志的原始值
• from_bits：从底层的位表示转换，除非该表示包含不对应于标志的位
• from_bits_truncate：从底层的位表示转换，丢弃任何不对应于标志的位
• is_empty：如果没有存储任何标志，返回 true
• is_all：如果所有标志都已设置，返回 true
• intersects：如果 self 和 other 有共同的标志，返回 true
• contains：如果 other 中的所有标志都包含在 self 中，返回 true
• insert：就地插入指定的标志
• remove：就地移除指定的标志
• toggle：如果指定的标志不存在，则将其插入；如果已存在，则将其移除
• set：根据传入的值插入或移除指定的标志

默认值

生成的结构体不会自动实现 Default 特性。

如果您的默认值等于 0（这等于在生成的结构体上调用 empty()），您可以直接派生 Default

extern crate bitflags;

bitflags::bitflags! {
    // Results in default value with bits: 0
    #[derive(Default)]
    struct Flags: u32 {
        const A = 0b00000001;
        const B = 0b00000010;
        const C = 0b00000100;
    }
}

fn main() {
    let derived_default: Flags = Default::default();
    assert_eq!(derived_default.bits(), 0);
}

extern crate bitflags;

bitflags::bitflags! {
    struct Flags: u32 {
        const A = 0b00000001;
        const B = 0b00000010;
        const C = 0b00000100;
    }
}

// explicit `Default` implementation
impl Default for Flags {
    fn default() -> Flags {
        Flags::A | Flags::C
    }
}

fn main() {
    let implemented_default: Flags = Default::default();
    assert_eq!(implemented_default, (Flags::A | Flags::C));
}