diff options
Diffstat (limited to 'third_party/rust/flagset/src')
| -rw-r--r-- | third_party/rust/flagset/src/lib.rs | 1286 |
1 files changed, 1286 insertions, 0 deletions
diff --git a/third_party/rust/flagset/src/lib.rs b/third_party/rust/flagset/src/lib.rs new file mode 100644 index 0000000000..220af6ba75 --- /dev/null +++ b/third_party/rust/flagset/src/lib.rs @@ -0,0 +1,1286 @@ +// +// Copyright 2019 Red Hat, Inc. +// +// Author: Nathaniel McCallum <npmccallum@redhat.com> +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. +// + +//! # Welcome to FlagSet! +//! +//! FlagSet is a new, ergonomic approach to handling flags that combines the +//! best of existing crates like `bitflags` and `enumflags` without their +//! downsides. +//! +//! ## Existing Implementations +//! +//! The `bitflags` crate has long been part of the Rust ecosystem. +//! Unfortunately, it doesn't feel like natural Rust. The `bitflags` crate +//! uses a wierd struct format to define flags. Flags themselves are just +//! integers constants, so there is little type-safety involved. But it doesn't +//! have any dependencies. It also allows you to define implied flags (otherwise +//! known as overlapping flags). +//! +//! The `enumflags` crate tried to improve on `bitflags` by using enumerations +//! to define flags. This was a big improvement to the natural feel of the code. +//! Unfortunately, there are some design flaws. To generate the flags, +//! procedural macros were used. This implied two separate crates plus +//! additional dependencies. Further, `enumflags` specifies the size of the +//! flags using a `repr($size)` attribute. Unfortunately, this attribute +//! cannot resolve type aliases, such as `c_int`. This makes `enumflags` a +//! poor fit for FFI, which is the most important place for a flags library. +//! The `enumflags` crate also disallows overlapping flags and is not +//! maintained. +//! +//! FlagSet improves on both of these by adopting the `enumflags` natural feel +//! and the `bitflags` mode of flag generation; as well as additional API usage +//! niceties. FlagSet has no dependencies and is extensively documented and +//! tested. It also tries very hard to prevent you from making mistakes by +//! avoiding external usage of the integer types. FlagSet is also a zero-cost +//! abstraction: all functions are inlineable and should reduce to the core +//! integer operations. FlagSet also does not depend on stdlib, so it can be +//! used in `no_std` libraries and applications. +//! +//! ## Defining Flags +//! +//! Flags are defined using the `flags!` macro: +//! +//! ``` +//! use flagset::{FlagSet, flags}; +//! use std::os::raw::c_int; +//! +//! flags! { +//! enum FlagsA: u8 { +//! Foo, +//! Bar, +//! Baz, +//! } +//! +//! enum FlagsB: c_int { +//! Foo, +//! Bar, +//! Baz, +//! } +//! } +//! ``` +//! +//! Notice that a flag definition looks just like a regular enumeration, with +//! the addition of the field-size type. The field-size type is required and +//! can be either a type or a type alias. Both examples are given above. +//! +//! Also note that the field-size type specifies the size of the corresponding +//! `FlagSet` type, not size of the enumeration itself. To specify the size of +//! the enumeration, use the `repr($size)` attribute as specified below. +//! +//! ## Flag Values +//! +//! Flags often need values assigned to them. This can be done implicitly, +//! where the value depends on the order of the flags: +//! +//! ``` +//! use flagset::{FlagSet, flags}; +//! +//! flags! { +//! enum Flags: u16 { +//! Foo, // Implicit Value: 0b0001 +//! Bar, // Implicit Value: 0b0010 +//! Baz, // Implicit Value: 0b0100 +//! } +//! } +//! ``` +//! +//! Alternatively, flag values can be defined explicitly, by specifying any +//! `const` expression: +//! +//! ``` +//! use flagset::{FlagSet, flags}; +//! +//! flags! { +//! enum Flags: u16 { +//! Foo = 0x01, // Explicit Value: 0b0001 +//! Bar = 2, // Explicit Value: 0b0010 +//! Baz = 0b0100, // Explicit Value: 0b0100 +//! } +//! } +//! ``` +//! +//! Flags can also overlap or "imply" other flags: +//! +//! ``` +//! use flagset::{FlagSet, flags}; +//! +//! flags! { +//! enum Flags: u16 { +//! Foo = 0b0001, +//! Bar = 0b0010, +//! Baz = 0b0110, // Implies Bar +//! All = (Flags::Foo | Flags::Bar | Flags::Baz).bits(), +//! } +//! } +//! ``` +//! +//! ## Specifying Attributes +//! +//! Attributes can be used on the enumeration itself or any of the values: +//! +//! ``` +//! use flagset::{FlagSet, flags}; +//! +//! flags! { +//! #[derive(PartialOrd, Ord)] +//! enum Flags: u8 { +//! Foo, +//! #[deprecated] +//! Bar, +//! Baz, +//! } +//! } +//! ``` +//! +//! ## Collections of Flags +//! +//! A collection of flags is a `FlagSet<T>`. If you are storing the flags in +//! memory, the raw `FlagSet<T>` type should be used. However, if you want to +//! receive flags as an input to a function, you should use +//! `impl Into<FlagSet<T>>`. This allows for very ergonomic APIs: +//! +//! ``` +//! use flagset::{FlagSet, flags}; +//! +//! flags! { +//! enum Flags: u8 { +//! Foo, +//! Bar, +//! Baz, +//! } +//! } +//! +//! struct Container(FlagSet<Flags>); +//! +//! impl Container { +//! fn new(flags: impl Into<FlagSet<Flags>>) -> Container { +//! Container(flags.into()) +//! } +//! } +//! +//! assert_eq!(Container::new(Flags::Foo | Flags::Bar).0.bits(), 0b011); +//! assert_eq!(Container::new(Flags::Foo).0.bits(), 0b001); +//! assert_eq!(Container::new(None).0.bits(), 0b000); +//! ``` +//! +//! ## Operations +//! +//! Operations can be performed on a `FlagSet<F>` or on individual flags: +//! +//! | Operator | Assignment Operator | Meaning | +//! |----------|---------------------|------------------------| +//! | \| | \|= | Union | +//! | & | &= | Intersection | +//! | ^ | ^= | Toggle specified flags | +//! | - | -= | Difference | +//! | % | %= | Symmetric difference | +//! | ! | | Toggle all flags | +//! +#![cfg_attr( + feature = "serde", + doc = r#" + +## Optional Serde support + +[Serde] support can be enabled with the 'serde' feature flag. You can then serialize and +deserialize `FlagSet<T>` to and from any of the [supported formats]: + + ``` + use flagset::{FlagSet, flags}; + + flags! { + enum Flags: u8 { + Foo, + Bar, + } + } + + let flagset = Flags::Foo | Flags::Bar; + let json = serde_json::to_string(&flagset).unwrap(); + let flagset: FlagSet<Flags> = serde_json::from_str(&json).unwrap(); + assert_eq!(flagset.bits(), 0b011); + ``` + +For serialization and deserialization of flags enum itself, you can use the [`serde_repr`] crate +(or implement `serde::ser::Serialize` and `serde:de::Deserialize` manually), combined with the +appropriate `repr` attribute: + + ``` + use flagset::{FlagSet, flags}; + use serde_repr::{Serialize_repr, Deserialize_repr}; + + flags! { + #[repr(u8)] + #[derive(Deserialize_repr, Serialize_repr)] + enum Flags: u8 { + Foo, + Bar, + } + } + + let json = serde_json::to_string(&Flags::Foo).unwrap(); + let flag: Flags = serde_json::from_str(&json).unwrap(); + assert_eq!(flag, Flags::Foo); + ``` + +[Serde]: https://serde.rs/ +[supported formats]: https://serde.rs/#data-formats +[`serde_repr`]: https://crates.io/crates/serde_repr +"# +)] +#![allow(unknown_lints)] +#![warn(clippy::all)] +#![no_std] + +use core::fmt::{Debug, Formatter, Result}; +use core::ops::*; + +/// Error type returned when creating a new flagset from bits is invalid or undefined. +/// ``` +/// use flagset::{FlagSet, flags}; +/// +/// flags! { +/// pub enum Flag: u16 { +/// Foo = 0b0001, +/// Bar = 0b0010, +/// Baz = 0b0100, +/// Qux = 0b1010, // Implies Bar +/// } +/// } +/// +/// assert_eq!(FlagSet::<Flag>::new(0b01101), Err(flagset::InvalidBits)); // Invalid +/// assert_eq!(FlagSet::<Flag>::new(0b10101), Err(flagset::InvalidBits)); // Unknown +/// ``` +#[derive(Clone, Copy, Debug, Eq, PartialEq)] +pub struct InvalidBits; + +impl core::fmt::Display for InvalidBits { + #[inline] + fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result { + write!(f, "invalid bits") + } +} + +#[doc(hidden)] +pub trait Flags: + Copy + + Clone + + Debug + + PartialEq + + Eq + + BitAnd<Self, Output = FlagSet<Self>> + + BitOr<Self, Output = FlagSet<Self>> + + BitXor<Self, Output = FlagSet<Self>> + + Sub<Self, Output = FlagSet<Self>> + + Rem<Self, Output = FlagSet<Self>> + + Not<Output = FlagSet<Self>> + + Into<FlagSet<Self>> + + 'static +{ + type Type: Copy + + Clone + + Debug + + PartialEq + + Eq + + Default + + BitAnd<Self::Type, Output = Self::Type> + + BitAndAssign<Self::Type> + + BitOr<Self::Type, Output = Self::Type> + + BitOrAssign<Self::Type> + + BitXor<Self::Type, Output = Self::Type> + + BitXorAssign<Self::Type> + + Not<Output = Self::Type>; + + /// A slice containing all the possible flag values. + const LIST: &'static [Self]; + + /// Creates an empty `FlagSet` of this type + #[inline] + fn none() -> FlagSet<Self> { + FlagSet::default() + } +} + +#[derive(Copy, Clone, Eq)] +pub struct FlagSet<F: Flags>(F::Type); + +#[doc(hidden)] +#[derive(Copy, Clone)] +pub struct Iter<F: Flags>(FlagSet<F>, usize); + +impl<F: Flags> Iterator for Iter<F> { + type Item = F; + + #[inline] + fn next(&mut self) -> Option<Self::Item> { + while self.1 < F::LIST.len() { + let next = F::LIST[self.1]; + self.1 += 1; + + if self.0.contains(next) { + return Some(next); + } + } + + None + } +} + +impl<F: Flags> IntoIterator for FlagSet<F> { + type Item = F; + type IntoIter = Iter<F>; + + /// Iterate over the flags in the set. + /// + /// **NOTE**: The order in which the flags are iterated is undefined. + /// + /// ``` + /// use flagset::{FlagSet, flags}; + /// + /// flags! { + /// enum Flag: u8 { + /// Foo = 0b001, + /// Bar = 0b010, + /// Baz = 0b100 + /// } + /// } + /// + /// let set = Flag::Foo | Flag::Bar; + /// let mut iter = set.into_iter(); + /// assert_eq!(iter.next(), Some(Flag::Foo)); + /// assert_eq!(iter.next(), Some(Flag::Bar)); + /// assert_eq!(iter.next(), None); + /// ``` + #[inline] + fn into_iter(self) -> Self::IntoIter { + Iter(self, 0) + } +} + +impl<F: Flags> Debug for FlagSet<F> { + #[inline] + fn fmt(&self, f: &mut Formatter) -> Result { + write!(f, "FlagSet(")?; + for (i, flag) in self.into_iter().enumerate() { + write!(f, "{}{:?}", if i > 0 { " | " } else { "" }, flag)?; + } + write!(f, ")") + } +} + +impl<F: Flags, R: Copy + Into<FlagSet<F>>> PartialEq<R> for FlagSet<F> { + #[inline] + fn eq(&self, rhs: &R) -> bool { + self.0 == (*rhs).into().0 + } +} + +impl<F: Flags> AsRef<F::Type> for FlagSet<F> { + #[inline] + fn as_ref(&self) -> &F::Type { + &self.0 + } +} + +impl<F: Flags> From<Option<FlagSet<F>>> for FlagSet<F> { + /// Converts from `Option<FlagSet<F>>` to `FlagSet<F>`. + /// + /// Most notably, this allows for the use of `None` in many places to + /// substitute for manually creating an empty `FlagSet<F>`. See below. + /// + /// ``` + /// use flagset::{FlagSet, flags}; + /// + /// flags! { + /// enum Flag: u8 { + /// Foo = 0b001, + /// Bar = 0b010, + /// Baz = 0b100 + /// } + /// } + /// + /// fn convert(v: impl Into<FlagSet<Flag>>) -> u8 { + /// v.into().bits() + /// } + /// + /// assert_eq!(convert(Flag::Foo | Flag::Bar), 0b011); + /// assert_eq!(convert(Flag::Foo), 0b001); + /// assert_eq!(convert(None), 0b000); + /// ``` + #[inline] + fn from(value: Option<FlagSet<F>>) -> FlagSet<F> { + value.unwrap_or_default() + } +} + +impl<F: Flags> Default for FlagSet<F> { + /// Creates a new, empty FlagSet. + /// + /// ``` + /// use flagset::{FlagSet, flags}; + /// + /// flags! { + /// enum Flag: u8 { + /// Foo = 0b001, + /// Bar = 0b010, + /// Baz = 0b100 + /// } + /// } + /// + /// let set = FlagSet::<Flag>::default(); + /// assert!(set.is_empty()); + /// assert!(!set.is_full()); + /// assert!(!set.contains(Flag::Foo)); + /// assert!(!set.contains(Flag::Bar)); + /// assert!(!set.contains(Flag::Baz)); + /// ``` + #[inline] + fn default() -> Self { + FlagSet(F::Type::default()) + } +} + +impl<F: Flags> Not for FlagSet<F> { + type Output = Self; + + /// Calculates the complement of the current set. + /// + /// In common parlance, this returns the set of all possible flags that are + /// not in the current set. + /// + /// ``` + /// use flagset::{FlagSet, flags}; + /// + /// flags! { + /// #[derive(PartialOrd, Ord)] + /// enum Flag: u8 { + /// Foo = 1 << 0, + /// Bar = 1 << 1, + /// Baz = 1 << 2 + /// } + /// } + /// + /// let set = !FlagSet::from(Flag::Foo); + /// assert!(!set.is_empty()); + /// assert!(!set.is_full()); + /// assert!(!set.contains(Flag::Foo)); + /// assert!(set.contains(Flag::Bar)); + /// assert!(set.contains(Flag::Baz)); + /// ``` + #[inline] + fn not(self) -> Self { + FlagSet(!self.0) + } +} + +impl<F: Flags, R: Into<FlagSet<F>>> BitAnd<R> for FlagSet<F> { + type Output = Self; + + /// Calculates the intersection of the current set and the specified flags. + /// + /// ``` + /// use flagset::{FlagSet, flags}; + /// + /// flags! { + /// #[derive(PartialOrd, Ord)] + /// pub enum Flag: u8 { + /// Foo = 0b001, + /// Bar = 0b010, + /// Baz = 0b100 + /// } + /// } + /// + /// let set0 = Flag::Foo | Flag::Bar; + /// let set1 = Flag::Baz | Flag::Bar; + /// assert_eq!(set0 & set1, Flag::Bar); + /// assert_eq!(set0 & Flag::Foo, Flag::Foo); + /// assert_eq!(set1 & Flag::Baz, Flag::Baz); + /// ``` + #[inline] + fn bitand(self, rhs: R) -> Self { + FlagSet(self.0 & rhs.into().0) + } +} + +impl<F: Flags, R: Into<FlagSet<F>>> BitAndAssign<R> for FlagSet<F> { + /// Assigns the intersection of the current set and the specified flags. + /// + /// ``` + /// use flagset::{FlagSet, flags}; + /// + /// flags! { + /// enum Flag: u64 { + /// Foo = 0b001, + /// Bar = 0b010, + /// Baz = 0b100 + /// } + /// } + /// + /// let mut set0 = Flag::Foo | Flag::Bar; + /// let mut set1 = Flag::Baz | Flag::Bar; + /// + /// set0 &= set1; + /// assert_eq!(set0, Flag::Bar); + /// + /// set1 &= Flag::Baz; + /// assert_eq!(set0, Flag::Bar); + /// ``` + #[inline] + fn bitand_assign(&mut self, rhs: R) { + self.0 &= rhs.into().0 + } +} + +impl<F: Flags, R: Into<FlagSet<F>>> BitOr<R> for FlagSet<F> { + type Output = Self; + + /// Calculates the union of the current set with the specified flags. + /// + /// ``` + /// use flagset::{FlagSet, flags}; + /// + /// flags! { + /// #[derive(PartialOrd, Ord)] + /// pub enum Flag: u8 { + /// Foo = 0b001, + /// Bar = 0b010, + /// Baz = 0b100 + /// } + /// } + /// + /// let set0 = Flag::Foo | Flag::Bar; + /// let set1 = Flag::Baz | Flag::Bar; + /// assert_eq!(set0 | set1, FlagSet::full()); + /// ``` + #[inline] + fn bitor(self, rhs: R) -> Self { + FlagSet(self.0 | rhs.into().0) + } +} + +impl<F: Flags, R: Into<FlagSet<F>>> BitOrAssign<R> for FlagSet<F> { + /// Assigns the union of the current set with the specified flags. + /// + /// ``` + /// use flagset::{FlagSet, flags}; + /// + /// flags! { + /// enum Flag: u64 { + /// Foo = 0b001, + /// Bar = 0b010, + /// Baz = 0b100 + /// } + /// } + /// + /// let mut set0 = Flag::Foo | Flag::Bar; + /// let mut set1 = Flag::Bar | Flag::Baz; + /// + /// set0 |= set1; + /// assert_eq!(set0, FlagSet::full()); + /// + /// set1 |= Flag::Baz; + /// assert_eq!(set1, Flag::Bar | Flag::Baz); + /// ``` + #[inline] + fn bitor_assign(&mut self, rhs: R) { + self.0 |= rhs.into().0 + } +} + +impl<F: Flags, R: Into<FlagSet<F>>> BitXor<R> for FlagSet<F> { + type Output = Self; + + /// Calculates the current set with the specified flags toggled. + /// + /// This is commonly known as toggling the presence + /// + /// ``` + /// use flagset::{FlagSet, flags}; + /// + /// flags! { + /// enum Flag: u32 { + /// Foo = 0b001, + /// Bar = 0b010, + /// Baz = 0b100 + /// } + /// } + /// + /// let set0 = Flag::Foo | Flag::Bar; + /// let set1 = Flag::Baz | Flag::Bar; + /// assert_eq!(set0 ^ set1, Flag::Foo | Flag::Baz); + /// assert_eq!(set0 ^ Flag::Foo, Flag::Bar); + /// ``` + #[inline] + fn bitxor(self, rhs: R) -> Self { + FlagSet(self.0 ^ rhs.into().0) + } +} + +impl<F: Flags, R: Into<FlagSet<F>>> BitXorAssign<R> for FlagSet<F> { + /// Assigns the current set with the specified flags toggled. + /// + /// ``` + /// use flagset::{FlagSet, flags}; + /// + /// flags! { + /// enum Flag: u16 { + /// Foo = 0b001, + /// Bar = 0b010, + /// Baz = 0b100 + /// } + /// } + /// + /// let mut set0 = Flag::Foo | Flag::Bar; + /// let mut set1 = Flag::Baz | Flag::Bar; + /// + /// set0 ^= set1; + /// assert_eq!(set0, Flag::Foo | Flag::Baz); + /// + /// set1 ^= Flag::Baz; + /// assert_eq!(set1, Flag::Bar); + /// ``` + #[inline] + fn bitxor_assign(&mut self, rhs: R) { + self.0 ^= rhs.into().0 + } +} + +impl<F: Flags, R: Into<FlagSet<F>>> Sub<R> for FlagSet<F> { + type Output = Self; + + /// Calculates set difference (the current set without the specified flags). + /// + /// ``` + /// use flagset::{FlagSet, flags}; + /// + /// flags! { + /// pub enum Flag: u8 { + /// Foo = 1, + /// Bar = 2, + /// Baz = 4 + /// } + /// } + /// + /// let set0 = Flag::Foo | Flag::Bar; + /// let set1 = Flag::Baz | Flag::Bar; + /// assert_eq!(set0 - set1, Flag::Foo); + /// ``` + #[inline] + fn sub(self, rhs: R) -> Self { + self & !rhs.into() + } +} + +impl<F: Flags, R: Into<FlagSet<F>>> SubAssign<R> for FlagSet<F> { + /// Assigns set difference (the current set without the specified flags). + /// + /// ``` + /// use flagset::{FlagSet, flags}; + /// + /// flags! { + /// pub enum Flag: u8 { + /// Foo = 1, + /// Bar = 2, + /// Baz = 4 + /// } + /// } + /// + /// let mut set0 = Flag::Foo | Flag::Bar; + /// set0 -= Flag::Baz | Flag::Bar; + /// assert_eq!(set0, Flag::Foo); + /// ``` + #[inline] + fn sub_assign(&mut self, rhs: R) { + *self &= !rhs.into(); + } +} + +impl<F: Flags, R: Into<FlagSet<F>>> Rem<R> for FlagSet<F> { + type Output = Self; + + /// Calculates the symmetric difference between two sets. + /// + /// The symmetric difference between two sets is the set of all flags + /// that appear in one set or the other, but not both. + /// + /// ``` + /// use flagset::{FlagSet, flags}; + /// + /// flags! { + /// pub enum Flag: u8 { + /// Foo = 1, + /// Bar = 2, + /// Baz = 4 + /// } + /// } + /// + /// let set0 = Flag::Foo | Flag::Bar; + /// let set1 = Flag::Baz | Flag::Bar; + /// assert_eq!(set0 % set1, Flag::Foo | Flag::Baz); + /// ``` + #[inline] + fn rem(self, rhs: R) -> Self { + let rhs = rhs.into(); + (self - rhs) | (rhs - self) + } +} + +impl<F: Flags, R: Into<FlagSet<F>>> RemAssign<R> for FlagSet<F> { + /// Assigns the symmetric difference between two sets. + /// + /// The symmetric difference between two sets is the set of all flags + /// that appear in one set or the other, but not both. + /// + /// ``` + /// use flagset::{FlagSet, flags}; + /// + /// flags! { + /// pub enum Flag: u8 { + /// Foo = 1, + /// Bar = 2, + /// Baz = 4 + /// } + /// } + /// + /// let mut set0 = Flag::Foo | Flag::Bar; + /// let set1 = Flag::Baz | Flag::Bar; + /// set0 %= set1; + /// assert_eq!(set0, Flag::Foo | Flag::Baz); + /// ``` + #[inline] + fn rem_assign(&mut self, rhs: R) { + *self = *self % rhs + } +} + +impl<F: Flags> FlagSet<F> { + /// Creates a new set from bits; returning `Err(InvalidBits)` on invalid/unknown bits. + /// + /// ``` + /// use flagset::{FlagSet, flags}; + /// + /// flags! { + /// pub enum Flag: u16 { + /// Foo = 0b0001, + /// Bar = 0b0010, + /// Baz = 0b0100, + /// Qux = 0b1010, // Implies Bar + /// } + /// } + /// + /// assert_eq!(FlagSet::<Flag>::new(0b00101), Ok(Flag::Foo | Flag::Baz)); + /// assert_eq!(FlagSet::<Flag>::new(0b01101), Err(flagset::InvalidBits)); // Invalid + /// assert_eq!(FlagSet::<Flag>::new(0b10101), Err(flagset::InvalidBits)); // Unknown + /// ``` + #[inline] + pub fn new(bits: F::Type) -> core::result::Result<Self, InvalidBits> { + if Self::new_truncated(bits).0 == bits { + return Ok(FlagSet(bits)); + } + + Err(InvalidBits) + } + + /// Creates a new set from bits; truncating invalid/unknown bits. + /// + /// ``` + /// use flagset::{FlagSet, flags}; + /// + /// flags! { + /// pub enum Flag: u16 { + /// Foo = 0b0001, + /// Bar = 0b0010, + /// Baz = 0b0100, + /// Qux = 0b1010, // Implies Bar + /// } + /// } + /// + /// let set = FlagSet::new_truncated(0b11101); // Has invalid and unknown. + /// assert_eq!(set, Flag::Foo | Flag::Baz); + /// assert_eq!(set.bits(), 0b00101); // Has neither. + /// ``` + #[inline] + pub fn new_truncated(bits: F::Type) -> Self { + let mut set = Self::default(); + + for flag in FlagSet::<F>(bits) { + set |= flag; + } + + set + } + + /// Creates a new set from bits; use of invalid/unknown bits is undefined. + /// + /// ``` + /// use flagset::{FlagSet, flags}; + /// + /// flags! { + /// pub enum Flag: u16 { + /// Foo = 0b0001, + /// Bar = 0b0010, + /// Baz = 0b0100, + /// Qux = 0b1010, // Implies Bar + /// } + /// } + /// + /// // Unknown and invalid bits are retained. Behavior is undefined. + /// let set = unsafe { FlagSet::<Flag>::new_unchecked(0b11101) }; + /// assert_eq!(set.bits(), 0b11101); + /// ``` + /// + /// # Safety + /// + /// This constructor doesn't check that the bits are valid. If you pass + /// undefined flags, undefined behavior may result. + #[inline] + pub unsafe fn new_unchecked(bits: F::Type) -> Self { + FlagSet(bits) + } + + /// Creates a new FlagSet containing all possible flags. + /// + /// ``` + /// use flagset::{FlagSet, flags}; + /// + /// flags! { + /// pub enum Flag: u8 { + /// Foo = 1, + /// Bar = 2, + /// Baz = 4 + /// } + /// } + /// + /// let set = FlagSet::full(); + /// assert!(!set.is_empty()); + /// assert!(set.is_full()); + /// assert!(set.contains(Flag::Foo)); + /// assert!(set.contains(Flag::Bar)); + /// assert!(set.contains(Flag::Baz)); + /// ``` + #[inline] + pub fn full() -> Self { + let mut set = Self::default(); + for f in F::LIST { + set |= *f + } + set + } + + /// Returns the raw bits of the set. + /// + /// ``` + /// use flagset::{FlagSet, flags}; + /// + /// flags! { + /// pub enum Flag: u16 { + /// Foo = 0b0001, + /// Bar = 0b0010, + /// Baz = 0b0100, + /// } + /// } + /// + /// let set = Flag::Foo | Flag::Baz; + /// assert_eq!(set.bits(), 0b0101u16); + /// ``` + #[inline] + pub fn bits(self) -> F::Type { + self.0 + } + + /// Returns true if the FlagSet contains no flags. + /// + /// ``` + /// use flagset::{FlagSet, flags}; + /// + /// flags! { + /// pub enum Flag: u8 { + /// Foo = 1, + /// Bar = 2, + /// Baz = 4 + /// } + /// } + /// + /// let mut set = Flag::Foo | Flag::Bar; + /// assert!(!set.is_empty()); + /// + /// set &= Flag::Baz; + /// assert!(set.is_empty()); + /// ``` + #[inline] + pub fn is_empty(self) -> bool { + self == Self::default() + } + + /// Returns true if the FlagSet contains all possible flags. + /// + /// ``` + /// use flagset::{FlagSet, flags}; + /// + /// flags! { + /// pub enum Flag: u8 { + /// Foo = 1, + /// Bar = 2, + /// Baz = 4 + /// } + /// } + /// + /// let mut set = Flag::Foo | Flag::Bar; + /// assert!(!set.is_full()); + /// + /// set |= Flag::Baz; + /// assert!(set.is_full()); + /// ``` + #[inline] + pub fn is_full(self) -> bool { + self == Self::full() + } + + /// Returns true if the two `FlagSet`s do not share any flags. + /// + /// ``` + /// use flagset::{FlagSet, flags}; + /// + /// flags! { + /// pub enum Flag: u8 { + /// Foo = 1, + /// Bar = 2, + /// Baz = 4 + /// } + /// } + /// + /// let set = Flag::Foo | Flag::Bar; + /// assert!(!set.is_disjoint(Flag::Foo)); + /// assert!(!set.is_disjoint(Flag::Foo | Flag::Baz)); + /// assert!(set.is_disjoint(Flag::Baz)); + /// ``` + #[inline] + pub fn is_disjoint(self, rhs: impl Into<FlagSet<F>>) -> bool { + self & rhs == Self::default() + } + + /// Returns true if this FlagSet is a superset of the specified flags. + /// + /// ``` + /// use flagset::{FlagSet, flags}; + /// + /// flags! { + /// pub enum Flag: u8 { + /// Foo = 1, + /// Bar = 2, + /// Baz = 4 + /// } + /// } + /// + /// let set = Flag::Foo | Flag::Bar; + /// assert!(set.contains(Flag::Foo)); + /// assert!(set.contains(Flag::Foo | Flag::Bar)); + /// assert!(!set.contains(Flag::Foo | Flag::Bar | Flag::Baz)); + /// ``` + #[inline] + pub fn contains(self, rhs: impl Into<FlagSet<F>>) -> bool { + let rhs = rhs.into(); + self & rhs == rhs + } + + /// Removes all flags from the FlagSet. + /// + /// ``` + /// use flagset::{FlagSet, flags}; + /// + /// flags! { + /// pub enum Flag: u8 { + /// Foo = 1, + /// Bar = 2, + /// Baz = 4 + /// } + /// } + /// + /// let mut set = Flag::Foo | Flag::Bar; + /// assert!(!set.is_empty()); + /// + /// set.clear(); + /// assert!(set.is_empty()); + /// ``` + #[inline] + pub fn clear(&mut self) { + *self = Self::default(); + } + + /// Clears the current set and returns an iterator of all removed flags. + /// + /// ``` + /// use flagset::{FlagSet, flags}; + /// + /// flags! { + /// pub enum Flag: u8 { + /// Foo = 1, + /// Bar = 2, + /// Baz = 4 + /// } + /// } + /// + /// let mut set = Flag::Foo | Flag::Bar; + /// let mut iter = set.drain(); + /// assert!(set.is_empty()); + /// assert_eq!(iter.next(), Some(Flag::Foo)); + /// assert_eq!(iter.next(), Some(Flag::Bar)); + /// assert_eq!(iter.next(), None); + /// ``` + #[inline] + pub fn drain(&mut self) -> Iter<F> { + let iter = self.into_iter(); + *self = Self::default(); + iter + } + + /// Retain only the flags flags specified by the predicate. + /// + /// ``` + /// use flagset::{FlagSet, flags}; + /// + /// flags! { + /// pub enum Flag: u8 { + /// Foo = 1, + /// Bar = 2, + /// Baz = 4 + /// } + /// } + /// + /// let mut set0 = Flag::Foo | Flag::Bar; + /// set0.retain(|f| f != Flag::Foo); + /// assert_eq!(set0, Flag::Bar); + /// ``` + #[inline] + pub fn retain(&mut self, func: impl Fn(F) -> bool) { + for f in self.into_iter() { + if !func(f) { + *self -= f + } + } + } +} + +#[cfg(feature = "serde")] +impl<F: Flags> serde::Serialize for FlagSet<F> +where + F::Type: serde::ser::Serialize, +{ + #[inline] + fn serialize<S>(&self, serializer: S) -> core::result::Result<S::Ok, S::Error> + where + S: serde::ser::Serializer, + { + self.0.serialize(serializer) + } +} + +#[cfg(feature = "serde")] +impl<'de, F: Flags> serde::Deserialize<'de> for FlagSet<F> +where + F::Type: serde::de::Deserialize<'de>, +{ + #[inline] + fn deserialize<D>(deserializer: D) -> core::result::Result<Self, D::Error> + where + D: serde::de::Deserializer<'de>, + { + Ok(FlagSet(F::Type::deserialize(deserializer)?)) + } +} + +/// Define flag value using the `enum` syntax. See below for details. +/// +/// Each enumeration value **MUST** have a specified value. +/// +/// The width of the bitfield **MUST** also be specified by its integer type. +/// +/// It is important to note that the size of the flag enumeration itself is +/// unrelated to the size of the corresponding `FlagSet` instance. +/// +/// It is also worth noting that this macro automatically implements a variety +/// of standard traits including: +/// * Copy +/// * Clone +/// * Debug +/// * PartialEq +/// * Eq +/// * From<$enum> for $integer +/// * Not +/// * BitAnd +/// * BitOr +/// * BitXor +/// * Sub +/// * Rem +/// +/// ``` +/// use std::mem::{align_of, size_of}; +/// use flagset::{FlagSet, flags}; +/// +/// flags! { +/// enum FlagEmpty: u32 {} +/// +/// enum Flag8: u8 { +/// Foo = 0b001, +/// Bar = 0b010, +/// Baz = 0b100 +/// } +/// +/// pub enum Flag16: u16 { +/// Foo, +/// Bar, +/// #[deprecated] +/// Baz, +/// } +/// +/// #[derive(PartialOrd, Ord)] +/// enum Flag32: u32 { +/// Foo = 0b001, +/// #[deprecated] +/// Bar = 0b010, +/// Baz = 0b100 +/// } +/// +/// #[repr(u64)] +/// enum Flag64: u64 { +/// Foo = 0b001, +/// Bar = 0b010, +/// Baz = 0b100 +/// } +/// +/// #[repr(u32)] +/// enum Flag128: u128 { +/// Foo = 0b001, +/// Bar = 0b010, +/// Baz = 0b100 +/// } +/// } +/// +/// assert_eq!(size_of::<Flag8>(), 1); +/// assert_eq!(size_of::<Flag16>(), 1); +/// assert_eq!(size_of::<Flag32>(), 1); +/// assert_eq!(size_of::<Flag64>(), 8); +/// assert_eq!(size_of::<Flag128>(), 4); +/// +/// assert_eq!(align_of::<Flag8>(), 1); +/// assert_eq!(align_of::<Flag16>(), 1); +/// assert_eq!(align_of::<Flag32>(), 1); +/// assert_eq!(align_of::<Flag64>(), align_of::<u64>()); +/// assert_eq!(align_of::<Flag128>(), align_of::<u32>()); +/// +/// assert_eq!(size_of::<FlagSet<Flag8>>(), size_of::<u8>()); +/// assert_eq!(size_of::<FlagSet<Flag16>>(), size_of::<u16>()); +/// assert_eq!(size_of::<FlagSet<Flag32>>(), size_of::<u32>()); +/// assert_eq!(size_of::<FlagSet<Flag64>>(), size_of::<u64>()); +/// assert_eq!(size_of::<FlagSet<Flag128>>(), size_of::<u128>()); +/// +/// assert_eq!(align_of::<FlagSet<Flag8>>(), align_of::<u8>()); +/// assert_eq!(align_of::<FlagSet<Flag16>>(), align_of::<u16>()); +/// assert_eq!(align_of::<FlagSet<Flag32>>(), align_of::<u32>()); +/// assert_eq!(align_of::<FlagSet<Flag64>>(), align_of::<u64>()); +/// assert_eq!(align_of::<FlagSet<Flag128>>(), align_of::<u128>()); +/// ``` +#[macro_export] +macro_rules! flags { + () => {}; + + // Entry point for enumerations without values. + ($(#[$m:meta])* $p:vis enum $n:ident: $t:ty { $($(#[$a:meta])* $k:ident),+ $(,)* } $($next:tt)*) => { + $crate::flags! { $(#[$m])* $p enum $n: $t { $($(#[$a])* $k = (1 << $n::$k as $t)),+ } $($next)* } + }; + + // Entrypoint for enumerations with values. + ($(#[$m:meta])* $p:vis enum $n:ident: $t:ty { $($(#[$a:meta])*$k:ident = $v:expr),* $(,)* } $($next:tt)*) => { + $(#[$m])* + #[derive(Copy, Clone, Debug, PartialEq, Eq)] + $p enum $n { $($(#[$a])* $k),* } + + impl $crate::Flags for $n { + type Type = $t; + + const LIST: &'static [Self] = &[$($n::$k),*]; + } + + impl core::convert::From<$n> for $crate::FlagSet<$n> { + #[inline] + fn from(value: $n) -> Self { + unsafe { + match value { + $($n::$k => Self::new_unchecked($v)),* + } + } + } + } + + impl core::ops::Not for $n { + type Output = $crate::FlagSet<$n>; + + #[inline] + fn not(self) -> Self::Output { + !$crate::FlagSet::from(self) + } + } + + impl<R: core::convert::Into<$crate::FlagSet<$n>>> core::ops::BitAnd<R> for $n { + type Output = $crate::FlagSet<$n>; + + #[inline] + fn bitand(self, rhs: R) -> Self::Output { + $crate::FlagSet::from(self) & rhs + } + } + + impl<R: core::convert::Into<$crate::FlagSet<$n>>> core::ops::BitOr<R> for $n { + type Output = $crate::FlagSet<$n>; + + #[inline] + fn bitor(self, rhs: R) -> Self::Output { + $crate::FlagSet::from(self) | rhs + } + } + + impl<R: core::convert::Into<$crate::FlagSet<$n>>> core::ops::BitXor<R> for $n { + type Output = $crate::FlagSet<$n>; + + #[inline] + fn bitxor(self, rhs: R) -> Self::Output { + $crate::FlagSet::from(self) ^ rhs + } + } + + impl<R: core::convert::Into<$crate::FlagSet<$n>>> core::ops::Sub<R> for $n { + type Output = $crate::FlagSet<$n>; + + #[inline] + fn sub(self, rhs: R) -> Self::Output { + $crate::FlagSet::from(self) - rhs + } + } + + impl<R: core::convert::Into<$crate::FlagSet<$n>>> core::ops::Rem<R> for $n { + type Output = $crate::FlagSet<$n>; + + #[inline] + fn rem(self, rhs: R) -> Self::Output { + $crate::FlagSet::from(self) % rhs + } + } + + $crate::flags! { $($next)* } + }; +} |