Trait Flags

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

    const NAMED_FLAGS: &'static [(&'static str, Self)];
    const RESERVED_BITS: Self::Bits;

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

    // Provided methods
    fn from_bits(bits: Self::Bits) -> Option<Self> { ... }
    fn from_bits_truncate(bits: Self::Bits) -> Self { ... }
    fn from_flag_name(name: &str) -> Option<Self> { ... }
    fn from_name(name: &str) -> Option<Self> { ... }
    fn empty() -> Self { ... }
    fn is_empty(&self) -> bool { ... }
    fn all_bits() -> Self { ... }
    fn is_all_bits(&self) -> bool { ... }
    fn all() -> Self { ... }
    fn is_all(&self) -> bool { ... }
    fn all_named() -> Self { ... }
    fn is_all_named(&self) -> bool { ... }
    fn contains_unknown_bits(&self) -> bool { ... }
    fn contains_unnamed_bits(&self) -> bool { ... }
    fn truncated(&self) -> Self { ... }
    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 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 { ... }
    fn set(&mut self, other: Self)
       where Self: Sized { ... }
    fn unset(&mut self, other: Self)
       where Self: Sized { ... }
    fn toggle(&mut self, other: Self)
       where Self: Sized { ... }
    fn clear(&mut self) { ... }
    fn iter(&self) -> Iter<Self>  { ... }
    fn iter_names(&self) -> IterNames<Self>  { ... }
}

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

Implementing Flags

This trait is implemented by the bitflag macro:

use bitflag_attr::bitflag;

#[bitflag(u8)]
#[derive(Clone, Copy)]
enum MyFlags {
  A = 1,
  B = 1 << 1,
}

It can also be implemented manually:

use bitflag_attr::{Flags};

#[derive(Clone, Copy)]
struct MyFlags(u8);

impl Flags for MyFlags {
    const NAMED_FLAGS: &'static [(&'static str, Self)] = &[
        ("A", MyFlags(1)),
        ("B", MyFlags(1 << 1)),
    ];

    const RESERVED_BITS: Self::Bits = 1 | (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::NAMED_FLAGS.iter().count()
}

#[bitflag(u8)]
#[non_exhaustive]
#[derive(Clone, Copy)]
enum MyFlags {
    A = 1,
    B = 1 << 1,
    C = 1 << 2,
}

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

Required Associated Constants

const NAMED_FLAGS: &'static [(&'static str, Self)]

The set of named defined flags.

const RESERVED_BITS: Self::Bits

All reserved bits values for the flags.

The bits defined here can be named or unnamed and the values defined here will be considered for the all method as a known value.

This can be used for externally defined flags or even reserving bits for future usage.

Usually, the value of this constant can be either 0 or the bitor-ed bits values of the named flags¹. For externally defined flags, the most common value is !0, i.e. all bits.

---

1. By pure logic, all bits from named flags are reserved bits. But alternatively, “reserved bits” can be thought as only the extra bits to be reserved as known. For that reason, the default implementation of the all method consider this value and the values of NAMED_FLAGS to generate the resulting value. ↩

Required Associated Types

type Bits: BitsPrimitive

The underlying bits type.

Required Methods

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

Return 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 bits value exactly.

Provided Methods

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

Converts from a bits value. Returning None is any unknown bits are set.

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

Convert from bits value, unsetting any unknown bits.

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

Convert from a flag name.

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 empty() -> Self

Construct a flags value with all bits unset.

fn is_empty(&self) -> bool

Returns true if the flags value has all bits unset.

fn all_bits() -> Self

Returns a flags value that contains all value.

This will include bits that do not have any flags/meaning. Use all if you want only the specified flags set.

fn is_all_bits(&self) -> bool

Returns true if the bitflag contains all value bits set.

This will check for all bits. Use is_all if you want to check for all specified flags.

fn all() -> Self

Construct a flags value with all known flags set.

This will only set the flags specified as associated constant and the defined extra valid bits.

fn is_all(&self) -> bool

Whether all known bits in this flags value are set.

fn all_named() -> Self

Construct a flags value with all known named flags set.

This will only set the flags specified as associated constant without the defined extra valid bits.

fn is_all_named(&self) -> bool

Returns true if the flags value contais all known named flags.

fn contains_unknown_bits(&self) -> bool

Returns true if there are any unknown bits set in the flags value.

fn contains_unnamed_bits(&self) -> bool

Returns true if there are any unnamed known bits set in the flags value.

fn truncated(&self) -> Self

Returns a flags value with unknown bits removed from the original flags value.

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

where Self: Sized,

Returns true if this flags value intersects with any value in other.

This is equivalent to (self & other) != Self::empty()

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

where Self: Sized,

Returns true if this flags value contains all values of other.

This is equivalent to (self & other) == other

fn truncate(&mut self)

where Self: Sized,

Remove any unknown bits from the flags.

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

Returns the intersection from this flags value with other.

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

Returns the union from this flags value with other.

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

Returns the difference from this flags value with other.

In other words, returns the intersection of this value with the negation of other.

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

Returns the symmetric difference from this flags value with other..

fn complement(self) -> Self

Returns the complement of the flags value.

This is very similar to the not operation, but truncates non used bits.

fn set(&mut self, other: Self)

where Self: Sized,

Set the flags in other in the value.

fn unset(&mut self, other: Self)

where Self: Sized,

Unset the flags bits in other in the 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,

Toggle the flags in other in the value.

fn clear(&mut self)

Resets the flags value to a empty state.

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.

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

impl Flags for ExampleFlags

const NAMED_FLAGS: &'static [(&'static str, ExampleFlags)]

const RESERVED_BITS: u32 = 4_294_967_295u32

type Bits = u32