bit_collection

Rust库，允许遍历集合中的位。

文档

许可证

本项目可以以以下任一方式发布：

• MIT许可证

• Apache许可证（版本2.0）

由您选择。

lib.rs:

遍历位集合。

用法

此crate在crates.io上可用，可以通过将以下内容添加到项目的Cargo.toml中使用

[dependencies]
bit_collection = "0.2.3"

并添加以下内容到crate根目录

#[macro_use]
extern crate bit_collection;

#[bit] 属性

#[bit] 属性由三部分组成，其中两部分在某些情况下是可选的。组件可以按任何顺序提供。

类型

表示单个位的类型。这部分是必需的。

#[bit(Type, ...)]

掩码

表示集合中有效位的掩码。这应该是一个常量表达式。

如果没有提供，则假定掩码设置了所有位（即 !0）。

BitCollection::FULL 返回此值。

注意：请阅读有关安全性的部分，以确保以正确和安全的方式使用。

#[bit(..., mask = "0b11", ...)]

检索器

用于检索位类型内部整数值的后缀。它扩展为 $value.$retr。因此，提供的检索器必须在派生处可见。

如果没有提供，则假定位类型是可以转换为整数的枚举。

#[bit(..., retr = "inner", ...)]

迭代器

给定 BitCollection 的迭代器。如果 BitIter 没有直接导入，此选项允许指定其模块路径。

extern crate bit_collection as bc;

#[bit(..., iter = "bc::BitIter", ...)]

示例

在计算机国际象棋中，表示棋盘上占据者的一个流行方法是使用 Bitboard 类型。在此类型中，每个单独的位都是棋盘上的一个方块。

#[derive(Copy, Clone)]
pub struct Square(u8);

/// A set of sixty-four `Square`s.
#[bit(Square, mask = "!0", retr = "0")]
#[derive(BitCollection)]
pub struct Bitboard(u64);

我们也可以用这种方式表示王车易位权。

#[derive(Copy, Clone)]
pub enum CastleRight {
    WhiteKingside,
    BlackKingside,
    WhiteQueenside,
    BlackQueenside,
}

/// A set of `CastleRight`s.
#[bit(CastleRight, mask = "0b1111")]
#[derive(BitCollection)]
pub struct CastleRights {
    bits: u8
}

fn iterate_over(rights: CastleRights) {
    for right in rights {
        match right {
            CastleRight::WhiteKingside  => { /* ... */ },
            CastleRight::BlackKingside  => { /* ... */ },
            CastleRight::WhiteQueenside => { /* ... */ },
            CastleRight::BlackQueenside => { /* ... */ },
        }
    }
}

安全性

此 crate 做了一些假设，如果这些假设没有得到满足，可能会产生不安全和意外的结果。

对于 #[bit] 的 mask 选项 必须 设置正确的位。它 不得 设置与位类型无效实例相对应的位。

同样，位类型必须定义得使 mask 中对应的位模式提供合法值。问问自己，1 << item 和其反转（撤销）操作，pop_{lsb,msb}，在提供的掩码下有意义吗？