Struct enumflags2::BitFlags [−][src]
#[repr(transparent)]pub struct BitFlags<T, N = <T as RawBitFlags>::Numeric> { /* fields omitted */ }
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.
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::from_bits,
BitFlags::from_bits_truncate or BitFlags::from_bits_unchecked,
but transmuting might still be useful if, for example, you’re dealing with
an entire array of BitFlags.
Transmuting from a numeric type into BitFlags may also be done, but
care must be taken to make sure that each set bit in the value 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 fns 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>, }
The types substituted for T and N must always match, creating a
BitFlags value where that isn’t the case is considered to be impossible
without unsafe code.
Implementations
Returns a BitFlags<T> if the raw value provided does not contain
any illegal flags.
Create a BitFlags<T> from an underlying bitwise value. If any
invalid bits are set, ignore them.
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
The argument must not have set bits at positions not corresponding to any flag.
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);
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);
A BitFlags with all flags set. Equivalent to all(),
but works in a const context.
A ConstToken for this type of flag.
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);
Returns true if at least one flag is shared.
Returns true if all flags are contained.
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
The argument must not have set bits at positions not corresponding to any flag.
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);
Bitwise OR — return value contains flag if either argument does.
Also available as a | b, but operator overloads are not usable
in const fns at the moment.
Bitwise AND — return value contains flag if both arguments do.
Also available as a & b, but operator overloads are not usable
in const fns at the moment.
Bitwise NOT — return value contains flag if argument doesn’t.
Also available as !a, but operator overloads are not usable
in const fns 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);
Trait Implementations
Performs the &= operation. Read more
Performs the |= operation. Read more
Performs the ^= operation. Read more
The default value returned is one with all flags unset, i. e. empty,
unless customized.
Extends a collection with the contents of an iterator. Read more
extend_one)Extends a collection with exactly one element.
extend_one)Reserves capacity in a collection for the given number of additional elements. Read more
Creates a value from an iterator. Read more