pub trait Flags: Sized + 'static {
type Bits: Bits;
const FLAGS: &'static [Flag<Self>];
Show 22 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 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 { ... }
}
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§
Required Associated Types§
Required Methods§
Sourcefn bits(&self) -> Self::Bits
fn bits(&self) -> Self::Bits
Get the underlying bits value.
The returned value is exactly the bits set in this flags value.
Sourcefn from_bits_retain(bits: Self::Bits) -> Self
fn from_bits_retain(bits: Self::Bits) -> Self
Convert from a bits value exactly.
Provided Methods§
Sourcefn from_bits(bits: Self::Bits) -> Option<Self>
fn from_bits(bits: Self::Bits) -> Option<Self>
Convert from a bits value.
This method will return None
if any unknown bits are set.
Sourcefn from_bits_truncate(bits: Self::Bits) -> Self
fn from_bits_truncate(bits: Self::Bits) -> Self
Convert from a bits value, unsetting any unknown bits.
Sourcefn from_name(name: &str) -> Option<Self>
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.
Sourcefn iter(&self) -> Iter<Self> ⓘ
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.
Sourcefn iter_names(&self) -> IterNames<Self> ⓘ
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.
Sourcefn intersects(&self, other: Self) -> boolwhere
Self: Sized,
fn intersects(&self, other: Self) -> boolwhere
Self: Sized,
Whether any set bits in a source flags value are also set in a target flags value.
Sourcefn contains(&self, other: Self) -> boolwhere
Self: Sized,
fn contains(&self, other: Self) -> boolwhere
Self: Sized,
Whether all set bits in a source flags value are also set in a target flags value.
Sourcefn insert(&mut self, other: Self)where
Self: Sized,
fn insert(&mut self, other: Self)where
Self: Sized,
The bitwise or (|
) of the bits in two flags values.
Sourcefn remove(&mut self, other: Self)where
Self: Sized,
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.
Sourcefn toggle(&mut self, other: Self)where
Self: Sized,
fn toggle(&mut self, other: Self)where
Self: Sized,
The bitwise exclusive-or (^
) of the bits in two flags values.
Sourcefn set(&mut self, other: Self, value: bool)where
Self: Sized,
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
.
Sourcefn intersection(self, other: Self) -> Self
fn intersection(self, other: Self) -> Self
The bitwise and (&
) of the bits in two flags values.
Sourcefn difference(self, other: Self) -> Self
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.
Sourcefn symmetric_difference(self, other: Self) -> Self
fn symmetric_difference(self, other: Self) -> Self
The bitwise exclusive-or (^
) of the bits in two flags values.
Sourcefn complement(self) -> Self
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.