Trait Flags

pub trait Flags: Sized + 'static {
    type Bits: Bits;

    const FLAGS: &'static [Flag<Self>];

    // Required methods
    fn bits(&self) -> Self::Bits;
    fn from_bits_retain(bits: Self::Bits) -> Self;

    // Provided methods
    fn empty() -> Self { ... }
    fn all() -> Self { ... }
    fn from_bits(bits: Self::Bits) -> Option<Self> { ... }
    fn from_bits_truncate(bits: Self::Bits) -> Self { ... }
    fn from_name(name: &str) -> Option<Self> { ... }
    fn iter(&self) -> Iter<Self>  { ... }
    fn iter_names(&self) -> IterNames<Self>  { ... }
    fn is_empty(&self) -> bool { ... }
    fn is_all(&self) -> bool { ... }
    fn intersects(&self, other: Self) -> bool
       where Self: Sized { ... }
    fn contains(&self, other: Self) -> bool
       where Self: Sized { ... }
    fn insert(&mut self, other: Self)
       where Self: Sized { ... }
    fn remove(&mut self, other: Self)
       where Self: Sized { ... }
    fn toggle(&mut self, other: Self)
       where Self: Sized { ... }
    fn set(&mut self, other: Self, value: bool)
       where Self: Sized { ... }
    fn intersection(self, other: Self) -> Self { ... }
    fn union(self, other: Self) -> Self { ... }
    fn difference(self, other: Self) -> Self { ... }
    fn symmetric_difference(self, other: Self) -> Self { ... }
    fn complement(self) -> Self { ... }
}

A set of defined flags using a bits type as storage.

Implementing Flags

This trait is implemented by the bitflags macro:

use bitflags::bitflags;

bitflags! {
    struct MyFlags: u8 {
        const A = 1;
        const B = 1 << 1;
    }
}

It can also be implemented manually:

use bitflags::{Flag, Flags};

struct MyFlags(u8);

impl Flags for MyFlags {
    const FLAGS: &'static [Flag<Self>] = &[
        Flag::new("A", MyFlags(1)),
        Flag::new("B", MyFlags(1 << 1)),
    ];

    type Bits = u8;

    fn from_bits_retain(bits: Self::Bits) -> Self {
        MyFlags(bits)
    }

    fn bits(&self) -> Self::Bits {
        self.0
    }
}

Using Flags

The Flags trait can be used generically to work with any flags types. In this example, we can count the number of defined named flags:

fn defined_flags<F: Flags>() -> usize {
    F::FLAGS.iter().filter(|f| f.is_named()).count()
}

bitflags! {
    struct MyFlags: u8 {
        const A = 1;
        const B = 1 << 1;
        const C = 1 << 2;

        const _ = !0;
    }
}

assert_eq!(3, defined_flags::<MyFlags>());

Required Associated Constants

const FLAGS: &'static [Flag<Self>]

The set of defined flags.

Required Associated Types

type Bits: Bits

The underlying bits type.

Required Methods

fn bits(&self) -> Self::Bits

Get the underlying bits value.

The returned value is exactly the bits set in this flags value.

fn from_bits_retain(bits: Self::Bits) -> Self

Convert from a bits value exactly.

Provided Methods

fn empty() -> Self

Get a flags value with all bits unset.

fn all() -> Self

Get a flags value with all known bits set.

fn from_bits(bits: Self::Bits) -> Option<Self>

Convert from a bits value.

This method will return None if any unknown bits are set.

fn from_bits_truncate(bits: Self::Bits) -> Self

Convert from a bits value, unsetting any unknown bits.

fn from_name(name: &str) -> Option<Self>

Get a flags value with the bits of a flag with the given name set.

This method will return None if name is empty or doesn’t correspond to any named flag.

fn iter(&self) -> Iter<Self>

Yield a set of contained flags values.

Each yielded flags value will correspond to a defined named flag. Any unknown bits will be yielded together as a final flags value.

fn iter_names(&self) -> IterNames<Self>

Yield a set of contained named flags values.

This method is like Flags::iter, except only yields bits in contained named flags. Any unknown bits, or bits not corresponding to a contained flag will not be yielded.

fn is_empty(&self) -> bool

Whether all bits in this flags value are unset.

fn is_all(&self) -> bool

Whether all known bits in this flags value are set.

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

where Self: Sized,

Whether any set bits in a source flags value are also set in a target flags value.

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

where Self: Sized,

Whether all set bits in a source flags value are also set in a target flags value.

fn insert(&mut self, other: Self)

where Self: Sized,

The bitwise or (|) of the bits in two flags values.

fn remove(&mut self, other: Self)

where Self: Sized,

The intersection of a source flags value with the complement of a target flags value (&!).

This method is not equivalent to self & !other when other has unknown bits set. remove won’t truncate other, but the ! operator will.

fn toggle(&mut self, other: Self)

where Self: Sized,

The bitwise exclusive-or (^) of the bits in two flags values.

fn set(&mut self, other: Self, value: bool)

where Self: Sized,

Call Flags::insert when value is true or Flags::remove when value is false.

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

The bitwise and (&) of the bits in two flags values.

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

The bitwise or (|) of the bits in two flags values.

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

The intersection of a source flags value with the complement of a target flags value (&!).

This method is not equivalent to self & !other when other has unknown bits set. difference won’t truncate other, but the ! operator will.

fn symmetric_difference(self, other: Self) -> Self

The bitwise exclusive-or (^) of the bits in two flags values.

fn complement(self) -> Self

The bitwise negation (!) of the bits in a flags value, truncating the result.

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementors