Macro new_bitflags::new_bitflags

macro_rules! new_bitflags {
    ( $(#[$attr:meta])* pub flags $name:ident : $inner:ty
            { $( $(#[$flag_attr:meta])* const $flag:ident = $value:expr ; )* } ) => { ... };
    ( $(#[$attr:meta])* flags $name:ident : $inner:ty
            { $( $(#[$flag_attr:meta])* const $flag:ident = $value:expr ; )* } ) => { ... };
    ( @_impl $name:ident : $inner:ty
            { $( $(#[$flag_attr:meta])* const $flag:ident = $value:expr ; )* } ) => { ... };
}

Generates a bitflags type, wrapping a given primitive integer type.

Example

The following macro invocation will create a struct Foo:

#[macro_use] extern crate new_bitflags;

new_bitflags!{
    pub flags Foo: u32 {
        const flag_a = 1 << 0;
        const flag_b = 1 << 1;
        const flag_c = 1 << 2;
    }
}

impl Foo {
    pub fn flag_abc() -> Foo {
        Foo::flag_a() |
        Foo::flag_b() |
        Foo::flag_c()
    }
}

fn main() {
    let f1 = Foo::flag_a() | Foo::flag_c();
    let f2 = Foo::flag_b() | Foo::flag_c();

    assert_eq!((f1 | f2), Foo::flag_abc()); // union
    assert_eq!((f1 & f2), Foo::flag_c());   // intersection
    assert_eq!((f1 - f2), Foo::flag_a());   // difference
    assert_eq!(!f2,       Foo::flag_a());   // complement
}

The generated struct can be extended with type and trait impls.

impl Foo {
    pub fn is_flag_a(&self) -> bool {
        self.contains(Foo::flag_a())
    }
}

Visibility

The visibility of the generated struct can be controlled within the invocation of new_bitflags!

#[macro_use] extern crate new_bitflags;

mod example {
    // `struct Public` will be visible outside this module.
    new_bitflags!{
        pub flags Public: u32 {
            // ...
        }
    }

    // `struct Private` will not be visible outside this module.
    new_bitflags!{
        flags Private: u32 {
            // ...
        }
    }
}

Trait implementations

Generated struct types will have derived implementations of the following traits: Copy, Clone, Hash, PartialEq, Eq, PartialOrd, and Ord.

The traits Extend and FromIterator are implemented for sequences of Self and &Self.

The Debug trait implementation will display the set of named flags contained in a set.

Operators

The following operators are implemented for generated struct types:

• BitOr and BitOrAssign perform union
• BitAnd and BitAndAssign perform intersection
• BitXor and BitXorAssign perform toggle
• Sub and SubAssign perform set difference
• Not performs set complement

Methods

The following methods are implemented for generated struct types:

• fn from_bits(bits) -> Option<Self> converts from underlying bits, checking that all bits correspond to defined flags.
• fn from_bits_truncate(bits) -> Option<Self> converts from underlying bits, truncating any bits that do not correspond to defined flags.
• fn bits(&self) -> bits returns the underlying bits
• fn contains(&self, other: Self) -> bool returns whether the set contains all flags present in other
• fn clear(&mut self) clears all flags on the set
• fn all() -> Self returns all defined flags
• fn empty() -> Self returns an empty set
• fn is_all(&self) -> bool returns whether the set contains all flags
• fn is_empty(&self) -> bool returns whether the set is empty
• fn intersects(&self, other: Self) -> bool returns whether any flags are common between self and other.
• fn insert(&mut self, other: Self) inserts all flags in other
• fn remove(&mut self, other: Self) removes all flags in other
• fn toggle(&mut self, other: Self) toggles all flags in other
• fn set(&mut self, other: Self, value: bool) sets or removes all flags in other, depending on boolean value

Additionally, for each defined flag, a static method of signature fn() -> Self is defined, returning a set containing only the named flag.