Struct enumset::EnumSet

#[repr(transparent)]
pub struct EnumSet<T: EnumSetType> { /* private fields */ }

An efficient set type for enums.

It is implemented using a bitset stored using the smallest integer that can fit all bits in the underlying enum. In general, an enum variant with a discriminator of n is stored in the nth least significant bit (corresponding with a mask of, e.g. 1 << enum as u32).

Numeric representation

EnumSet is internally implemented using integer types, and as such can be easily converted from and to numbers.

Each bit of the underlying integer corresponds to at most one particular enum variant. If the corresponding bit for a variant is set, it present in the set. Bits that do not correspond to any variant are always unset.

By default, each enum variant is stored in a bit corresponding to its discriminator. An enum variant with a discriminator of n is stored in the n + 1th least significant bit (corresponding to a mask of e.g. 1 << enum as u32).

Serialization

When the serde feature is enabled, EnumSets can be serialized and deserialized using the serde crate. The exact serialization format can be controlled with additional attributes on the enum type. These attributes are valid regardless of whether the serde feature is enabled.

By default, EnumSets serialize by directly writing out the underlying bitset as an integer of the smallest type that can fit in the underlying enum. You can add a #[enumset(serialize_repr = "u8")] attribute to your enum to control the integer type used for serialization. This can be important for avoiding unintentional breaking changes when EnumSets are serialized with formats like bincode.

By default, unknown bits are ignored and silently removed from the bitset. To override thris behavior, you can add a #[enumset(serialize_deny_unknown)] attribute. This will cause deserialization to fail if an invalid bit is set.

In addition, the #[enumset(serialize_as_list)] attribute causes the EnumSet to be instead serialized as a list of enum variants. This requires your enum type implement [Serialize] and [Deserialize]. Note that this is a breaking change.

FFI, Safety and repr

If an enum type T is annotated with #[enumset(repr = "R")], then several things happen:

• T will implement EnumSetTypeWithRepr<Repr = R> in addition to EnumSetType.
• The EnumSet methods with repr in their name, such as as_repr and from_repr, will be available for EnumSet<T>.
• The in-memory representation of EnumSet<T> is guaranteed to be R.

That last guarantee makes it sound to send EnumSet<T> across an FFI boundary. For example:

extern "C" {
    // This function is written in C like:
    // uint32_t some_foreign_function(uint32_t set) { … }
    fn some_foreign_function(set: EnumSet<MyEnum>) -> EnumSet<MyEnum>;
}

#[derive(Debug, EnumSetType)]
#[enumset(repr = "u32")]
enum MyEnum { A, B, C }

let set: EnumSet<MyEnum> = enum_set!(MyEnum::A | MyEnum::C);

let new_set: EnumSet<MyEnum> = unsafe { some_foreign_function(set) };
assert_eq!(new_set, enum_set!(MyEnum::C));

When an EnumSet<T> is received via FFI, all bits that don’t correspond to an enum variant of T must be set to 0. Behavior is undefined if any of these bits are set to 1.

Implementations

impl<T: EnumSetType> EnumSet<T>

pub fn new() -> Self

Creates an empty EnumSet.

pub fn only(t: T) -> Self

Returns an EnumSet containing a single element.

pub fn empty() -> Self

Creates an empty EnumSet.

This is an alias for EnumSet::new.

pub fn all() -> Self

Returns an EnumSet containing all valid variants of the enum.

pub fn bit_width() -> u32

Total number of bits used by this type. Note that the actual amount of space used is rounded up to the next highest integer type (u8, u16, u32, u64, or u128).

This is the same as EnumSet::variant_count except in enums with “sparse” variants. (e.g. enum Foo { A = 10, B = 20 })

pub fn variant_count() -> u32

The number of valid variants that this type can contain.

This is the same as EnumSet::bit_width except in enums with “sparse” variants. (e.g. enum Foo { A = 10, B = 20 })

pub fn len(&self) -> usize

Returns the number of elements in this set.

pub fn is_empty(&self) -> bool

Returns true if the set contains no elements.

pub fn clear(&mut self)

Removes all elements from the set.

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

Returns true if self has no elements in common with other. This is equivalent to checking for an empty intersection.

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

Returns true if the set is a superset of another, i.e., self contains at least all the values in other.

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

Returns true if the set is a subset of another, i.e., other contains at least all the values in self.

pub fn union(&self, other: Self) -> Self

Returns a set containing any elements present in either set.

pub fn intersection(&self, other: Self) -> Self

Returns a set containing every element present in both sets.

pub fn difference(&self, other: Self) -> Self

Returns a set containing element present in self but not in other.

pub fn symmetrical_difference(&self, other: Self) -> Self

Returns a set containing every element present in either self or other, but is not present in both.

pub fn complement(&self) -> Self

Returns a set containing all enum variants not in this set.

pub fn contains(&self, value: T) -> bool

Checks whether this set contains a value.

pub fn insert(&mut self, value: T) -> bool

Adds a value to this set.

If the set did not have this value present, true is returned.

If the set did have this value present, false is returned.

pub fn remove(&mut self, value: T) -> bool

Removes a value from this set. Returns whether the value was present in the set.

pub fn insert_all(&mut self, other: Self)

Adds all elements in another set to this one.

pub fn remove_all(&mut self, other: Self)

Removes all values in another set from this one.

pub fn iter(&self) -> EnumSetIter<T>

Iterates the contents of the set in order from the least significant bit to the most significant bit.

Note that iterator invalidation is impossible as the iterator contains a copy of this type, rather than holding a reference to it.

pub fn as_repr(&self) -> <T as EnumSetTypeWithRepr>::Repr where
    T: EnumSetTypeWithRepr, 

Returns a T::Repr representing the elements of this set.

Unlike the other as_* methods, this method is zero-cost and guaranteed not to fail, panic or truncate any bits.

In order to use this method, the definition of T must have the #[enumset(repr = "…")] annotation.

pub unsafe fn from_repr_unchecked(
    bits: <T as EnumSetTypeWithRepr>::Repr
) -> Self where
    T: EnumSetTypeWithRepr, 

Constructs a bitset from a T::Repr without checking for invalid bits.

Unlike the other from_* methods, this method is zero-cost and guaranteed not to fail, panic or truncate any bits, provided the conditions under “Safety” are upheld.

In order to use this method, the definition of T must have the #[enumset(repr = "…")] annotation.

Safety

All bits in the provided parameter bits that don’t correspond to an enum variant of T must be set to 0. Behavior is undefined if any of these bits are set to 1.

pub fn from_repr(bits: <T as EnumSetTypeWithRepr>::Repr) -> Self where
    T: EnumSetTypeWithRepr, 

Constructs a bitset from a T::Repr.

If a bit that doesn’t correspond to an enum variant is set, this method will panic.

In order to use this method, the definition of T must have the #[enumset(repr = "…")] annotation.

pub fn try_from_repr(bits: <T as EnumSetTypeWithRepr>::Repr) -> Option<Self> where
    T: EnumSetTypeWithRepr, 

Attempts to constructs a bitset from a T::Repr.

If a bit that doesn’t correspond to an enum variant is set, this method will return None.

In order to use this method, the definition of T must have the #[enumset(repr = "…")] annotation.

pub fn from_repr_truncated(bits: <T as EnumSetTypeWithRepr>::Repr) -> Self where
    T: EnumSetTypeWithRepr, 

Constructs a bitset from a T::Repr, ignoring invalid variants.

In order to use this method, the definition of T must have the #[enumset(repr = "…")] annotation.

impl<T: EnumSetType> EnumSet<T>

pub fn as_u8(&self) -> u8

Returns a u8 representing the elements of this set.

If the underlying bitset will not fit in a u8 or contains bits that do not correspond to an enum variant, this method will panic.

pub fn try_as_u8(&self) -> Option<u8>

Tries to return a u8 representing the elements of this set.

If the underlying bitset will not fit in a u8 or contains bits that do not correspond to an enum variant, this method will instead return None.

pub fn as_u8_truncated(&self) -> u8

Returns a truncated u8 representing the elements of this set.

If the underlying bitset will not fit in a u8, this method will truncate any bits that don’t fit or do not correspond to an enum variant.

pub fn from_u8(bits: u8) -> Self

Constructs a bitset from a u8.

If a bit that doesn’t correspond to an enum variant is set, this method will panic.

pub fn try_from_u8(bits: u8) -> Option<Self>

Attempts to constructs a bitset from a u8.

If a bit that doesn’t correspond to an enum variant is set, this method will return None.

pub fn from_u8_truncated(bits: u8) -> Self

Constructs a bitset from a u8, ignoring invalid variants.

pub unsafe fn from_u8_unchecked(bits: u8) -> Self

Constructs a bitset from a u8, without checking for invalid bits.

Safety

All bits in the provided parameter bits that don’t correspond to an enum variant of T must be set to 0. Behavior is undefined if any of these bits are set to 1.

pub fn as_u16(&self) -> u16

Returns a u16 representing the elements of this set.

If the underlying bitset will not fit in a u16 or contains bits that do not correspond to an enum variant, this method will panic.

pub fn try_as_u16(&self) -> Option<u16>

Tries to return a u16 representing the elements of this set.

If the underlying bitset will not fit in a u16 or contains bits that do not correspond to an enum variant, this method will instead return None.

pub fn as_u16_truncated(&self) -> u16

Returns a truncated u16 representing the elements of this set.

If the underlying bitset will not fit in a u16, this method will truncate any bits that don’t fit or do not correspond to an enum variant.

pub fn from_u16(bits: u16) -> Self

Constructs a bitset from a u16.

If a bit that doesn’t correspond to an enum variant is set, this method will panic.

pub fn try_from_u16(bits: u16) -> Option<Self>

Attempts to constructs a bitset from a u16.

If a bit that doesn’t correspond to an enum variant is set, this method will return None.

pub fn from_u16_truncated(bits: u16) -> Self

Constructs a bitset from a u16, ignoring invalid variants.

pub unsafe fn from_u16_unchecked(bits: u16) -> Self

Constructs a bitset from a u16, without checking for invalid bits.

Safety

All bits in the provided parameter bits that don’t correspond to an enum variant of T must be set to 0. Behavior is undefined if any of these bits are set to 1.

pub fn as_u32(&self) -> u32

Returns a u32 representing the elements of this set.

If the underlying bitset will not fit in a u32 or contains bits that do not correspond to an enum variant, this method will panic.

pub fn try_as_u32(&self) -> Option<u32>

Tries to return a u32 representing the elements of this set.

If the underlying bitset will not fit in a u32 or contains bits that do not correspond to an enum variant, this method will instead return None.

pub fn as_u32_truncated(&self) -> u32

Returns a truncated u32 representing the elements of this set.

If the underlying bitset will not fit in a u32, this method will truncate any bits that don’t fit or do not correspond to an enum variant.

pub fn from_u32(bits: u32) -> Self

Constructs a bitset from a u32.

If a bit that doesn’t correspond to an enum variant is set, this method will panic.

pub fn try_from_u32(bits: u32) -> Option<Self>

Attempts to constructs a bitset from a u32.

If a bit that doesn’t correspond to an enum variant is set, this method will return None.

pub fn from_u32_truncated(bits: u32) -> Self

Constructs a bitset from a u32, ignoring invalid variants.

pub unsafe fn from_u32_unchecked(bits: u32) -> Self

Constructs a bitset from a u32, without checking for invalid bits.

Safety

All bits in the provided parameter bits that don’t correspond to an enum variant of T must be set to 0. Behavior is undefined if any of these bits are set to 1.

pub fn as_u64(&self) -> u64

Returns a u64 representing the elements of this set.

If the underlying bitset will not fit in a u64 or contains bits that do not correspond to an enum variant, this method will panic.

pub fn try_as_u64(&self) -> Option<u64>

Tries to return a u64 representing the elements of this set.

If the underlying bitset will not fit in a u64 or contains bits that do not correspond to an enum variant, this method will instead return None.

pub fn as_u64_truncated(&self) -> u64

Returns a truncated u64 representing the elements of this set.

If the underlying bitset will not fit in a u64, this method will truncate any bits that don’t fit or do not correspond to an enum variant.

pub fn from_u64(bits: u64) -> Self

Constructs a bitset from a u64.

If a bit that doesn’t correspond to an enum variant is set, this method will panic.

pub fn try_from_u64(bits: u64) -> Option<Self>

Attempts to constructs a bitset from a u64.

If a bit that doesn’t correspond to an enum variant is set, this method will return None.

pub fn from_u64_truncated(bits: u64) -> Self

Constructs a bitset from a u64, ignoring invalid variants.

pub unsafe fn from_u64_unchecked(bits: u64) -> Self

Constructs a bitset from a u64, without checking for invalid bits.

Safety

All bits in the provided parameter bits that don’t correspond to an enum variant of T must be set to 0. Behavior is undefined if any of these bits are set to 1.

pub fn as_u128(&self) -> u128

Returns a u128 representing the elements of this set.

If the underlying bitset will not fit in a u128 or contains bits that do not correspond to an enum variant, this method will panic.

pub fn try_as_u128(&self) -> Option<u128>

Tries to return a u128 representing the elements of this set.

If the underlying bitset will not fit in a u128 or contains bits that do not correspond to an enum variant, this method will instead return None.

pub fn as_u128_truncated(&self) -> u128

Returns a truncated u128 representing the elements of this set.

If the underlying bitset will not fit in a u128, this method will truncate any bits that don’t fit or do not correspond to an enum variant.

pub fn from_u128(bits: u128) -> Self

Constructs a bitset from a u128.

If a bit that doesn’t correspond to an enum variant is set, this method will panic.

pub fn try_from_u128(bits: u128) -> Option<Self>

Attempts to constructs a bitset from a u128.

If a bit that doesn’t correspond to an enum variant is set, this method will return None.

pub fn from_u128_truncated(bits: u128) -> Self

Constructs a bitset from a u128, ignoring invalid variants.

pub unsafe fn from_u128_unchecked(bits: u128) -> Self

Constructs a bitset from a u128, without checking for invalid bits.

Safety

All bits in the provided parameter bits that don’t correspond to an enum variant of T must be set to 0. Behavior is undefined if any of these bits are set to 1.

pub fn as_usize(&self) -> usize

Returns a usize representing the elements of this set.

If the underlying bitset will not fit in a usize or contains bits that do not correspond to an enum variant, this method will panic.

pub fn try_as_usize(&self) -> Option<usize>

Tries to return a usize representing the elements of this set.

If the underlying bitset will not fit in a usize or contains bits that do not correspond to an enum variant, this method will instead return None.

pub fn as_usize_truncated(&self) -> usize

Returns a truncated usize representing the elements of this set.

If the underlying bitset will not fit in a usize, this method will truncate any bits that don’t fit or do not correspond to an enum variant.

pub fn from_usize(bits: usize) -> Self

Constructs a bitset from a usize.

If a bit that doesn’t correspond to an enum variant is set, this method will panic.

pub fn try_from_usize(bits: usize) -> Option<Self>

Attempts to constructs a bitset from a usize.

If a bit that doesn’t correspond to an enum variant is set, this method will return None.

pub fn from_usize_truncated(bits: usize) -> Self

Constructs a bitset from a usize, ignoring invalid variants.

pub unsafe fn from_usize_unchecked(bits: usize) -> Self

Constructs a bitset from a usize, without checking for invalid bits.

Safety

All bits in the provided parameter bits that don’t correspond to an enum variant of T must be set to 0. Behavior is undefined if any of these bits are set to 1.

Trait Implementations

impl<T: EnumSetType, O: Into<EnumSet<T>>> BitAnd<O> for EnumSet<T>

type Output = Self

The resulting type after applying the & operator.

fn bitand(self, other: O) -> Self::Output

Performs the & operation.

impl<T: EnumSetType, O: Into<EnumSet<T>>> BitAndAssign<O> for EnumSet<T>

fn bitand_assign(&mut self, rhs: O)

Performs the &= operation.

impl<T: EnumSetType, O: Into<EnumSet<T>>> BitOr<O> for EnumSet<T>

type Output = Self

The resulting type after applying the | operator.

fn bitor(self, other: O) -> Self::Output

Performs the | operation.

impl<T: EnumSetType, O: Into<EnumSet<T>>> BitOrAssign<O> for EnumSet<T>

fn bitor_assign(&mut self, rhs: O)

Performs the |= operation.

impl<T: EnumSetType, O: Into<EnumSet<T>>> BitXor<O> for EnumSet<T>

type Output = Self

The resulting type after applying the ^ operator.

fn bitxor(self, other: O) -> Self::Output

Performs the ^ operation.

impl<T: EnumSetType, O: Into<EnumSet<T>>> BitXorAssign<O> for EnumSet<T>

fn bitxor_assign(&mut self, rhs: O)

Performs the ^= operation.

impl<T: Clone + EnumSetType> Clone for EnumSet<T> where
    T::Repr: Clone, 

fn clone(&self) -> EnumSet<T>

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<T: EnumSetType + Debug> Debug for EnumSet<T>

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

Formats the value using the given formatter.

impl<T: EnumSetType> Default for EnumSet<T>

fn default() -> Self

Returns an empty set.

impl<T: EnumSetType> Extend<EnumSet<T>> for EnumSet<T>

fn extend<I: IntoIterator<Item = EnumSet<T>>>(&mut self, iter: I)

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: EnumSetType> Extend<T> for EnumSet<T>

fn extend<I: IntoIterator<Item = T>>(&mut self, iter: I)

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: EnumSetType> From<T> for EnumSet<T>

fn from(t: T) -> Self

Converts to this type from the input type.

impl<T: EnumSetType> FromIterator<EnumSet<T>> for EnumSet<T>

fn from_iter<I: IntoIterator<Item = EnumSet<T>>>(iter: I) -> Self

Creates a value from an iterator.

impl<T: EnumSetType> FromIterator<T> for EnumSet<T>

fn from_iter<I: IntoIterator<Item = T>>(iter: I) -> Self

Creates a value from an iterator.

impl<T: EnumSetType> Hash for EnumSet<T>

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: EnumSetType> IntoIterator for EnumSet<T>

type Item = T

The type of the elements being iterated over.

type IntoIter = EnumSetIter<T>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl<T: EnumSetType> Not for EnumSet<T>

type Output = Self

The resulting type after applying the ! operator.

fn not(self) -> Self::Output

Performs the unary ! operation.

impl<T: EnumSetType> Ord for EnumSet<T>

fn cmp(&self, other: &Self) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

Restrict a value to a certain interval.

impl<T: PartialEq + EnumSetType> PartialEq<EnumSet<T>> for EnumSet<T> where
    T::Repr: PartialEq, 

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

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

fn ne(&self, other: &EnumSet<T>) -> bool

This method tests for !=.

impl<T: EnumSetType> PartialEq<T> for EnumSet<T>

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: EnumSetType> PartialOrd<EnumSet<T>> for EnumSet<T>

fn partial_cmp(&self, other: &Self) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

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

This method tests less than (for self and other) and is used by the < operator.

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

This method tests less than or equal to (for self and other) and is used by the <= operator.

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

This method tests greater than (for self and other) and is used by the > operator.

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

This method tests greater than or equal to (for self and other) and is used by the >= operator.

impl<T: EnumSetType, O: Into<EnumSet<T>>> Sub<O> for EnumSet<T>

type Output = Self

The resulting type after applying the - operator.

fn sub(self, other: O) -> Self::Output

Performs the - operation.

impl<T: EnumSetType, O: Into<EnumSet<T>>> SubAssign<O> for EnumSet<T>

fn sub_assign(&mut self, rhs: O)

Performs the -= operation.

impl<'a, T: EnumSetType> Sum<&'a EnumSet<T>> for EnumSet<T>

fn sum<I: Iterator<Item = &'a Self>>(iter: I) -> Self

Method which takes an iterator and generates Self from the elements by “summing up” the items.

impl<'a, T: EnumSetType> Sum<&'a T> for EnumSet<T>

fn sum<I: Iterator<Item = &'a T>>(iter: I) -> Self

Method which takes an iterator and generates Self from the elements by “summing up” the items.

impl<T: EnumSetType> Sum<EnumSet<T>> for EnumSet<T>

fn sum<I: Iterator<Item = Self>>(iter: I) -> Self

Method which takes an iterator and generates Self from the elements by “summing up” the items.

impl<T: EnumSetType> Sum<T> for EnumSet<T>

fn sum<I: Iterator<Item = T>>(iter: I) -> Self

Method which takes an iterator and generates Self from the elements by “summing up” the items.

impl<T: Copy + EnumSetType> Copy for EnumSet<T> where
    T::Repr: Copy, 

impl<T: Eq + EnumSetType> Eq for EnumSet<T> where
    T::Repr: Eq, 

impl<T: EnumSetType> StructuralEq for EnumSet<T>

impl<T: EnumSetType> StructuralPartialEq for EnumSet<T>