1bitflags
2========
3
4[![Rust](https://github.com/bitflags/bitflags/workflows/Rust/badge.svg)](https://github.com/bitflags/bitflags/actions)
5[![Latest version](https://img.shields.io/crates/v/bitflags.svg)](https://crates.io/crates/bitflags)
6[![Documentation](https://docs.rs/bitflags/badge.svg)](https://docs.rs/bitflags)
7![License](https://img.shields.io/crates/l/bitflags.svg)
8
9`bitflags` generates flags enums with well-defined semantics and ergonomic end-user APIs.
10
11You 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
16You 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
27Add this to your `Cargo.toml`:
28
29```toml
30[dependencies]
31bitflags = "2.6.0"
32```
33
34and this to your source code:
35
36```rust
37use bitflags::bitflags;
38```
39
40## Example
41
42Generate a flags structure:
43
44```rust
45use bitflags::bitflags;
46
47// The `bitflags!` macro generates `struct`s that manage a set of flags.
48bitflags! {
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
64fn 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
76The minimum supported Rust version is documented in the `Cargo.toml` file.
77This may be bumped in minor releases as necessary.
78