Crate enumflags2

Enum Flags

enumflags2 implements the classic bitflags datastructure. Annotate an enum with #[bitflags], and BitFlags<YourEnum> will be able to hold arbitrary combinations of your enum within the space of a single integer.

Example

use enumflags2::{bitflags, make_bitflags, BitFlags};

#[bitflags]
#[repr(u8)]
#[derive(Copy, Clone, Debug, PartialEq)]
enum Test {
    A = 0b0001,
    B = 0b0010,
    C, // unspecified variants pick unused bits automatically
    D = 0b1000,
}

// Flags can be combined with |, this creates a BitFlags of your type:
let a_b: BitFlags<Test> = Test::A | Test::B;
let a_c = Test::A | Test::C;
let b_c_d = make_bitflags!(Test::{B | C | D});

// The debug output lets you inspect both the numeric value and
// the actual flags:
assert_eq!(format!("{:?}", a_b), "BitFlags<Test>(0b11, A | B)");

// But if you'd rather see only one of those, that's available too:
assert_eq!(format!("{}", a_b), "A | B");
assert_eq!(format!("{:04b}", a_b), "0011");

// Iterate over the flags like a normal set
assert_eq!(a_b.iter().collect::<Vec<_>>(), &[Test::A, Test::B]);

// Query the contents with contains and intersects
assert!(a_b.contains(Test::A));
assert!(b_c_d.contains(Test::B | Test::C));
assert!(!(b_c_d.contains(a_b)));

assert!(a_b.intersects(a_c));
assert!(!(a_b.intersects(Test::C | Test::D)));

Optional Feature Flags

• serde implements Serialize and Deserialize for BitFlags<T>.
• std implements std::error::Error for FromBitsError.

const fn-compatible APIs

Background: The subset of const fn features currently stabilized is pretty limited. Most notably, const traits are still at the RFC stage, which makes it impossible to use any overloaded operators in a const context.

Naming convention: If a separate, more limited function is provided for usage in a const fn, the name is suffixed with _c.

Blanket implementations: If you attempt to write a const fn ranging over T: BitFlag, you will be met with an error explaining that currently, the only allowed trait bound for a const fn is ?Sized. You will probably want to write a separate implementation for BitFlags<T, u8>, BitFlags<T, u16>, etc — best accomplished by a simple macro.

Documentation considerations: The strategy described above is often used by enumflags2 itself. To avoid clutter in the auto-generated documentation, the implementations for widths other than u8 are marked with #[doc(hidden)].

Customizing Default

By default, creating an instance of BitFlags<T> with Default will result in an empty set. If that’s undesirable, you may customize this:

#[bitflags(default = B | C)]
#[repr(u8)]
#[derive(Copy, Clone, Debug, PartialEq)]
enum Test {
    A = 0b0001,
    B = 0b0010,
    C = 0b0100,
    D = 0b1000,
}

assert_eq!(BitFlags::default(), Test::B | Test::C);

Macros

• make_bitflags
  make_bitflags! provides a succint syntax for creating instances of BitFlags<T>. Instead of repeating the name of your type for each flag you want to add, try make_bitflags!(Flags::{Foo | Bar}).

Structs

• BitFlags
  Represents a set of flags of some type T. T must have the #[bitflags] attribute applied.
• ConstToken
  Workaround for const fn limitations.
• FromBitsError
  The error struct used by BitFlags::from_bits and the TryFrom implementation for invalid values.
• Iter
  Iterator that yields each flag set in a BitFlags.

Traits

• BitFlag
  A trait automatically implemented by #[bitflags] to make the enum a valid type parameter for BitFlags<T>.