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

Thebitflags! macro generates astruct that manages a set of flags. Theflags should only be defined for integer types, otherwise unexpected typeerrors may occur at compile time.

Example

#[macro_use]externcratebitflags;bitflags! {structFlags:u32 {constFLAG_A=0b00000001;constFLAG_B=0b00000010;constFLAG_C=0b00000100;constFLAG_ABC=FLAG_A.bits|FLAG_B.bits|FLAG_C.bits;    }}fnmain() {lete1=FLAG_A|FLAG_C;lete2=FLAG_B|FLAG_C;assert_eq!((e1|e2),FLAG_ABC);// unionassert_eq!((e1&e2),FLAG_C);// intersectionassert_eq!((e1-e2),FLAG_A);// set differenceassert_eq!(!e2,FLAG_A);// set complement}

Seeexample_generated::Flags for documentation of codegenerated by the abovebitflags! expansion.

The generatedstructs can also be extended with type and traitimplementations:

#[macro_use]externcratebitflags;usestd::fmt;bitflags! {structFlags:u32 {constFLAG_A=0b00000001;constFLAG_B=0b00000010;    }}implFlags {pubfnclear(&mutself) {self.bits=0;// The `bits` field can be accessed from within the// same module where the `bitflags!` macro was invoked.    }}implfmt::DisplayforFlags {fnfmt(&self,f:&mutfmt::Formatter)->fmt::Result {write!(f,"hi!")    }}fnmain() {letmutflags=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 exportedout of the current module by default. A definition can be exported out ofthe current module by addingpub beforeflags:

#[macro_use]externcratebitflags;modexample {bitflags! {pubstructFlags1:u32 {constFLAG_A=0b00000001;        }    }bitflags! {structFlags2:u32 {constFLAG_B=0b00000010;        }    }}fnmain() {letflag1=example::FLAG_A;letflag2=example::FLAG_B;// error: const `FLAG_B` is private}

Attributes

Attributes can be attached to the generatedstruct by placing thembefore theflags keyword.

Trait implementations

TheCopy,Clone,PartialEq,Eq,PartialOrd,Ord andHashtraits automatically derived for thestruct using thederive attribute.Additional traits can be derived by providing an explicitderiveattribute onflags.

TheExtend andFromIterator traits are implemented for thestruct,too:Extend adds the union of the instances of thestruct iterated over,whileFromIterator calculates the union.

TheBinary,Debug,LowerExp,Octal andUpperExp trait is alsoimplemented by displaying the bits value of the internal struct.

Operators

The following operator traits are implemented for the generatedstruct:

• BitOr andBitOrAssign: union
• BitAnd andBitAndAssign: intersection
• BitXor andBitXorAssign: toggle
• Sub andSubAssign: set difference
• Not: set complement

Methods

The following methods are defined for the generatedstruct:

• 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 bothself andother
• contains:true all of the flags inother are contained withinself
• 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

TheDefault trait is not automatically implemented for the generated struct.

If your default value is equal to0 (which is the same value as callingempty()on the generated struct), you can simply deriveDefault:

#[macro_use]externcratebitflags;bitflags! {// Results in default value with bits: 0#[derive(Default)]structFlags:u32 {constFLAG_A=0b00000001;constFLAG_B=0b00000010;constFLAG_C=0b00000100;    }}fnmain() {letderived_default:Flags=Default::default();assert_eq!(derived_default.bits(),0);}

If your default value is not equal to0 you need to implementDefault yourself:

#[macro_use]externcratebitflags;bitflags! {structFlags:u32 {constFLAG_A=0b00000001;constFLAG_B=0b00000010;constFLAG_C=0b00000100;    }}// explicit `Default` implementationimplDefaultforFlags {fndefault()->Flags {FLAG_A|FLAG_C    }}fnmain() {letimplemented_default:Flags=Default::default();assert_eq!(implemented_default, (FLAG_A|FLAG_C));}