Struct enumset::EnumSet

source ·

#[repr(transparent)]
pub struct EnumSet<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.

Struct enumset::EnumSet

Implementations§

impl<T: EnumSetType> EnumSet<T>

pub const EMPTY: Self = _

pub const ALL: Self = _

pub fn new() -> Self

pub fn only(t: T) -> Self

pub fn empty() -> Self

pub fn all() -> Self

pub fn bit_width() -> u32

pub fn variant_count() -> u32

pub fn len(&self) -> usize

pub fn is_empty(&self) -> bool

pub fn clear(&mut self)

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

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

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

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

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

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

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

pub fn complement(&self) -> Self

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

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

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

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

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

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

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

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

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

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

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

impl<T: EnumSetType> EnumSet<T>

pub fn as_u8(&self) -> u8

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

pub fn as_u8_truncated(&self) -> u8

pub fn from_u8(bits: u8) -> Self

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

pub fn from_u8_truncated(bits: u8) -> Self

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

pub fn as_u16(&self) -> u16

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

pub fn as_u16_truncated(&self) -> u16

pub fn from_u16(bits: u16) -> Self

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

pub fn from_u16_truncated(bits: u16) -> Self

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

pub fn as_u32(&self) -> u32

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

pub fn as_u32_truncated(&self) -> u32

pub fn from_u32(bits: u32) -> Self

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

pub fn from_u32_truncated(bits: u32) -> Self

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

pub fn as_u64(&self) -> u64

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

pub fn as_u64_truncated(&self) -> u64

pub fn from_u64(bits: u64) -> Self

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

pub fn from_u64_truncated(bits: u64) -> Self

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

pub fn as_u128(&self) -> u128

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

pub fn as_u128_truncated(&self) -> u128

pub fn from_u128(bits: u128) -> Self

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

pub fn from_u128_truncated(bits: u128) -> Self

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

pub fn as_usize(&self) -> usize

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

pub fn as_usize_truncated(&self) -> usize

pub fn from_usize(bits: usize) -> Self

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

pub fn from_usize_truncated(bits: usize) -> Self

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

impl<T: EnumSetType> EnumSet<T>

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

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

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