# bitflag-attr
[](https://github.com/GrayJack/bitflag-attr/actions)
[](https://crates.io/crates/bitflag-attr)
[](https://docs.rs/bitflag-attr)
This is a proc-macro Rust crate that allows to turn a C-like enum into a bitflag structures with an API similar to `bitfields` crate.
You can use this crate to:
- provide more user-friendly bindings to C APIs where flags may or may not be fully known in advance.
You can't use this crate to:
- guarantee only bits corresponding to defined flags will ever be set. `bitflag-attr` allows access to the underlying bits type so arbitrary bits may be set.
- define bitfields. `bitflag-attr` only generates types where set bits denote the presence of some combination of flags.
## Implemented traits
The macro requires that `Clone` and `Copy` are derived.
The macro will also implement some traits for bitwise operations and formatting.
- [X] core::ops::Not
- [X] core::ops::BitAnd
- [X] core::ops::BitOr
- [X] core::ops::BitXor
- [X] core::ops::BitAndAssign
- [X] core::ops::BitOrAssign
- [X] core::ops::BitXorAssign
- [X] core::ops::Sub
- [X] core::ops::SubAssign
- [X] core::fmt::Debug (This can be opt-out with the `no_auto_debug`)
- [X] core::fmt::Binary
- [X] core::fmt::UpperHex
- [X] core::fmt::LowerHex
- [X] core::fmt::Octal
- [X] From
If the `Debug` trait is defined in the `#[derive(...)]` attribute. The macro will produce a custom implementation instead of the one Rust std produces
The macro also generate iterator types to iterate over the set flags, and for convenience also implement the following traits:
- [X] core::iter::Extend
- [X] core::iter::FromIterator
- [X] core::iter::Iterator (for the type and reference)
There is a opt-in crate feature `serde` that generate a parsing error type and implements the traits:
- [X] core::str::FromStr
- [X] serde::Serialize
- [X] serde::Deserialize
The custom implementation for `Serialize` and `Deserialize` will be generated only if those traits are in the `#[derive(...)]` attribute list (similar how the `Debug` works).
**Note:** This crate does not import/re-export serde traits, your project MUST have `serde` as dependency.
## Example
Generate a flags structure:
```rust
use bitflag_attr::bitflag;
#[bitflag(u32)]
#[derive(Debug, Clone, Copy, PartialEq, PartialOrd, Eq, Ord, Hash)]
enum Flags {
/// The value `A`, at bit position `0`.
A = 0b00000001,
/// The value `B`, at bit position `1`.
B = 0b00000010,
/// The value `C`, at bit position `2`.
C = 0b00000100,
/// The combination of `A`, `B`, and `C`.
ABC = A | B | C,
}
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
}
```
If you don't want `Debug` trait to be generated, you can simply not define it on the derive attribute to the attribute.
```rust
use bitflag_attr::bitflag;
#[bitflag(u32)]
#[derive(Clone, Copy, PartialEq, PartialOrd, Eq, Ord, Hash)]
enum Flags {
/// The value `A`, at bit position `0`.
A = 0b00000001,
/// The value `B`, at bit position `1`.
B = 0b00000010,
/// The value `C`, at bit position `2`.
C = 0b00000100,
/// The combination of `A`, `B`, and `C`.
ABC = A | B | C,
}
```
## Rust Version Support
The minimum supported Rust version is documented in the `Cargo.toml` file.
This may be bumped in minor releases as necessary.