Crate bitflags

A typesafe bitmask flag generator useful for sets of C-style bitmask flags. It can be used for creating typesafe wrappers around C APIs.

The bitflags! macro generates a struct that manages a set of flags. The flags should only be defined for integer types, otherwise unexpected type errors may occur at compile time.

Example

#[macro_use]
extern crate bitflags;

bitflags! {
    struct 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_eq!((e1 | e2), FLAG_ABC);   // union
    assert_eq!((e1 & e2), FLAG_C);     // intersection
    assert_eq!((e1 - e2), FLAG_A);     // set difference
    assert_eq!(!e2, FLAG_A);           // set complement
}

See example_generated::Flags for documentation of code generated by the above bitflags! expansion.

The generated structs can also be extended with type and trait implementations:

#[macro_use]
extern crate bitflags;

use std::fmt;

bitflags! {
    struct 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 struct Flags1: u32 {
            const FLAG_A   = 0b00000001;
        }
    }
    bitflags! {
        struct 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 Extend and FromIterator traits are implemented for the struct, too: Extend adds the union of the instances of the struct iterated over, while FromIterator calculates the union.

The Binary, Debug, LowerExp, Octal and UpperExp 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

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.

Default

The Default trait is not automatically implemented for the generated struct.

If your default value is equal to 0 (which is the same value as calling empty() on the generated struct), you can simply derive Default:

#[macro_use]
extern crate bitflags;

bitflags! {
    // Results in default value with bits: 0
    #[derive(Default)]
    struct Flags: u32 {
        const FLAG_A       = 0b00000001;
        const FLAG_B       = 0b00000010;
        const FLAG_C       = 0b00000100;
    }
}

fn main() {
    let derived_default: Flags = Default::default();
    assert_eq!(derived_default.bits(), 0);
}

If your default value is not equal to 0 you need to implement Default yourself:

#[macro_use]
extern crate bitflags;

bitflags! {
    struct Flags: u32 {
        const FLAG_A       = 0b00000001;
        const FLAG_B       = 0b00000010;
        const FLAG_C       = 0b00000100;
    }
}

// explicit `Default` implementation
impl Default for Flags {
    fn default() -> Flags {
        FLAG_A | FLAG_C
    }
}

fn main() {
    let implemented_default: Flags = Default::default();
    assert_eq!(implemented_default, (FLAG_A | FLAG_C));
}

Modules

example_generated

This module shows an example of code generated by the macro. IT MUST NOT BE USED OUTSIDE THIS CRATE.

Macros

bitflags

The macro used to generate the flag structure.