# bitflags::bitflags! [−] [src]

    macro_rules! bitflags {
        ($(#[$attr:meta])* pub flags $BitFlags:ident: $T:ty {
            $($(#[$Flag_attr:meta])* const $Flag:ident = $value:expr),+
        }) => { ... };
        ($(#[$attr:meta])* flags $BitFlags:ident: $T:ty {
            $($(#[$Flag_attr:meta])* const $Flag:ident = $value:expr),+
        }) => { ... };
        (@_impl flags $BitFlags:ident: $T:ty {
            $($(#[$Flag_attr:meta])* const $Flag:ident = $value:expr),+
        }) => { ... };
        ($(#[$attr:meta])* pub flags $BitFlags:ident: $T:ty {
            $($(#[$Flag_attr:meta])* const $Flag:ident = $value:expr),+,
        }) => { ... };
        ($(#[$attr:meta])* flags $BitFlags:ident: $T:ty {
            $($(#[$Flag_attr:meta])* const $Flag:ident = $value:expr),+,
        }) => { ... };
    }

The `bitflags!` macro generates a `struct` that holds a set of C-style bitmask flags. It is useful for creating typesafe wrappers for C APIs.

The flags should only be defined for integer types, otherwise unexpected type errors may occur at compile time.

# Example

    #![cfg_attr(feature = "assignment_operators", feature(augmented_assignments, op_assign_traits))]
    #[macro_use]
    extern crate bitflags;

    bitflags! {
        flags Flags: u32 {
            const FLAG_A       = 0b00000001,
            const FLAG_B       = 0b00000010,
            const FLAG_C       = 0b00000100,
            const FLAG_ABC     = FLAG_A.bits
                               | FLAG_B.bits
                               | FLAG_C.bits,
        }
    }

    fn main() {
        let e1 = FLAG_A | FLAG_C;
        let e2 = FLAG_B | FLAG_C;
        assert!((e1 | e2) == FLAG_ABC);   // union
        assert!((e1 & e2) == FLAG_C);     // intersection
        assert!((e1 - e2) == FLAG_A);     // set difference
        assert!(!e2 == FLAG_A);           // set complement
    }

The generated `struct`s can also be extended with type and trait implementations:

    #![cfg_attr(feature = "assignment_operators", feature(augmented_assignments, op_assign_traits))]
    #[macro_use]
    extern crate bitflags;

    use std::fmt;

    bitflags! {
        flags Flags: u32 {
            const FLAG_A   = 0b00000001,
            const FLAG_B   = 0b00000010,
        }
    }

    impl Flags {
        pub fn clear(&mut self) {
            self.bits = 0;  // The `bits` field can be accessed from within the
                            // same module where the `bitflags!` macro was invoked.
        }
    }

    impl fmt::Display for Flags {
        fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
            write!(f, "hi!")
        }
    }

    fn main() {
        let mut flags = FLAG_A | FLAG_B;
        flags.clear();
        assert!(flags.is_empty());
        assert_eq!(format!("{}", flags), "hi!");
        assert_eq!(format!("{:?}", FLAG_A | FLAG_B), "FLAG_A | FLAG_B");
        assert_eq!(format!("{:?}", FLAG_B), "FLAG_B");
    }

# Visibility

The generated struct and its associated flag constants are not exported out of the current module by default. A definition can be exported out of the current module by adding `pub` before `flags`:

    #[macro_use]
    extern crate bitflags;

    mod example {
        bitflags! {
            pub flags Flags1: u32 {
                const FLAG_A   = 0b00000001,
            }
        }
        bitflags! {
            flags Flags2: u32 {
                const FLAG_B   = 0b00000010,
            }
        }
    }

    fn main() {
        let flag1 = example::FLAG_A;
        let flag2 = example::FLAG_B; // error: const `FLAG_B` is private
    }

# Attributes

Attributes can be attached to the generated `struct` by placing them before the `flags` keyword.

# Trait implementations

The `Copy`, `Clone`, `PartialEq`, `Eq`, `PartialOrd`, `Ord` and `Hash` traits automatically derived for the `struct` using the `derive` attribute. Additional traits can be derived by providing an explicit `derive` attribute on `flags`.

The `FromIterator` trait is implemented for the `struct`, too, calculating the union of the instances of the `struct` iterated over.

The `Debug` trait is also implemented by displaying the bits value of the internal struct.

## Operators

The following operator traits are implemented for the generated `struct`:

- `BitOr` and `BitOrAssign`: union
- `BitAnd` and `BitAndAssign`: intersection
- `BitXor` and `BitXorAssign`: toggle
- `Sub` and `SubAssign`: set difference
- `Not`: set complement

As long as the assignment operators are unstable rust feature they are only available with the crate feature `assignment_ops` enabled.

# Methods

The following methods are defined for the generated `struct`:

- `empty`: an empty set of flags
- `all`: the set of all flags
- `bits`: the raw value of the flags currently stored
- `from_bits`: convert from underlying bit representation, unless that representation contains bits that do not correspond to a flag
- `from_bits_truncate`: convert from underlying bit representation, dropping any bits that do not correspond to flags
- `is_empty`: `true` if no flags are currently stored
- `is_all`: `true` if all flags are currently set
- `intersects`: `true` if there are flags common to both `self` and `other`
- `contains`: `true` all of the flags in `other` are contained within `self`
- `insert`: inserts the specified flags in-place
- `remove`: removes the specified flags in-place
- `toggle`: the specified flags will be inserted if not present, and removed if they are.

# Help

## Keyboard Shortcuts

?
  Show this help dialog
S
  Focus the search field
⇤
  Move up in search results
⇥
  Move down in search results
⏎
  Go to active search result

## Search Tricks

Prefix searches with a type followed by a colon (e.g. `fn:`) to restrict the search to a given type.

Accepted types are: `fn`, `mod`, `struct`, `enum`, `trait`, `type`, `macro`, and `const`.

Search functions by type signature (e.g. `vec -> usize` or `* -> vec`)