Struct BitFlags
pub struct BitFlags<T, N = <T as RawBitFlags>::Numeric> { /* private fields */ }
Expand description
Represents a set of flags of some type T
.
T
must have the #[bitflags]
attribute applied.
A BitFlags<T>
is as large as the T
itself,
and stores one flag per bit.
§Comparison operators, PartialOrd
and Ord
To make it possible to use BitFlags
as the key of a
[BTreeMap
][std::collections::BTreeMap], BitFlags
implements
Ord
. There is no meaningful total order for bitflags,
so the implementation simply compares the integer values of the bits.
Unfortunately, this means that comparing BitFlags
with an operator
like <=
will compile, and return values that are probably useless
and not what you expect. In particular, <=
does not check whether
one value is a subset of the other. Use BitFlags::contains
for that.
§Customizing Default
By default, creating an instance of BitFlags<T>
with Default
will result
in an empty set. If that’s undesirable, you may customize this:
#[bitflags(default = B | C)]
#[repr(u8)]
#[derive(Copy, Clone, Debug, PartialEq)]
enum MyFlag {
A = 0b0001,
B = 0b0010,
C = 0b0100,
D = 0b1000,
}
assert_eq!(BitFlags::default(), MyFlag::B | MyFlag::C);
§Memory layout
BitFlags<T>
is marked with the #[repr(transparent)]
trait, meaning
it can be safely transmuted into the corresponding numeric type.
Usually, the same can be achieved by using BitFlags::bits
in one
direction, and BitFlags::from_bits
, BitFlags::from_bits_truncate
,
or BitFlags::from_bits_unchecked
in the other direction. However,
transmuting might still be useful if, for example, you’re dealing with
an entire array of BitFlags
.
When transmuting into a BitFlags
, make sure that each set bit
corresponds to an existing flag
(cf. from_bits_unchecked
).
For example:
#[bitflags]
#[repr(u8)] // <-- the repr determines the numeric type
#[derive(Copy, Clone)]
enum TransmuteMe {
One = 1 << 0,
Two = 1 << 1,
}
// NOTE: we use a small, self-contained function to handle the slice
// conversion to make sure the lifetimes are right.
fn transmute_slice<'a>(input: &'a [BitFlags<TransmuteMe>]) -> &'a [u8] {
unsafe {
slice::from_raw_parts(input.as_ptr() as *const u8, input.len())
}
}
let many_flags = &[
TransmuteMe::One.into(),
TransmuteMe::One | TransmuteMe::Two,
];
let as_nums = transmute_slice(many_flags);
assert_eq!(as_nums, &[0b01, 0b11]);
§Implementation notes
You might expect this struct to be defined as
struct BitFlags<T: BitFlag> {
value: T::Numeric
}
Ideally, that would be the case. However, because const fn
s cannot
have trait bounds in current Rust, this would prevent us from providing
most const fn
APIs. As a workaround, we define BitFlags
with two
type parameters, with a default for the second one:
struct BitFlags<T, N = <T as BitFlag>::Numeric> {
value: N,
marker: PhantomData<T>,
}
Manually providing a type for the N
type parameter shouldn’t ever
be necessary.
The types substituted for T
and N
must always match, creating a
BitFlags
value where that isn’t the case is only possible with
incorrect unsafe code.
Implementations§
§impl<T> BitFlags<T>where
T: BitFlag,
impl<T> BitFlags<T>where
T: BitFlag,
pub fn iter(self) -> Iter<T>
pub fn iter(self) -> Iter<T>
Iterate over the BitFlags
.
let flags = make_bitflags!(MyFlag::{A | C});
flags.iter()
.for_each(|flag| println!("{:?}", flag));
§impl<T> BitFlags<T>where
T: BitFlag,
impl<T> BitFlags<T>where
T: BitFlag,
pub const EMPTY: BitFlags<T> = _
pub const EMPTY: BitFlags<T> = _
An empty BitFlags
. Equivalent to empty()
,
but works in a const context.
pub const ALL: BitFlags<T> = _
pub const ALL: BitFlags<T> = _
A BitFlags
with all flags set. Equivalent to all()
,
but works in a const context.
pub const CONST_TOKEN: ConstToken<T, <T as RawBitFlags>::Numeric> = _
pub const CONST_TOKEN: ConstToken<T, <T as RawBitFlags>::Numeric> = _
A [ConstToken
] for this type of flag.
§impl<T> BitFlags<T, u8>
impl<T> BitFlags<T, u8>
pub const unsafe fn from_bits_unchecked_c(
val: u8,
const_token: ConstToken<T, u8>,
) -> BitFlags<T, u8>
pub const unsafe fn from_bits_unchecked_c( val: u8, const_token: ConstToken<T, u8>, ) -> BitFlags<T, u8>
Create a new BitFlags unsafely, without checking if the bits form a valid bit pattern for the type.
Const variant of
from_bits_unchecked
.
Consider using
from_bits_truncate_c
instead.
§Safety
All bits set in val
must correspond to a value of the enum.
pub const fn from_bits_truncate_c(
bits: u8,
const_token: ConstToken<T, u8>,
) -> BitFlags<T, u8>
pub const fn from_bits_truncate_c( bits: u8, const_token: ConstToken<T, u8>, ) -> BitFlags<T, u8>
Create a BitFlags<T>
from an underlying bitwise value. If any
invalid bits are set, ignore them.
#[bitflags]
#[repr(u8)]
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
enum MyFlag {
One = 1 << 0,
Two = 1 << 1,
Three = 1 << 2,
}
const FLAGS: BitFlags<MyFlag> =
BitFlags::<MyFlag>::from_bits_truncate_c(0b10101010, BitFlags::CONST_TOKEN);
assert_eq!(FLAGS, MyFlag::Two);
pub const fn union_c(self, other: BitFlags<T, u8>) -> BitFlags<T, u8>
pub const fn union_c(self, other: BitFlags<T, u8>) -> BitFlags<T, u8>
Bitwise OR — return value contains flag if either argument does.
Also available as a | b
, but operator overloads are not usable
in const fn
s at the moment.
pub const fn intersection_c(self, other: BitFlags<T, u8>) -> BitFlags<T, u8>
pub const fn intersection_c(self, other: BitFlags<T, u8>) -> BitFlags<T, u8>
Bitwise AND — return value contains flag if both arguments do.
Also available as a & b
, but operator overloads are not usable
in const fn
s at the moment.
pub const fn not_c(self, const_token: ConstToken<T, u8>) -> BitFlags<T, u8>
pub const fn not_c(self, const_token: ConstToken<T, u8>) -> BitFlags<T, u8>
Bitwise NOT — return value contains flag if argument doesn’t.
Also available as !a
, but operator overloads are not usable
in const fn
s at the moment.
Moreover, due to const fn
limitations, not_c
needs a
[ConstToken
] as an argument.
#[bitflags]
#[repr(u8)]
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
enum MyFlag {
One = 1 << 0,
Two = 1 << 1,
Three = 1 << 2,
}
const FLAGS: BitFlags<MyFlag> = make_bitflags!(MyFlag::{One | Two});
const NEGATED: BitFlags<MyFlag> = FLAGS.not_c(BitFlags::CONST_TOKEN);
assert_eq!(NEGATED, MyFlag::Three);
§impl<T> BitFlags<T>where
T: BitFlag,
impl<T> BitFlags<T>where
T: BitFlag,
pub fn from_bits(
bits: <T as RawBitFlags>::Numeric,
) -> Result<BitFlags<T>, FromBitsError<T>>
pub fn from_bits( bits: <T as RawBitFlags>::Numeric, ) -> Result<BitFlags<T>, FromBitsError<T>>
Create a BitFlags
if the raw value provided does not contain
any illegal flags.
See also: [a convenience re-export in the BitFlag
trait][BitFlag::from_bits],
which can help avoid the need for type hints.
#[bitflags]
#[repr(u8)]
#[derive(Clone, Copy, PartialEq, Eq, Debug)]
enum MyFlag {
One = 1 << 0,
Two = 1 << 1,
Three = 1 << 2,
}
let flags: BitFlags<MyFlag> = BitFlags::from_bits(0b11).unwrap();
assert_eq!(flags.contains(MyFlag::One), true);
assert_eq!(flags.contains(MyFlag::Two), true);
assert_eq!(flags.contains(MyFlag::Three), false);
let invalid = BitFlags::<MyFlag>::from_bits(1 << 3);
assert!(invalid.is_err());
pub fn from_bits_truncate(bits: <T as RawBitFlags>::Numeric) -> BitFlags<T>
pub fn from_bits_truncate(bits: <T as RawBitFlags>::Numeric) -> BitFlags<T>
Create a BitFlags
from an underlying bitwise value. If any
invalid bits are set, ignore them.
See also: [a convenience re-export in the BitFlag
trait][BitFlag::from_bits_truncate],
which can help avoid the need for type hints.
#[bitflags]
#[repr(u8)]
#[derive(Clone, Copy, PartialEq, Eq)]
enum MyFlag {
One = 1 << 0,
Two = 1 << 1,
Three = 1 << 2,
}
let flags: BitFlags<MyFlag> = BitFlags::from_bits_truncate(0b1_1011);
assert_eq!(flags.contains(MyFlag::One), true);
assert_eq!(flags.contains(MyFlag::Two), true);
assert_eq!(flags.contains(MyFlag::Three), false);
pub unsafe fn from_bits_unchecked(
val: <T as RawBitFlags>::Numeric,
) -> BitFlags<T>
pub unsafe fn from_bits_unchecked( val: <T as RawBitFlags>::Numeric, ) -> BitFlags<T>
Create a new BitFlags unsafely, without checking if the bits form a valid bit pattern for the type.
Consider using from_bits
or from_bits_truncate
instead.
§Safety
All bits set in val
must correspond to a value of the enum.
§Example
#[bitflags]
#[repr(u8)]
#[derive(Clone, Copy, PartialEq, Eq)]
enum MyFlag {
One = 1 << 0,
Two = 1 << 1,
Three = 1 << 2,
}
let flags: BitFlags<MyFlag> = unsafe {
BitFlags::from_bits_unchecked(0b011)
};
assert_eq!(flags.contains(MyFlag::One), true);
assert_eq!(flags.contains(MyFlag::Two), true);
assert_eq!(flags.contains(MyFlag::Three), false);
pub fn empty() -> BitFlags<T>
pub fn empty() -> BitFlags<T>
Create a BitFlags
with no flags set (in other words, with a value of 0
).
See also: [BitFlag::empty
], a convenience reexport;
BitFlags::EMPTY
, the same functionality available
as a constant for const fn
code.
#[bitflags]
#[repr(u8)]
#[derive(Clone, Copy, PartialEq, Eq)]
enum MyFlag {
One = 1 << 0,
Two = 1 << 1,
Three = 1 << 2,
}
let empty: BitFlags<MyFlag> = BitFlags::empty();
assert!(empty.is_empty());
assert_eq!(empty.contains(MyFlag::One), false);
assert_eq!(empty.contains(MyFlag::Two), false);
assert_eq!(empty.contains(MyFlag::Three), false);
pub fn all() -> BitFlags<T>
pub fn all() -> BitFlags<T>
Create a BitFlags
with all flags set.
See also: [BitFlag::all
], a convenience reexport;
BitFlags::ALL
, the same functionality available
as a constant for const fn
code.
#[bitflags]
#[repr(u8)]
#[derive(Clone, Copy, PartialEq, Eq)]
enum MyFlag {
One = 1 << 0,
Two = 1 << 1,
Three = 1 << 2,
}
let empty: BitFlags<MyFlag> = BitFlags::all();
assert!(empty.is_all());
assert_eq!(empty.contains(MyFlag::One), true);
assert_eq!(empty.contains(MyFlag::Two), true);
assert_eq!(empty.contains(MyFlag::Three), true);
pub fn exactly_one(self) -> Option<T>
pub fn exactly_one(self) -> Option<T>
If exactly one flag is set, the flag is returned. Otherwise, returns None
.
See also Itertools::exactly_one
.
pub fn bits(self) -> <T as RawBitFlags>::Numeric
pub fn bits(self) -> <T as RawBitFlags>::Numeric
Returns the underlying bitwise value.
#[bitflags]
#[repr(u8)]
#[derive(Clone, Copy)]
enum Flags {
Foo = 1 << 0,
Bar = 1 << 1,
}
let both_flags = Flags::Foo | Flags::Bar;
assert_eq!(both_flags.bits(), 0b11);
pub fn intersects<B>(self, other: B) -> bool
pub fn intersects<B>(self, other: B) -> bool
Returns true if at least one flag is shared.
pub fn set<B>(&mut self, other: B, cond: bool)
pub fn set<B>(&mut self, other: B, cond: bool)
Inserts if cond
holds, else removes
#[bitflags]
#[derive(Clone, Copy, PartialEq, Debug)]
#[repr(u8)]
enum MyFlag {
A = 1 << 0,
B = 1 << 1,
C = 1 << 2,
}
let mut state = MyFlag::A | MyFlag::C;
state.set(MyFlag::A | MyFlag::B, false);
// Because the condition was false, both
// `A` and `B` are removed from the set
assert_eq!(state, MyFlag::C);
Trait Implementations§
§impl<T, B> BitAndAssign<B> for BitFlags<T>
impl<T, B> BitAndAssign<B> for BitFlags<T>
§fn bitand_assign(&mut self, other: B)
fn bitand_assign(&mut self, other: B)
&=
operation. Read more§impl<T, B> BitOrAssign<B> for BitFlags<T>
impl<T, B> BitOrAssign<B> for BitFlags<T>
§fn bitor_assign(&mut self, other: B)
fn bitor_assign(&mut self, other: B)
|=
operation. Read more§impl<T, B> BitXorAssign<B> for BitFlags<T>
impl<T, B> BitXorAssign<B> for BitFlags<T>
§fn bitxor_assign(&mut self, other: B)
fn bitxor_assign(&mut self, other: B)
^=
operation. Read more§impl<T> Default for BitFlags<T>where
T: BitFlag,
impl<T> Default for BitFlags<T>where
T: BitFlag,
The default value returned is one with all flags unset, i. e. empty
,
unless customized.
§impl<T, B> Extend<B> for BitFlags<T>
impl<T, B> Extend<B> for BitFlags<T>
§fn extend<I>(&mut self, it: I)where
I: IntoIterator<Item = B>,
fn extend<I>(&mut self, it: I)where
I: IntoIterator<Item = B>,
source§fn extend_one(&mut self, item: A)
fn extend_one(&mut self, item: A)
extend_one
)source§fn extend_reserve(&mut self, additional: usize)
fn extend_reserve(&mut self, additional: usize)
extend_one
)§impl<T, B> FromIterator<B> for BitFlags<T>
impl<T, B> FromIterator<B> for BitFlags<T>
§fn from_iter<I>(it: I) -> BitFlags<T>where
I: IntoIterator<Item = B>,
fn from_iter<I>(it: I) -> BitFlags<T>where
I: IntoIterator<Item = B>,
§impl<T> IntoIterator for BitFlags<T>where
T: BitFlag,
impl<T> IntoIterator for BitFlags<T>where
T: BitFlag,
§impl<T, N> Ord for BitFlags<T, N>where
N: Ord,
impl<T, N> Ord for BitFlags<T, N>where
N: Ord,
§impl<T, N> PartialOrd for BitFlags<T, N>where
N: PartialOrd,
impl<T, N> PartialOrd for BitFlags<T, N>where
N: PartialOrd,
impl<T, N> Copy for BitFlags<T, N>
impl<T, N> Eq for BitFlags<T, N>where
N: Eq,
Auto Trait Implementations§
impl<T, N> Freeze for BitFlags<T, N>where
N: Freeze,
impl<T, N> RefUnwindSafe for BitFlags<T, N>where
N: RefUnwindSafe,
T: RefUnwindSafe,
impl<T, N> Send for BitFlags<T, N>
impl<T, N> Sync for BitFlags<T, N>
impl<T, N> Unpin for BitFlags<T, N>
impl<T, N> UnwindSafe for BitFlags<T, N>where
N: UnwindSafe,
T: UnwindSafe,
Blanket Implementations§
source§impl<T> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere
T: ?Sized,
source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
source§impl<T> CloneToUninit for Twhere
T: Clone,
impl<T> CloneToUninit for Twhere
T: Clone,
source§unsafe fn clone_to_uninit(&self, dst: *mut T)
unsafe fn clone_to_uninit(&self, dst: *mut T)
clone_to_uninit
)