Struct flagset::FlagSet

#[repr(C)]
pub struct FlagSet<F: Flags>(/* private fields */);

Implementations

impl<F: Flags> FlagSet<F>

pub fn new(bits: F::Type) -> Result<Self, InvalidBits>

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

pub fn new_truncated(bits: F::Type) -> Self

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.

pub const unsafe fn new_unchecked(bits: F::Type) -> Self

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.
const set: FlagSet<Flag> = 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.

pub fn full() -> Self

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

pub fn bits(self) -> F::Type

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

pub fn is_empty(self) -> bool

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());

pub fn is_full(self) -> bool

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());

pub fn is_disjoint(self, rhs: impl Into<FlagSet<F>>) -> bool

Returns true if the two FlagSets 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));

pub fn contains(self, rhs: impl Into<FlagSet<F>>) -> bool

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

pub fn clear(&mut self)

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());

pub fn drain(&mut self) -> Iter<F>

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

pub fn retain(&mut self, func: impl Fn(F) -> bool)

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

Trait Implementations

impl<F: Flags> AsRef<<F as Flags>::Type> for FlagSet<F>

fn as_ref(&self) -> &F::Type

Converts this type into a shared reference of the (usually inferred) input type.

impl<F: Flags, R: Into<FlagSet<F>>> BitAnd<R> for FlagSet<F>

fn bitand(self, rhs: R) -> 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);

type Output = FlagSet<F>

The resulting type after applying the & operator.

impl<F: Flags, R: Into<FlagSet<F>>> BitAndAssign<R> for FlagSet<F>

fn bitand_assign(&mut self, rhs: R)

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

impl<F: Flags, R: Into<FlagSet<F>>> BitOr<R> for FlagSet<F>

fn bitor(self, rhs: R) -> 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());

type Output = FlagSet<F>

The resulting type after applying the | operator.

impl<F: Flags, R: Into<FlagSet<F>>> BitOrAssign<R> for FlagSet<F>

fn bitor_assign(&mut self, rhs: R)

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

impl<F: Flags, R: Into<FlagSet<F>>> BitXor<R> for FlagSet<F>

fn bitxor(self, rhs: R) -> 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);

type Output = FlagSet<F>

The resulting type after applying the ^ operator.

impl<F: Flags, R: Into<FlagSet<F>>> BitXorAssign<R> for FlagSet<F>

fn bitxor_assign(&mut self, rhs: R)

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

impl<F: Clone + Flags> Clone for FlagSet<F>

where F::Type: Clone,

fn clone(&self) -> FlagSet<F>

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<F: Flags> Debug for FlagSet<F>

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

Formats the value using the given formatter.

impl<F: Flags> Default for FlagSet<F>

fn default() -> Self

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

impl<'de, F: Flags> Deserialize<'de> for FlagSet<F>

where F::Type: Deserialize<'de>,

Available on crate feature serde only.

fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>

where D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl<F: Flags, R: Into<FlagSet<F>>> Extend<R> for FlagSet<F>

fn extend<T>(&mut self, iter: T)

where T: IntoIterator<Item = R>,

Add values by iterating over some collection.

use flagset::{FlagSet, flags};

flags! {
    pub enum Flag: u8 {
        Foo = 1,
        Bar = 2,
        Baz = 4
    }
}

let flag_vec = vec![Flag::Bar, Flag::Baz];
let mut some_extended_flags = FlagSet::from(Flag::Foo);
some_extended_flags.extend(flag_vec);
assert_eq!(some_extended_flags, Flag::Foo | Flag::Bar | Flag::Baz);

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<F: Flags> From<Option<FlagSet<F>>> for FlagSet<F>

fn from(value: Option<FlagSet<F>>) -> 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);

impl<F: Hash + Flags> Hash for FlagSet<F>

where F::Type: Hash,

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, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl<F: Flags> IntoIterator for FlagSet<F>

fn into_iter(self) -> Self::IntoIter

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

type Item = F

The type of the elements being iterated over.

type IntoIter = Iter<F>

Which kind of iterator are we turning this into?

impl<F: Flags> Not for FlagSet<F>

fn not(self) -> 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));

type Output = FlagSet<F>

The resulting type after applying the ! operator.

impl<F: Flags, R: Copy + Into<FlagSet<F>>> PartialEq<R> for FlagSet<F>

fn eq(&self, rhs: &R) -> 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 !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<F: Flags, R: Into<FlagSet<F>>> Rem<R> for FlagSet<F>

fn rem(self, rhs: R) -> 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);

type Output = FlagSet<F>

The resulting type after applying the % operator.

impl<F: Flags, R: Into<FlagSet<F>>> RemAssign<R> for FlagSet<F>

fn rem_assign(&mut self, rhs: R)

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

impl<F: Flags> Serialize for FlagSet<F>

where F::Type: Serialize,

Available on crate feature serde only.

fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>

where S: Serializer,

Serialize this value into the given Serde serializer.

impl<F: Flags, R: Into<FlagSet<F>>> Sub<R> for FlagSet<F>

fn sub(self, rhs: R) -> 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);

type Output = FlagSet<F>

The resulting type after applying the - operator.

impl<F: Flags, R: Into<FlagSet<F>>> SubAssign<R> for FlagSet<F>

fn sub_assign(&mut self, rhs: R)

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

impl<F: Copy + Flags> Copy for FlagSet<F>

where F::Type: Copy,

impl<F: Eq + Flags> Eq for FlagSet<F>

where F::Type: Eq,