Struct EnumSet

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

Expand description

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

§Array representation

Sets with more than 128 variants are instead stored with an underlying array of u64s. This is treated as if it was a single large integer. The nth least significant bit of this integer is stored in the n % 64th least significant bit of the n / 64th element in the array.

§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, EnumSet is serialized by directly writing out a single integer containing the numeric representation of the bitset. The integer type used is the smallest one that can fit the largest variant in the enum. If no integer type is large enough, instead the EnumSet is serialized as an array of u64s containing the array representation.

The #[enumset(serialize_repr = "…")] attribute can be used to override the representation used. Valid values are as follows:

u8, u16, u32, u64, and u128 serialize the type as the corresponding integer type.
array serializes the set as an list of u64s corresponding to the array representation.
list serializes the set as a list of enum variants. This requires your enum type implement Serialize and Deserialize.
map serializes the set as a map of enum variants to booleans. The set contains a value if the boolean is true. This requires your enum type implement Serialize and Deserialize.

The representation used is determined statically at compile time, and there is currently no support for reading different formats with the same deserializer.

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

§FFI, Safety and `repr`

If an enum type T is annotated with #[enumset(repr = "…")] where … is a primitive integer type, 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> EnumSet<T>
where T: EnumSetType,

pub const EMPTY: EnumSet<T> = Self::EMPTY_REPR

👎Deprecated: Use EnumSet::empty() instead.

An empty EnumSet.

This is deprecated because EnumSet::empty is now const.

pub const ALL: EnumSet<T> = Self::ALL_REPR

👎Deprecated: Use EnumSet::all() instead.

An EnumSet containing all valid variants of the enum.

This is deprecated because EnumSet::all is now const.

pub const fn new() -> EnumSet<T>

Creates an empty EnumSet.

pub fn only(t: T) -> EnumSet<T>

Returns an EnumSet containing a single element.

pub const fn empty() -> EnumSet<T>

Creates an empty EnumSet.

This is an alias for EnumSet::new.

pub const fn all() -> EnumSet<T>

Returns an EnumSet containing all valid variants of the enum.

pub const 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 const 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: EnumSet<T>) -> 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: EnumSet<T>) -> 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: EnumSet<T>) -> 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: EnumSet<T>) -> EnumSet<T>

Returns a set containing any elements present in either set.

pub fn intersection(&self, other: EnumSet<T>) -> EnumSet<T>

Returns a set containing every element present in both sets.

pub fn difference(&self, other: EnumSet<T>) -> EnumSet<T>

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

pub fn symmetrical_difference(&self, other: EnumSet<T>) -> EnumSet<T>

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

pub fn complement(&self) -> EnumSet<T>

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: EnumSet<T>)

Adds all elements in another set to this one.

pub fn remove_all(&mut self, other: EnumSet<T>)

Removes all values in another set from this one.

§

impl<T> EnumSet<T>
where T: EnumSetType + EnumSetTypeWithRepr,

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

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, ) -> EnumSet<T>

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) -> EnumSet<T>

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<EnumSet<T>>

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) -> EnumSet<T>

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> EnumSet<T>
where T: EnumSetType,

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, 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, this method will panic.

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.

pub fn from_u8(bits: u8) -> EnumSet<T>

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<EnumSet<T>>

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) -> EnumSet<T>

Constructs a bitset from a u8, ignoring bits that do not correspond to a variant.

pub unsafe fn from_u8_unchecked(bits: u8) -> EnumSet<T>

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, 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, this method will panic.

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.

pub fn from_u16(bits: u16) -> EnumSet<T>

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<EnumSet<T>>

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) -> EnumSet<T>

Constructs a bitset from a u16, ignoring bits that do not correspond to a variant.

pub unsafe fn from_u16_unchecked(bits: u16) -> EnumSet<T>

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, 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, this method will panic.

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.

pub fn from_u32(bits: u32) -> EnumSet<T>

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<EnumSet<T>>

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) -> EnumSet<T>

Constructs a bitset from a u32, ignoring bits that do not correspond to a variant.

pub unsafe fn from_u32_unchecked(bits: u32) -> EnumSet<T>

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, 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, this method will panic.

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.

pub fn from_u64(bits: u64) -> EnumSet<T>

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<EnumSet<T>>

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) -> EnumSet<T>

Constructs a bitset from a u64, ignoring bits that do not correspond to a variant.

pub unsafe fn from_u64_unchecked(bits: u64) -> EnumSet<T>

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, 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, this method will panic.

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.

pub fn from_u128(bits: u128) -> EnumSet<T>

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<EnumSet<T>>

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) -> EnumSet<T>

Constructs a bitset from a u128, ignoring bits that do not correspond to a variant.

pub unsafe fn from_u128_unchecked(bits: u128) -> EnumSet<T>

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, 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, this method will panic.

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.

pub fn from_usize(bits: usize) -> EnumSet<T>

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<EnumSet<T>>

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) -> EnumSet<T>

Constructs a bitset from a usize, ignoring bits that do not correspond to a variant.

pub unsafe fn from_usize_unchecked(bits: usize) -> EnumSet<T>

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.

§

impl<T> EnumSet<T>
where T: EnumSetType,

pub fn as_array<const O: usize>(&self) -> [u64; O]

Returns an [u64; O] representing the elements of this set.

If the underlying bitset will not fit in a [u64; O], this method will panic.

pub fn try_as_array<const O: usize>(&self) -> Option<[u64; O]>

Returns an [u64; O] representing the elements of this set.

If the underlying bitset will not fit in a [u64; O], this method will instead return None.

pub fn as_array_truncated<const O: usize>(&self) -> [u64; O]

Returns an [u64; O] representing the elements of this set.

If the underlying bitset will not fit in a [u64; O], this method will truncate any bits that don’t fit.

pub fn from_array<const O: usize>(v: [u64; O]) -> EnumSet<T>

Attempts to constructs a bitset from a [u64; O].

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

pub fn try_from_array<const O: usize>(bits: [u64; O]) -> Option<EnumSet<T>>

Attempts to constructs a bitset from a [u64; O].

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

pub fn from_array_truncated<const O: usize>(bits: [u64; O]) -> EnumSet<T>

Constructs a bitset from a [u64; O], ignoring bits that do not correspond to a variant.

pub unsafe fn from_array_unchecked<const O: usize>(bits: [u64; O]) -> EnumSet<T>

Constructs a bitset from a [u64; O], 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 copy_into_slice(&self, data: &mut [u64])

Copies the elements of this set into a &mut [u64].

If the underlying bitset will not fit in the provided slice, this method will panic.

pub fn try_copy_into_slice(&self, data: &mut [u64]) -> Option<()>

Copies the elements of this set into a &mut [u64].

If the underlying bitset will not fit in the provided slice, this method will return None. Otherwise, it will return Some(()).

pub fn copy_into_slice_truncated(&self, data: &mut [u64])

Copies the elements of this set into a &mut [u64].

If the underlying bitset will not fit in the provided slice, this method will truncate any bits that don’t fit.

pub fn from_slice(v: &[u64]) -> EnumSet<T>

Attempts to 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_slice(bits: &[u64]) -> Option<EnumSet<T>>

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_slice_truncated(bits: &[u64]) -> EnumSet<T>

Constructs a bitset from a &[u64], ignoring bits that do not correspond to a variant.

pub unsafe fn from_slice_unchecked(bits: &[u64]) -> EnumSet<T>

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.

§