#bit-flags

macro no-std bitflag-attr

A macro to generate bitflags structures from C-like enums

4 releases (2 breaking)

new 0.3.1 Oct 19, 2024
0.3.0 May 16, 2024
0.2.0 May 15, 2024
0.1.0 May 15, 2024

#148 in No standard library

Download history 14/week @ 2024-07-01 7/week @ 2024-07-08 22/week @ 2024-07-15 43/week @ 2024-09-23 18/week @ 2024-09-30 24/week @ 2024-10-07 174/week @ 2024-10-14

259 downloads per month

MIT/Apache

32KB
666 lines

bitflag-attr

Rust Latest version Documentation License

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 will also implement some traits for bitwise operations and formatting.

  • core::ops::Not
  • core::ops::BitAnd
  • core::ops::BitOr
  • core::ops::BitXor
  • core::ops::BitAndAssign
  • core::ops::BitOrAssign
  • core::ops::BitXorAssign
  • core::ops::Sub
  • core::ops::SubAssign
  • core::fmt::Debug
  • core::fmt::Binary
  • core::fmt::UpperHex
  • core::fmt::LowerHex
  • core::fmt::Octal
  • From
  • Clone
  • Copy

Besides the Debug, Clone and Copy traits, all other derivable traits can be used together with the type

Example

Generate a flags structure

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,
}

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
}

Rust Version Support

The minimum supported Rust version is documented in the Cargo.toml file. This may be bumped in minor releases as necessary.

Dependencies

~260–710KB
~17K SLoC