[−][src]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 A = 0b00000001; const B = 0b00000010; const C = 0b00000100; const ABC = Self::A.bits | Self::B.bits | Self::C.bits; } } fn main() { let e1 = Flags::A | Flags::C; let e2 = Flags::B | Flags::C; assert_eq!((e1 | e2), Flags::ABC); // union assert_eq!((e1 & e2), Flags::C); // intersection assert_eq!((e1 - e2), Flags::A); // set difference assert_eq!(!e2, Flags::A); // set complement }
See example_generated::Flags
for documentation of code
generated by the above bitflags!
expansion.
The generated struct
s can also be extended with type and trait
implementations:
#[macro_use] extern crate bitflags; use std::fmt; bitflags! { struct Flags: u32 { const A = 0b00000001; const 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 = Flags::A | Flags::B; flags.clear(); assert!(flags.is_empty()); assert_eq!(format!("{}", flags), "hi!"); assert_eq!(format!("{:?}", Flags::A | Flags::B), "A | B"); assert_eq!(format!("{:?}", Flags::B), "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 A = 0b00000001; } } bitflags! { struct Flags2: u32 { const B = 0b00000010; } } } fn main() { let flag1 = example::Flags1::A; let flag2 = example::Flags2::B; // error: const `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
, LowerHex
, Octal
and UpperHex
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
andBitOrAssign
: unionBitAnd
andBitAndAssign
: intersectionBitXor
andBitXorAssign
: toggleSub
andSubAssign
: set differenceNot
: set complement
Methods
The following methods are defined for the generated struct
:
empty
: an empty set of flagsall
: the set of all defined flagsbits
: the raw value of the flags currently storedfrom_bits
: convert from underlying bit representation, unless that representation contains bits that do not correspond to a defined flagfrom_bits_truncate
: convert from underlying bit representation, dropping any bits that do not correspond to defined flagsfrom_bits_unchecked
: convert from underlying bit representation, keeping all bits (even those not corresponding to defined flags)is_empty
:true
if no flags are currently storedis_all
:true
if currently set flags exactly equal all defined flagsintersects
: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-placeremove
: removes the specified flags in-placetoggle
: the specified flags will be inserted if not present, and removed if they are.set
: inserts or removes the specified flags depending on the passed value
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 A = 0b00000001; const B = 0b00000010; const 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 A = 0b00000001; const B = 0b00000010; const C = 0b00000100; } } // explicit `Default` implementation impl Default for Flags { fn default() -> Flags { Flags::A | Flags::C } } fn main() { let implemented_default: Flags = Default::default(); assert_eq!(implemented_default, (Flags::A | Flags::C)); }
Zero Flags
Flags with a value equal to zero will have some strange behavior that one should be aware of.
#[macro_use] extern crate bitflags; bitflags! { struct Flags: u32 { const NONE = 0b00000000; const SOME = 0b00000001; } } fn main() { let empty = Flags::empty(); let none = Flags::NONE; let some = Flags::SOME; // Zero flags are treated as always present assert!(empty.contains(Flags::NONE)); assert!(none.contains(Flags::NONE)); assert!(some.contains(Flags::NONE)); // Zero flags will be ignored when testing for emptiness assert!(none.is_empty()); }
Macros
bitflags | The macro used to generate the flag structure. |