Trait Flags

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

    const FLAGS: &'static [Flag<Self>];
Show 25 methods
    // Required methods
    fn bits(&self) -> Self::Bits;
    fn from_bits_retain(bits: Self::Bits) -> Self;

    // Provided methods
    fn empty() -> Self { ... }
    fn all() -> Self { ... }
    fn contains_unknown_bits(&self) -> bool { ... }
    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 truncate(&mut self)
       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 clear(&mut self)
       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 { ... }
}

Expand description

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 contains_unknown_bits(&self) -> bool

This method will return true if any unknown bits are 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.