//! }
//! ```
//!
+//! For more information on more advanced use cases, see the documentation for [`EnumSetType`].
+//!
//! # Working with EnumSets
//!
//! EnumSets can be constructed via [`EnumSet::new()`] like a normal set. In addition,
//! assert_eq!(CONST_SET, Enum::A | Enum::B);
//! ```
//!
-//! Mutable operations on the [`EnumSet`] otherwise work basically as expected:
+//! Mutable operations on the [`EnumSet`] otherwise similarly to Rust's builtin sets:
//!
//! ```rust
//! # use enumset::*;
//! assert_eq!(set, Enum::A | Enum::E | Enum::G);
//! ```
-pub use enumset_derive::*;
+pub use enumset_derive::EnumSetType;
use core::cmp::Ordering;
use core::fmt;
use core::iter::FromIterator;
use core::ops::*;
-use num_traits::*;
-
#[doc(hidden)]
/// Everything in this module is internal API and may change at any time.
-pub mod internal {
+pub mod __internal {
use super::*;
- /// A struct used to type check [`enum_set!`].
- pub struct EnumSetSameTypeHack<'a, T: EnumSetType + 'static> {
- pub unified: &'a [T],
- pub enum_set: EnumSet<T>,
- }
-
/// A reexport of core to allow our macros to be generic to std vs core.
pub use ::core as core_export;
/// The actual members of EnumSetType. Put here to avoid polluting global namespaces.
pub unsafe trait EnumSetTypePrivate {
+ /// The underlying type used to store the bitset.
type Repr: EnumSetTypeRepr;
+ /// A mask of bits that are valid in the bitset.
const ALL_BITS: Self::Repr;
+
+ /// Converts an enum of this type into its bit position.
fn enum_into_u32(self) -> u32;
+ /// Converts a bit position into an enum value.
unsafe fn enum_from_u32(val: u32) -> Self;
+ /// Serializes the `EnumSet`.
+ ///
+ /// This and `deserialize` are part of the `EnumSetType` trait so the procedural derive
+ /// can control how `EnumSet` is serialized.
#[cfg(feature = "serde")]
fn serialize<S: serde::Serializer>(set: EnumSet<Self>, ser: S) -> Result<S::Ok, S::Error>
where Self: EnumSetType;
+ /// Deserializes the `EnumSet`.
#[cfg(feature = "serde")]
fn deserialize<'de, D: serde::Deserializer<'de>>(de: D) -> Result<EnumSet<Self>, D::Error>
where Self: EnumSetType;
}
}
-use crate::internal::EnumSetTypePrivate;
-#[cfg(feature = "serde")] use crate::internal::serde;
+use crate::__internal::EnumSetTypePrivate;
+#[cfg(feature = "serde")] use crate::__internal::serde;
#[cfg(feature = "serde")] use crate::serde::{Serialize, Deserialize};
mod private {
use super::*;
+ use core::convert::TryInto;
+ /// A trait marking valid underlying bitset storage types and providing the
+ /// operations `EnumSet` and related types use.
pub trait EnumSetTypeRepr :
- PrimInt + WrappingSub + CheckedShl + Debug + Hash + FromPrimitive + ToPrimitive +
- AsPrimitive<u8> + AsPrimitive<u16> + AsPrimitive<u32> + AsPrimitive<u64> +
- AsPrimitive<u128> + AsPrimitive<usize>
+ // Basic traits used to derive traits
+ Copy +
+ Ord +
+ Eq +
+ Debug +
+ Hash +
+ // Operations used by enumset
+ BitAnd<Output = Self> +
+ BitOr<Output = Self> +
+ BitXor<Output = Self> +
+ Not<Output = Self> +
{
const WIDTH: u32;
+ fn is_empty(&self) -> bool;
+ fn empty() -> Self;
+
+ fn add_bit(&mut self, bit: u32);
+ fn remove_bit(&mut self, bit: u32);
+ fn has_bit(&self, bit: u32) -> bool;
+
+ fn count_ones(&self) -> u32;
+ fn count_remaining_ones(&self, cursor: u32) -> usize;
+ fn leading_zeros(&self) -> u32;
+
fn from_u8(v: u8) -> Self;
fn from_u16(v: u16) -> Self;
fn from_u32(v: u32) -> Self;
fn from_u64(v: u64) -> Self;
fn from_u128(v: u128) -> Self;
fn from_usize(v: usize) -> Self;
+
+ fn to_u8(&self) -> u8;
+ fn to_u16(&self) -> u16;
+ fn to_u32(&self) -> u32;
+ fn to_u64(&self) -> u64;
+ fn to_u128(&self) -> u128;
+ fn to_usize(&self) -> usize;
+
+ fn from_u8_opt(v: u8) -> Option<Self>;
+ fn from_u16_opt(v: u16) -> Option<Self>;
+ fn from_u32_opt(v: u32) -> Option<Self>;
+ fn from_u64_opt(v: u64) -> Option<Self>;
+ fn from_u128_opt(v: u128) -> Option<Self>;
+ fn from_usize_opt(v: usize) -> Option<Self>;
+
+ fn to_u8_opt(&self) -> Option<u8>;
+ fn to_u16_opt(&self) -> Option<u16>;
+ fn to_u32_opt(&self) -> Option<u32>;
+ fn to_u64_opt(&self) -> Option<u64>;
+ fn to_u128_opt(&self) -> Option<u128>;
+ fn to_usize_opt(&self) -> Option<usize>;
}
macro_rules! prim {
($name:ty, $width:expr) => {
impl EnumSetTypeRepr for $name {
const WIDTH: u32 = $width;
- fn from_u8(v: u8) -> Self { v.as_() }
- fn from_u16(v: u16) -> Self { v.as_() }
- fn from_u32(v: u32) -> Self { v.as_() }
- fn from_u64(v: u64) -> Self { v.as_() }
- fn from_u128(v: u128) -> Self { v.as_() }
- fn from_usize(v: usize) -> Self { v.as_() }
+
+ fn is_empty(&self) -> bool { *self == 0 }
+ fn empty() -> Self { 0 }
+
+ fn add_bit(&mut self, bit: u32) {
+ *self |= 1 << bit as $name;
+ }
+ fn remove_bit(&mut self, bit: u32) {
+ *self &= !(1 << bit as $name);
+ }
+ fn has_bit(&self, bit: u32) -> bool {
+ (self & (1 << bit as $name)) != 0
+ }
+
+ fn count_ones(&self) -> u32 { (*self).count_ones() }
+ fn leading_zeros(&self) -> u32 { (*self).leading_zeros() }
+
+ fn count_remaining_ones(&self, cursor: u32) -> usize {
+ let left_mask =
+ !((1 as $name).checked_shl(cursor).unwrap_or(0).wrapping_sub(1));
+ (*self & left_mask).count_ones() as usize
+ }
+
+ fn from_u8(v: u8) -> Self { v as $name }
+ fn from_u16(v: u16) -> Self { v as $name }
+ fn from_u32(v: u32) -> Self { v as $name }
+ fn from_u64(v: u64) -> Self { v as $name }
+ fn from_u128(v: u128) -> Self { v as $name }
+ fn from_usize(v: usize) -> Self { v as $name }
+
+ fn to_u8(&self) -> u8 { (*self) as u8 }
+ fn to_u16(&self) -> u16 { (*self) as u16 }
+ fn to_u32(&self) -> u32 { (*self) as u32 }
+ fn to_u64(&self) -> u64 { (*self) as u64 }
+ fn to_u128(&self) -> u128 { (*self) as u128 }
+ fn to_usize(&self) -> usize { (*self) as usize }
+
+ fn from_u8_opt(v: u8) -> Option<Self> { v.try_into().ok() }
+ fn from_u16_opt(v: u16) -> Option<Self> { v.try_into().ok() }
+ fn from_u32_opt(v: u32) -> Option<Self> { v.try_into().ok() }
+ fn from_u64_opt(v: u64) -> Option<Self> { v.try_into().ok() }
+ fn from_u128_opt(v: u128) -> Option<Self> { v.try_into().ok() }
+ fn from_usize_opt(v: usize) -> Option<Self> { v.try_into().ok() }
+
+ fn to_u8_opt(&self) -> Option<u8> { (*self).try_into().ok() }
+ fn to_u16_opt(&self) -> Option<u16> { (*self).try_into().ok() }
+ fn to_u32_opt(&self) -> Option<u32> { (*self).try_into().ok() }
+ fn to_u64_opt(&self) -> Option<u64> { (*self).try_into().ok() }
+ fn to_u128_opt(&self) -> Option<u128> { (*self).try_into().ok() }
+ fn to_usize_opt(&self) -> Option<usize> { (*self).try_into().ok() }
}
}
}
/// The trait used to define enum types that may be used with [`EnumSet`].
///
/// This trait should be implemented using `#[derive(EnumSetType)]`. Its internal structure is
-/// not currently stable, and may change at any time.
+/// not stable, and may change at any time.
///
/// # Custom Derive
///
+/// Any C-like enum is supported, as long as there are no more than 128 variants in the enum,
+/// and no variant discriminator is larger than 127.
+///
/// The custom derive for [`EnumSetType`] automatically creates implementations of [`PartialEq`],
/// [`Sub`], [`BitAnd`], [`BitOr`], [`BitXor`], and [`Not`] allowing the enum to be used as
/// if it were an [`EnumSet`] in expressions. This can be disabled by adding an `#[enumset(no_ops)]`
/// The custom derive for `EnumSetType` automatically implements [`Copy`], [`Clone`], [`Eq`], and
/// [`PartialEq`] on the enum. These are required for the [`EnumSet`] to function.
///
-/// Any C-like enum is supported, as long as there are no more than 128 variants in the enum,
-/// and no variant discriminator is larger than 127.
+/// In addition, if you have renamed the `enumset` crate in your crate, you can use the
+/// `#[enumset(crate_name = "enumset2")]` attribute to tell the custom derive to use that name
+/// instead.
+///
+/// Attributes controlling the serialization of an `EnumSet` are documented in
+/// [its documentation](./struct.EnumSet.html#serialization).
///
/// # Examples
///
/// 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 the underlying enum. In general, an enum variant with a numeric value of `n` is stored in
+/// the nth least significant bit (corresponding with a mask of, e.g. `1 << enum as u32`).
///
/// # Serialization
///
-/// By default, `EnumSet`s are serialized as an unsigned integer of the same width as used to store
-/// it in memory.
+/// When the `serde` feature is enabled, `EnumSet`s 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.
///
-/// Unknown bits are ignored, and are simply dropped. To override this behavior, you can add a
-/// `#[enumset(serialize_deny_unknown)]` annotation to your enum.
+/// By default, `EnumSet`s 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
+/// `EnumSet`s are serialized with formats like `bincode`.
///
-/// You can add a `#[enumset(serialize_repr = "u8")]` annotation to your enum to manually set
-/// the number width the `EnumSet` is serialized as. Only unsigned integer types may be used. This
-/// can be used to avoid breaking changes in certain serialization formats (such as `bincode`).
+/// 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.
///
-/// In addition, the `#[enumset(serialize_as_list)]` annotation causes the `EnumSet` to be
+/// 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`].
+/// [`Serialize`] and [`Deserialize`]. Note that this is a breaking change
#[derive(Copy, Clone, PartialEq, Eq)]
pub struct EnumSet<T: EnumSetType> {
#[doc(hidden)]
pub __enumset_underlying: T::Repr
}
impl <T: EnumSetType> EnumSet<T> {
- fn mask(bit: u32) -> T::Repr {
- Shl::<usize>::shl(T::Repr::one(), bit as usize)
- }
- fn has_bit(&self, bit: u32) -> bool {
- let mask = Self::mask(bit);
- self.__enumset_underlying & mask == mask
- }
- fn partial_bits(bits: u32) -> T::Repr {
- T::Repr::one().checked_shl(bits as u32)
- .unwrap_or(T::Repr::zero())
- .wrapping_sub(&T::Repr::one())
- }
-
// Returns all bits valid for the enum
fn all_bits() -> T::Repr {
T::ALL_BITS
/// Creates an empty `EnumSet`.
pub fn new() -> Self {
- EnumSet { __enumset_underlying: T::Repr::zero() }
+ EnumSet { __enumset_underlying: T::Repr::empty() }
}
/// Returns an `EnumSet` containing a single element.
pub fn only(t: T) -> Self {
- EnumSet { __enumset_underlying: Self::mask(t.enum_into_u32()) }
+ let mut set = Self::new();
+ set.insert(t);
+ set
}
/// Creates an empty `EnumSet`.
}
/// Returns `true` if the set contains no elements.
pub fn is_empty(&self) -> bool {
- self.__enumset_underlying.is_zero()
+ self.__enumset_underlying.is_empty()
}
/// Removes all elements from the set.
pub fn clear(&mut self) {
- self.__enumset_underlying = T::Repr::zero()
+ self.__enumset_underlying = T::Repr::empty()
}
/// Returns `true` if `self` has no elements in common with `other`. This is equivalent to
/// Checks whether this set contains a value.
pub fn contains(&self, value: T) -> bool {
- self.has_bit(value.enum_into_u32())
+ self.__enumset_underlying.has_bit(value.enum_into_u32())
}
/// Adds a value to this set.
/// If the set did have this value present, `false` is returned.
pub fn insert(&mut self, value: T) -> bool {
let contains = !self.contains(value);
- self.__enumset_underlying = self.__enumset_underlying | Self::mask(value.enum_into_u32());
+ self.__enumset_underlying.add_bit(value.enum_into_u32());
contains
}
/// Removes a value from this set. Returns whether the value was present in the set.
pub fn remove(&mut self, value: T) -> bool {
let contains = self.contains(value);
- self.__enumset_underlying = self.__enumset_underlying & !Self::mask(value.enum_into_u32());
+ self.__enumset_underlying.remove_bit(value.enum_into_u32());
contains
}
}
}
+/// Helper macro for generating conversion functions.
macro_rules! conversion_impls {
(
$(for_num!(
- $underlying:ty, $underlying_str:expr, $from_fn:ident, $to_fn:ident,
+ $underlying:ty, $underlying_str:expr,
+ $from_fn:ident $to_fn:ident $from_fn_opt:ident $to_fn_opt:ident,
$from:ident $try_from:ident $from_truncated:ident
$to:ident $try_to:ident $to_truncated:ident
);)*
impl <T : EnumSetType> EnumSet<T> {$(
#[doc = "Returns a `"]
#[doc = $underlying_str]
- #[doc = "` representing the elements of this set. \n\nIf the underlying bitset will \
+ #[doc = "` representing the elements of this set.\n\nIf the underlying bitset will \
not fit in a `"]
#[doc = $underlying_str]
#[doc = "`, this method will panic."]
#[doc = "Tries to return a `"]
#[doc = $underlying_str]
- #[doc = "` representing the elements of this set. \n\nIf the underlying bitset will \
+ #[doc = "` representing the elements of this set.\n\nIf the underlying bitset will \
not fit in a `"]
#[doc = $underlying_str]
#[doc = "`, this method will instead return `None`."]
pub fn $try_to(&self) -> Option<$underlying> {
- self.__enumset_underlying.$to_fn()
+ EnumSetTypeRepr::$to_fn_opt(&self.__enumset_underlying)
}
#[doc = "Returns a truncated `"]
#[doc = $underlying_str]
- #[doc = "` representing the elements of this set. \n\nIf the underlying bitset will \
+ #[doc = "` representing the elements of this set.\n\nIf the underlying bitset will \
not fit in a `"]
#[doc = $underlying_str]
#[doc = "`, this method will truncate any bits that don't fit."]
pub fn $to_truncated(&self) -> $underlying {
- AsPrimitive::<$underlying>::as_(self.__enumset_underlying)
+ EnumSetTypeRepr::$to_fn(&self.__enumset_underlying)
}
#[doc = "Constructs a bitset from a `"]
#[doc = $underlying_str]
- #[doc = "`. \n\nIf a bit that doesn't correspond to an enum variant is set, this \
+ #[doc = "`.\n\nIf a bit that doesn't correspond to an enum variant is set, this \
method will panic."]
pub fn $from(bits: $underlying) -> Self {
Self::$try_from(bits).expect("Bitset contains invalid variants.")
#[doc = "Attempts to constructs a bitset from a `"]
#[doc = $underlying_str]
- #[doc = "`. \n\nIf a bit that doesn't correspond to an enum variant is set, this \
+ #[doc = "`.\n\nIf a bit that doesn't correspond to an enum variant is set, this \
method will return `None`."]
pub fn $try_from(bits: $underlying) -> Option<Self> {
- let bits = <T::Repr as FromPrimitive>::$from_fn(bits);
+ let bits = T::Repr::$from_fn_opt(bits);
let mask = Self::all().__enumset_underlying;
- bits.and_then(|bits| if (bits & !mask) == T::Repr::zero() {
+ bits.and_then(|bits| if (bits & !mask).is_empty() {
Some(EnumSet { __enumset_underlying: bits })
} else {
None
)*}
}
}
-
conversion_impls! {
- for_num!(u8, "u8", from_u8, to_u8,
+ for_num!(u8, "u8", from_u8 to_u8 from_u8_opt to_u8_opt,
from_u8 try_from_u8 from_u8_truncated as_u8 try_as_u8 as_u8_truncated);
- for_num!(u16, "u16", from_u16, to_u16,
+ for_num!(u16, "u16", from_u16 to_u16 from_u16_opt to_u16_opt,
from_u16 try_from_u16 from_u16_truncated as_u16 try_as_u16 as_u16_truncated);
- for_num!(u32, "u32", from_u32, to_u32,
+ for_num!(u32, "u32", from_u32 to_u32 from_u32_opt to_u32_opt,
from_u32 try_from_u32 from_u32_truncated as_u32 try_as_u32 as_u32_truncated);
- for_num!(u64, "u64", from_u64, to_u64,
+ for_num!(u64, "u64", from_u64 to_u64 from_u64_opt to_u64_opt,
from_u64 try_from_u64 from_u64_truncated as_u64 try_as_u64 as_u64_truncated);
- for_num!(u128, "u128", from_u128, to_u128,
+ for_num!(u128, "u128", from_u128 to_u128 from_u128_opt to_u128_opt,
from_u128 try_from_u128 from_u128_truncated as_u128 try_as_u128 as_u128_truncated);
- for_num!(usize, "usize", from_usize, to_usize,
+ for_num!(usize, "usize", from_usize to_usize from_usize_opt to_usize_opt,
from_usize try_from_usize from_usize_truncated
as_usize try_as_usize as_usize_truncated);
}
impl <T: EnumSetType> PartialEq<T> for EnumSet<T> {
fn eq(&self, other: &T) -> bool {
- self.__enumset_underlying == EnumSet::<T>::mask(other.enum_into_u32())
+ self.__enumset_underlying == EnumSet::only(*other).__enumset_underlying
}
}
impl <T: EnumSetType + Debug> Debug for EnumSet<T> {
while self.1 < EnumSet::<T>::bit_width() {
let bit = self.1;
self.1 += 1;
- if self.0.has_bit(bit) {
+ if self.0.__enumset_underlying.has_bit(bit) {
return unsafe { Some(T::enum_from_u32(bit)) }
}
}
None
}
fn size_hint(&self) -> (usize, Option<usize>) {
- let left_mask = !EnumSet::<T>::partial_bits(self.1);
- let left = (self.0.__enumset_underlying & left_mask).count_ones() as usize;
+ let left = self.0.__enumset_underlying.count_remaining_ones(self.1);
(left, Some(left))
}
}
/// The syntax used is `enum_set!(Type::A | Type::B | Type::C)`. Each variant must be of the same
/// type, or a error will occur at compile-time.
///
+/// This macro accepts trailing `|`s to allow easier use in other macros.
+///
/// # Examples
///
/// ```rust
/// ```
#[macro_export]
macro_rules! enum_set {
- () => {
+ ($(|)*) => {
$crate::EnumSet { __enumset_underlying: 0 }
};
- ($($value:path)|* $(|)*) => {
- $crate::internal::EnumSetSameTypeHack {
- unified: &[$($value,)*],
- enum_set: $crate::EnumSet {
- __enumset_underlying: 0 $(| (1 << ($value as u32)))*
- },
- }.enum_set
+ ($value:path $(|)*) => {
+ $value.__impl_enumset_internal__const_only()
+ };
+ ($value:path | $($rest:path)|* $(|)*) => {
+ {
+ #[allow(deprecated)] let value = $value.__impl_enumset_internal__const_only();
+ $(#[allow(deprecated)] let value = $rest.__impl_enumset_internal__const_merge(value);)*
+ value
+ }
};
}
projects / enumset.git / blobdiff