Struct enumflags2::BitFlags

#[repr(transparent)]
pub struct BitFlags<T, N = <T as RawBitFlags>::Numeric> { /* private fields */ }

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 only possible with incorrect unsafe code.

Implementations

impl<T> BitFlags<T> where
    T: BitFlag, 

pub fn from_bits(bits: T::Numeric) -> Result<Self, FromBitsError<T>>

Returns a BitFlags<T> if the raw value provided does not contain any illegal flags.

pub fn from_bits_truncate(bits: T::Numeric) -> Self

Create a BitFlags<T> from an underlying bitwise value. If any invalid bits are set, ignore them.

pub unsafe fn from_bits_unchecked(val: T::Numeric) -> Self

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.

pub fn from_flag(flag: T) -> Self

Turn a T into a BitFlags<T>. Also available as flag.into().

pub fn empty() -> Self

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() -> Self

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 const EMPTY: Self

An empty BitFlags. Equivalent to empty(), but works in a const context.

pub const ALL: Self

A BitFlags with all flags set. Equivalent to all(), but works in a const context.

pub const CONST_TOKEN: ConstToken<T, T::Numeric>

A ConstToken for this type of flag.

pub fn is_all(self) -> bool

Returns true if all flags are set

pub fn is_empty(self) -> bool

Returns true if no flag is set

pub fn len(self) -> usize

Returns the number of flags set.

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::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: Into<BitFlags<T>>>(self, other: B) -> bool

Returns true if at least one flag is shared.

pub fn contains<B: Into<BitFlags<T>>>(self, other: B) -> bool

Returns true if all flags are contained.

pub fn toggle<B: Into<BitFlags<T>>>(&mut self, other: B)

Toggles the matching bits

pub fn insert<B: Into<BitFlags<T>>>(&mut self, other: B)

Inserts the flags into the BitFlag

pub fn remove<B: Into<BitFlags<T>>>(&mut self, other: B)

Removes the matching flags

pub fn iter(self) -> Iter<T>

Returns an iterator that yields each set flag

impl<T> BitFlags<T, u8>

pub const unsafe fn from_bits_unchecked_c(
    val: u8,
    const_token: ConstToken<T, u8>
) -> Self

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>
) -> Self

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: Self) -> Self

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.

pub const fn intersection_c(self, other: Self) -> Self

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.

pub const fn not_c(self, const_token: ConstToken<T, u8>) -> Self

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);

pub const fn bits_c(self) -> u8

Returns the underlying bitwise value.

const variant of bits.

Trait Implementations

impl<T> Binary for BitFlags<T> where
    T: BitFlag,
    T::Numeric: Binary, 

fn fmt(&self, fmt: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<T, B> BitAnd<B> for BitFlags<T> where
    T: BitFlag,
    B: Into<BitFlags<T>>, 

type Output = BitFlags<T>

The resulting type after applying the & operator.

fn bitand(self, other: B) -> BitFlags<T>

Performs the & operation.

impl<T, B> BitAndAssign<B> for BitFlags<T> where
    T: BitFlag,
    B: Into<BitFlags<T>>, 

fn bitand_assign(&mut self, other: B)

Performs the &= operation.

impl<T, B> BitOr<B> for BitFlags<T> where
    T: BitFlag,
    B: Into<BitFlags<T>>, 

type Output = BitFlags<T>

The resulting type after applying the | operator.

fn bitor(self, other: B) -> BitFlags<T>

Performs the | operation.

impl<T, B> BitOrAssign<B> for BitFlags<T> where
    T: BitFlag,
    B: Into<BitFlags<T>>, 

fn bitor_assign(&mut self, other: B)

Performs the |= operation.

impl<T, B> BitXor<B> for BitFlags<T> where
    T: BitFlag,
    B: Into<BitFlags<T>>, 

type Output = BitFlags<T>

The resulting type after applying the ^ operator.

fn bitxor(self, other: B) -> BitFlags<T>

Performs the ^ operation.

impl<T, B> BitXorAssign<B> for BitFlags<T> where
    T: BitFlag,
    B: Into<BitFlags<T>>, 

fn bitxor_assign(&mut self, other: B)

Performs the ^= operation.

impl<T: Clone, N: Clone> Clone for BitFlags<T, N>

fn clone(&self) -> BitFlags<T, N>

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<T> Debug for BitFlags<T> where
    T: BitFlag + Debug, 

fn fmt(&self, fmt: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<T> Default for BitFlags<T> where
    T: BitFlag, 

The default value returned is one with all flags unset, i. e. empty, unless customized.

fn default() -> Self

Returns the “default value” for a type.

impl<T> Display for BitFlags<T> where
    T: BitFlag + Debug, 

fn fmt(&self, fmt: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<T, B> Extend<B> for BitFlags<T> where
    T: BitFlag,
    B: Into<BitFlags<T>>, 

fn extend<I>(&mut self, it: I) where
    I: IntoIterator<Item = B>, 

Extends a collection with the contents of an iterator.

fn extend_one(&mut self, item: A)

🔬 This is a nightly-only experimental API. (extend_one)

Extends a collection with exactly one element.

fn extend_reserve(&mut self, additional: usize)

🔬 This is a nightly-only experimental API. (extend_one)

Reserves capacity in a collection for the given number of additional elements.

impl<T: BitFlag> From<T> for BitFlags<T>

fn from(t: T) -> BitFlags<T>

Converts to this type from the input type.

impl<T, B> FromIterator<B> for BitFlags<T> where
    T: BitFlag,
    B: Into<BitFlags<T>>, 

fn from_iter<I>(it: I) -> BitFlags<T> where
    I: IntoIterator<Item = B>, 

Creates a value from an iterator.

impl<T, N: Hash> Hash for BitFlags<T, N>

fn hash<H: Hasher>(&self, state: &mut H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H) where
    H: Hasher, 

Feeds a slice of this type into the given Hasher.

impl<T: BitFlag> IntoIterator for BitFlags<T>

type IntoIter = Iter<T>

Which kind of iterator are we turning this into?

type Item = T

The type of the elements being iterated over.

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl<T> LowerHex for BitFlags<T> where
    T: BitFlag,
    T::Numeric: LowerHex, 

fn fmt(&self, fmt: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<T> Not for BitFlags<T> where
    T: BitFlag, 

type Output = BitFlags<T>

The resulting type after applying the ! operator.

fn not(self) -> BitFlags<T>

Performs the unary ! operation.

impl<T> Octal for BitFlags<T> where
    T: BitFlag,
    T::Numeric: Octal, 

fn fmt(&self, fmt: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<T, N: PartialEq> PartialEq<BitFlags<T, N>> for BitFlags<T, N>

fn eq(&self, other: &Self) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl<T> PartialEq<T> for BitFlags<T> where
    T: BitFlag, 

fn eq(&self, other: &T) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl<T> TryFrom<u128> for BitFlags<T> where
    T: BitFlag<Numeric = u128>, 

type Error = FromBitsError<T>

The type returned in the event of a conversion error.

fn try_from(bits: T::Numeric) -> Result<Self, Self::Error>

Performs the conversion.

impl<T> TryFrom<u16> for BitFlags<T> where
    T: BitFlag<Numeric = u16>, 

type Error = FromBitsError<T>

The type returned in the event of a conversion error.

fn try_from(bits: T::Numeric) -> Result<Self, Self::Error>

Performs the conversion.

impl<T> TryFrom<u32> for BitFlags<T> where
    T: BitFlag<Numeric = u32>, 

type Error = FromBitsError<T>

The type returned in the event of a conversion error.

fn try_from(bits: T::Numeric) -> Result<Self, Self::Error>

Performs the conversion.

impl<T> TryFrom<u64> for BitFlags<T> where
    T: BitFlag<Numeric = u64>, 

type Error = FromBitsError<T>

The type returned in the event of a conversion error.

fn try_from(bits: T::Numeric) -> Result<Self, Self::Error>

Performs the conversion.

impl<T> TryFrom<u8> for BitFlags<T> where
    T: BitFlag<Numeric = u8>, 

type Error = FromBitsError<T>

The type returned in the event of a conversion error.

fn try_from(bits: T::Numeric) -> Result<Self, Self::Error>

Performs the conversion.

impl<T> UpperHex for BitFlags<T> where
    T: BitFlag,
    T::Numeric: UpperHex, 

fn fmt(&self, fmt: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<T: Copy, N: Copy> Copy for BitFlags<T, N>

impl<T: Eq, N: Eq> Eq for BitFlags<T, N>

impl<T, N> StructuralEq for BitFlags<T, N>