EnumBitFlags

A proc-macro crate for Rust that allows creating bit flags enums.

How to use:

1. First you need to this crate to your cargo.toml file:

[dependencies]
EnumBitFlags = "1.0.8"

2. Then, you can use it in your Rust project like this:

#[EnumBitFlags]
enum MyFlags {
  Flag_1 = 0x0001,
  Flag_2 = 0x0002,
  Flag_3 = 0x0004
}

fn main() {
  let flags = MyFlags::Flag_1 | MyFlags::Flag_2;
  
  // check if a flag is set (via .contains(...) method)
  if flags.contains(MyFlags::Flag_1) {
    println!("Flag_1 is present");
  }
  
  // check if a flag is set (via AND operation)
  if (flags & MyFlags::Flag_2) == MyFlags::Flag_2 {
    println!("Flag_2 is present");
  }
}

Moreover, the following function allows you to create an object from a numeric value: fn from_value(value: T) -> Option<Self> where T is an unsigned numeric type (u8, u16, u32, u64).

#[EnumBitFlags]
enum MyFlags {
  Flag_1 = 0x0001,
  Flag_2 = 0x0002,
  Flag_3 = 0x0004
}

fn main() {
  if let Some(y) = MyFlags::from_value(5) {
        println!("{y}");
    }
    else {
        eprintln!("Could not create value!");
    }
}

Arguments

EnumBitFlags supports various arguments that provide additional information on how to build the enum. Arguments are specified in the EnumBitFlags arguments with the following format: key=value,key=value,.... Alternativelly, you can use : instead of = (key:value, key:value....)

• bits In-memory representation of the bitfield. It could be one of the following:8, 16, 32, 64 or 128. If not specified the default value is 32. Example

  #[EnumBitFlags(bits=8)]
  enum MyFlags {
    Flag_1 = 0x01,
    Flag_2 = 0x02,
    Flag_3 = 0x04
  }

• empty The name of the empty variant. An empty variant is the case where not bits are being set up. If not specified, None will be generated. The name of the empty variant must NOT be present in the enum variants and must start with a letter or underline character and can contain letters, numbers and the underline character. Example

  #[EnumBitFlags(empty=Nothing)]
  enum MyFlags {
    Flag_1 = 1,
    Flag_2 = 2,
    Flag_3 = 4
  }
  
  fn main() {
    let f = MyFlags::Nothing;
  }

• disable_empty_generation Disables the generation of an empty (value 0) variant. By default this is None but the name can be changed by using the empty attribute. This attribute will also disable any manual variant with value 0 (e.g. No_flag = 0) Example

  #[EnumBitFlags(disable_empty_generation=true)]
  enum MyFlags {
    Flag_1 = 1,
    Flag_2 = 2,
    Flag_3 = 4
  }
  
  fn main() {
    let f = MyFlags::None; // this code will produce an error as variant None will not be generated
  }

  • debug Will print the resulted structure after parsing. Example

  #[EnumBitFlags(debug=true)]
  enum MyFlags {
    Flag_1 = 1,
    Flag_2 = 2,
    Flag_3 = 4
  }

Methods

Every EnumBitFlags has several methods that can be used to easily manipulate and chek bits status:

Method	Description
obj.contains(mask)	Returns true if all set bits from the mask are present in the object, or false otherwise
obj.contains_one(mask)	Returns true if at least one bit from the mask is present in the object, or false otherwise
obj.clear()	Clears all bits from the current object
obj.is_empty()	Returns true if not bits are set, false otherwise
obj.remove(mask)	Removes all set flags from the mask
obj.set(mask)	Set all bits from the mask
obj.get_value()	Returns the numerical value associated to the bit mask flags

• contains Checks if an exact bitflag mask is present

  fn contains(&self, obj: <EnumName>) -> bool

  The obj must not be empty (at least one bit has to be set) and all bits from the object must be present. Example:

  #[EnumBitFlags]
  enum MyFlags { A = 1, B = 2, C = 4 }
  
  fn main() {
     let t = MyFlags::A | MyFlags::B;
     if t.contains(MyFlags::A) { 
       /* this code will be executed */ 
     }
     if t.contains(MyFlags::A | MyFlags::B) {
       /* this code will be executed */ 
     }
     if t.contains(MyFlags::A | MyFlags::C) {
       /* this code WILL NOT BE REACHED as flags C is not set in variable t */
     }
  }

• contains_one Checks if at least one bit from the mask is present in the object

  fn contains_one(&self, mask: <EnumName>) -> bool

  The obj must not be empty (at least one bit has to be set) . Example:

  #[EnumBitFlags]
  enum MyFlags { A = 1, B = 2, C = 4 }
  
  fn main() {
     let t = MyFlags::A | MyFlags::B;
     if t.contains_one(MyFlags::A) { 
       /* this code will be executed */ 
     }
     if t.contains_one(MyFlags::A | MyFlags::B) {
       /* this code will be executed */ 
     }
     if t.contains_one(MyFlags::A | MyFlags::C) {
       /* this code will be executed */
     }
  }

• clear Clears all bits from the enum

  fn clear(&mut self) 

  Example:

  #[EnumBitFlags]
  enum MyFlags { A = 1, B = 2, C = 4 }
  
  fn main() {
     let mut t = MyFlags::A | MyFlags::B;
     if t.contains_one(MyFlags::A) { 
       /* this code will be executed */ 
     }
     t.clear();
     if t.contains(MyFlags::A) {
       /* this code will NOT BE REACHED as t was cleared */ 
     }
  }