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 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>,
}
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
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 fn
s 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 fn
s 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 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);
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