Struct enumflags2::BitFlags

source ·
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.

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§

source§

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

source

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.

source

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.

source

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.

source

pub fn from_flag(flag: T) -> Self

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

source

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

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

pub const EMPTY: Self = _

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

source

pub const ALL: Self = _

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

source

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

A ConstToken for this type of flag.

source

pub fn is_all(self) -> bool

Returns true if all flags are set

source

pub fn is_empty(self) -> bool

Returns true if no flag is set

source

pub fn len(self) -> usize

Returns the number of flags set.

source

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.

source

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

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

Returns true if at least one flag is shared.

source

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

Returns true if all flags are contained.

source

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

Toggles the matching bits

source

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

Inserts the flags into the BitFlag

source

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

Removes the matching flags

source

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

Returns an iterator that yields each set flag

source§

impl<T> BitFlags<T, u8>

source

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.

source

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

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.

source

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.

source

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

pub const fn bits_c(self) -> u8

Returns the underlying bitwise value.

const variant of bits.

Trait Implementations§

source§

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

source§

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

Formats the value using the given formatter.
source§

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.
source§

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

Performs the & operation. Read more
source§

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

source§

fn bitand_assign(&mut self, other: B)

Performs the &= operation. Read more
source§

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.
source§

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

Performs the | operation. Read more
source§

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

source§

fn bitor_assign(&mut self, other: B)

Performs the |= operation. Read more
source§

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.
source§

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

Performs the ^ operation. Read more
source§

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

source§

fn bitxor_assign(&mut self, other: B)

Performs the ^= operation. Read more
source§

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

source§

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

Returns a copy of the value. Read more
1.0.0 · source§

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

Performs copy-assignment from source. Read more
source§

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

source§

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

Formats the value using the given formatter. Read more
source§

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

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

source§

fn default() -> Self

Returns the “default value” for a type. Read more
source§

impl<'a, T> Deserialize<'a> for BitFlags<T>where T: BitFlag, T::Numeric: Deserialize<'a> + Into<u64>,

source§

fn deserialize<D: Deserializer<'a>>(d: D) -> Result<Self, D::Error>

Deserialize this value from the given Serde deserializer. Read more
source§

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

source§

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

Formats the value using the given formatter. Read more
source§

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

source§

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

Extends a collection with the contents of an iterator. Read more
source§

fn extend_one(&mut self, item: A)

🔬This is a nightly-only experimental API. (extend_one)
Extends a collection with exactly one element.
source§

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. Read more
source§

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

source§

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

Converts to this type from the input type.
source§

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

source§

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

Creates a value from an iterator. Read more
source§

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

source§

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

Feeds this value into the given Hasher. Read more
1.3.0 · source§

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

Feeds a slice of this type into the given Hasher. Read more
source§

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.
source§

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value. Read more
source§

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

source§

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

Formats the value using the given formatter.
source§

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

§

type Output = BitFlags<T>

The resulting type after applying the ! operator.
source§

fn not(self) -> BitFlags<T>

Performs the unary ! operation. Read more
source§

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

source§

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

Formats the value using the given formatter.
source§

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

source§

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

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

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

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.
source§

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

source§

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

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

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

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.
source§

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

source§

fn serialize<S: Serializer>(&self, s: S) -> Result<S::Ok, S::Error>

Serialize this value into the given Serde serializer. Read more
source§

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.
source§

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

Performs the conversion.
source§

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.
source§

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

Performs the conversion.
source§

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.
source§

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

Performs the conversion.
source§

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.
source§

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

Performs the conversion.
source§

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.
source§

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

Performs the conversion.
source§

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

source§

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

Formats the value using the given formatter.
source§

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

source§

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

source§

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

Auto Trait Implementations§

§

impl<T, N> RefUnwindSafe for BitFlags<T, N>where N: RefUnwindSafe, T: RefUnwindSafe,

§

impl<T, N> Send for BitFlags<T, N>where N: Send, T: Send,

§

impl<T, N> Sync for BitFlags<T, N>where N: Sync, T: Sync,

§

impl<T, N> Unpin for BitFlags<T, N>where N: Unpin, T: Unpin,

§

impl<T, N> UnwindSafe for BitFlags<T, N>where N: UnwindSafe, T: UnwindSafe,

Blanket Implementations§

source§

impl<T> Any for Twhere T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
source§

impl<T> Borrow<T> for Twhere T: ?Sized,

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for Twhere T: ?Sized,

source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

source§

impl<T, U> Into<U> for Twhere U: From<T>,

source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

source§

impl<T> ToOwned for Twhere T: Clone,

§

type Owned = T

The resulting type after obtaining ownership.
source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
source§

impl<T> ToString for Twhere T: Display + ?Sized,

source§

default fn to_string(&self) -> String

Converts the given value to a String. Read more
source§

impl<T, U> TryFrom<U> for Twhere U: Into<T>,

§

type Error = Infallible

The type returned in the event of a conversion error.
source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
source§

impl<T, U> TryInto<U> for Twhere U: TryFrom<T>,

§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
source§

impl<T> DeserializeOwned for Twhere T: for<'de> Deserialize<'de>,