| 1 |
bitflags |
| 2 |
======== |
| 3 |
|
| 4 |
[](https://github.com/bitflags/bitflags/actions) |
| 5 |
[](https://crates.io/crates/bitflags) |
| 6 |
[](https://docs.rs/bitflags) |
| 7 |
 |
| 8 |
|
| 9 |
`bitflags` generates flags enums with well-defined semantics and ergonomic end-user APIs. |
| 10 |
|
| 11 |
You can use `bitflags` to: |
| 12 |
|
| 13 |
- provide more user-friendly bindings to C APIs where flags may or may not be fully known in advance. |
| 14 |
- generate efficient options types with string parsing and formatting support. |
| 15 |
|
| 16 |
You can't use `bitflags` to: |
| 17 |
|
| 18 |
- guarantee only bits corresponding to defined flags will ever be set. `bitflags` allows access to the underlying bits type so arbitrary bits may be set. |
| 19 |
- define bitfields. `bitflags` only generates types where set bits denote the presence of some combination of flags. |
| 20 |
|
| 21 |
- [Documentation](https://docs.rs/bitflags) |
| 22 |
- [Specification](https://github.com/bitflags/bitflags/blob/main/spec.md) |
| 23 |
- [Release notes](https://github.com/bitflags/bitflags/releases) |
| 24 |
|
| 25 |
## Usage |
| 26 |
|
| 27 |
Add this to your `Cargo.toml`: |
| 28 |
|
| 29 |
```toml |
| 30 |
[dependencies] |
| 31 |
bitflags = "2.5.0" |
| 32 |
``` |
| 33 |
|
| 34 |
and this to your source code: |
| 35 |
|
| 36 |
```rust |
| 37 |
use bitflags::bitflags; |
| 38 |
``` |
| 39 |
|
| 40 |
## Example |
| 41 |
|
| 42 |
Generate a flags structure: |
| 43 |
|
| 44 |
```rust |
| 45 |
use bitflags::bitflags; |
| 46 |
|
| 47 |
// The `bitflags!` macro generates `struct`s that manage a set of flags. |
| 48 |
bitflags! { |
| 49 |
/// Represents a set of flags. |
| 50 |
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)] |
| 51 |
struct Flags: u32 { |
| 52 |
/// The value `A`, at bit position `0`. |
| 53 |
const A = 0b00000001; |
| 54 |
/// The value `B`, at bit position `1`. |
| 55 |
const B = 0b00000010; |
| 56 |
/// The value `C`, at bit position `2`. |
| 57 |
const C = 0b00000100; |
| 58 |
|
| 59 |
/// The combination of `A`, `B`, and `C`. |
| 60 |
const ABC = Self::A.bits() | Self::B.bits() | Self::C.bits(); |
| 61 |
} |
| 62 |
} |
| 63 |
|
| 64 |
fn main() { |
| 65 |
let e1 = Flags::A | Flags::C; |
| 66 |
let e2 = Flags::B | Flags::C; |
| 67 |
assert_eq!((e1 | e2), Flags::ABC); // union |
| 68 |
assert_eq!((e1 & e2), Flags::C); // intersection |
| 69 |
assert_eq!((e1 - e2), Flags::A); // set difference |
| 70 |
assert_eq!(!e2, Flags::A); // set complement |
| 71 |
} |
| 72 |
``` |
| 73 |
|
| 74 |
## Rust Version Support |
| 75 |
|
| 76 |
The minimum supported Rust version is documented in the `Cargo.toml` file. |
| 77 |
This may be bumped in minor releases as necessary. |