1use core::{
2 fmt,
3 ops::{BitAnd, BitOr, BitXor, Not},
4};
5
6use crate::{
7 iter,
8 parser::{ParseError, ParseHex, WriteHex},
9};
10
11/**
12A defined flags value that may be named or unnamed.
13*/
14#[derive(Debug)]
15pub struct Flag<B> {
16 name: &'static str,
17 value: B,
18}
19
20impl<B> Flag<B> {
21 /**
22 Define a flag.
23
24 If `name` is non-empty then the flag is named, otherwise it's unnamed.
25 */
26 pub const fn new(name: &'static str, value: B) -> Self {
27 Flag { name, value }
28 }
29
30 /**
31 Get the name of this flag.
32
33 If the flag is unnamed then the returned string will be empty.
34 */
35 pub const fn name(&self) -> &'static str {
36 self.name
37 }
38
39 /**
40 Get the flags value of this flag.
41 */
42 pub const fn value(&self) -> &B {
43 &self.value
44 }
45
46 /**
47 Whether the flag is named.
48
49 If [`Flag::name`] returns a non-empty string then this method will return `true`.
50 */
51 pub const fn is_named(&self) -> bool {
52 !self.name.is_empty()
53 }
54
55 /**
56 Whether the flag is unnamed.
57
58 If [`Flag::name`] returns a non-empty string then this method will return `false`.
59 */
60 pub const fn is_unnamed(&self) -> bool {
61 self.name.is_empty()
62 }
63}
64
65/**
66A set of defined flags using a bits type as storage.
67
68## Implementing `Flags`
69
70This trait is implemented by the [`bitflags`](macro.bitflags.html) macro:
71
72```
73use bitflags::bitflags;
74
75bitflags! {
76 struct MyFlags: u8 {
77 const A = 1;
78 const B = 1 << 1;
79 }
80}
81```
82
83It can also be implemented manually:
84
85```
86use bitflags::{Flag, Flags};
87
88struct MyFlags(u8);
89
90impl Flags for MyFlags {
91 const FLAGS: &'static [Flag<Self>] = &[
92 Flag::new("A", MyFlags(1)),
93 Flag::new("B", MyFlags(1 << 1)),
94 ];
95
96 type Bits = u8;
97
98 fn from_bits_retain(bits: Self::Bits) -> Self {
99 MyFlags(bits)
100 }
101
102 fn bits(&self) -> Self::Bits {
103 self.0
104 }
105}
106```
107
108## Using `Flags`
109
110The `Flags` trait can be used generically to work with any flags types. In this example,
111we can count the number of defined named flags:
112
113```
114# use bitflags::{bitflags, Flags};
115fn defined_flags<F: Flags>() -> usize {
116 F::FLAGS.iter().filter(|f| f.is_named()).count()
117}
118
119bitflags! {
120 struct MyFlags: u8 {
121 const A = 1;
122 const B = 1 << 1;
123 const C = 1 << 2;
124
125 const _ = !0;
126 }
127}
128
129assert_eq!(3, defined_flags::<MyFlags>());
130```
131*/
132pub trait Flags: Sized + 'static {
133 /// The set of defined flags.
134 const FLAGS: &'static [Flag<Self>];
135
136 /// The underlying bits type.
137 type Bits: Bits;
138
139 /// Get a flags value with all bits unset.
140 fn empty() -> Self {
141 Self::from_bits_retain(Self::Bits::EMPTY)
142 }
143
144 /// Get a flags value with all known bits set.
145 fn all() -> Self {
146 let mut truncated = Self::Bits::EMPTY;
147
148 for flag in Self::FLAGS.iter() {
149 truncated = truncated | flag.value().bits();
150 }
151
152 Self::from_bits_retain(truncated)
153 }
154
155 /// This method will return `true` if any unknown bits are set.
156 fn contains_unknown_bits(&self) -> bool {
157 Self::all().bits() & self.bits() != self.bits()
158 }
159
160 /// Get the underlying bits value.
161 ///
162 /// The returned value is exactly the bits set in this flags value.
163 fn bits(&self) -> Self::Bits;
164
165 /// Convert from a bits value.
166 ///
167 /// This method will return `None` if any unknown bits are set.
168 fn from_bits(bits: Self::Bits) -> Option<Self> {
169 let truncated = Self::from_bits_truncate(bits);
170
171 if truncated.bits() == bits {
172 Some(truncated)
173 } else {
174 None
175 }
176 }
177
178 /// Convert from a bits value, unsetting any unknown bits.
179 fn from_bits_truncate(bits: Self::Bits) -> Self {
180 Self::from_bits_retain(bits & Self::all().bits())
181 }
182
183 /// Convert from a bits value exactly.
184 fn from_bits_retain(bits: Self::Bits) -> Self;
185
186 /// Get a flags value with the bits of a flag with the given name set.
187 ///
188 /// This method will return `None` if `name` is empty or doesn't
189 /// correspond to any named flag.
190 fn from_name(name: &str) -> Option<Self> {
191 // Don't parse empty names as empty flags
192 if name.is_empty() {
193 return None;
194 }
195
196 for flag in Self::FLAGS {
197 if flag.name() == name {
198 return Some(Self::from_bits_retain(flag.value().bits()));
199 }
200 }
201
202 None
203 }
204
205 /// Yield a set of contained flags values.
206 ///
207 /// Each yielded flags value will correspond to a defined named flag. Any unknown bits
208 /// will be yielded together as a final flags value.
209 fn iter(&self) -> iter::Iter<Self> {
210 iter::Iter::new(self)
211 }
212
213 /// Yield a set of contained named flags values.
214 ///
215 /// This method is like [`Flags::iter`], except only yields bits in contained named flags.
216 /// Any unknown bits, or bits not corresponding to a contained flag will not be yielded.
217 fn iter_names(&self) -> iter::IterNames<Self> {
218 iter::IterNames::new(self)
219 }
220
221 /// Whether all bits in this flags value are unset.
222 fn is_empty(&self) -> bool {
223 self.bits() == Self::Bits::EMPTY
224 }
225
226 /// Whether all known bits in this flags value are set.
227 fn is_all(&self) -> bool {
228 // NOTE: We check against `Self::all` here, not `Self::Bits::ALL`
229 // because the set of all flags may not use all bits
230 Self::all().bits() | self.bits() == self.bits()
231 }
232
233 /// Whether any set bits in a source flags value are also set in a target flags value.
234 fn intersects(&self, other: Self) -> bool
235 where
236 Self: Sized,
237 {
238 self.bits() & other.bits() != Self::Bits::EMPTY
239 }
240
241 /// Whether all set bits in a source flags value are also set in a target flags value.
242 fn contains(&self, other: Self) -> bool
243 where
244 Self: Sized,
245 {
246 self.bits() & other.bits() == other.bits()
247 }
248
249 /// Remove any unknown bits from the flags.
250 fn truncate(&mut self)
251 where
252 Self: Sized,
253 {
254 *self = Self::from_bits_truncate(self.bits());
255 }
256
257 /// The bitwise or (`|`) of the bits in two flags values.
258 fn insert(&mut self, other: Self)
259 where
260 Self: Sized,
261 {
262 *self = Self::from_bits_retain(self.bits()).union(other);
263 }
264
265 /// The intersection of a source flags value with the complement of a target flags value (`&!`).
266 ///
267 /// This method is not equivalent to `self & !other` when `other` has unknown bits set.
268 /// `remove` won't truncate `other`, but the `!` operator will.
269 fn remove(&mut self, other: Self)
270 where
271 Self: Sized,
272 {
273 *self = Self::from_bits_retain(self.bits()).difference(other);
274 }
275
276 /// The bitwise exclusive-or (`^`) of the bits in two flags values.
277 fn toggle(&mut self, other: Self)
278 where
279 Self: Sized,
280 {
281 *self = Self::from_bits_retain(self.bits()).symmetric_difference(other);
282 }
283
284 /// Call [`Flags::insert`] when `value` is `true` or [`Flags::remove`] when `value` is `false`.
285 fn set(&mut self, other: Self, value: bool)
286 where
287 Self: Sized,
288 {
289 if value {
290 self.insert(other);
291 } else {
292 self.remove(other);
293 }
294 }
295
296 /// Unsets all bits in the flags.
297 fn clear(&mut self)
298 where
299 Self: Sized,
300 {
301 *self = Self::empty();
302 }
303
304 /// The bitwise and (`&`) of the bits in two flags values.
305 #[must_use]
306 fn intersection(self, other: Self) -> Self {
307 Self::from_bits_retain(self.bits() & other.bits())
308 }
309
310 /// The bitwise or (`|`) of the bits in two flags values.
311 #[must_use]
312 fn union(self, other: Self) -> Self {
313 Self::from_bits_retain(self.bits() | other.bits())
314 }
315
316 /// The intersection of a source flags value with the complement of a target flags value (`&!`).
317 ///
318 /// This method is not equivalent to `self & !other` when `other` has unknown bits set.
319 /// `difference` won't truncate `other`, but the `!` operator will.
320 #[must_use]
321 fn difference(self, other: Self) -> Self {
322 Self::from_bits_retain(self.bits() & !other.bits())
323 }
324
325 /// The bitwise exclusive-or (`^`) of the bits in two flags values.
326 #[must_use]
327 fn symmetric_difference(self, other: Self) -> Self {
328 Self::from_bits_retain(self.bits() ^ other.bits())
329 }
330
331 /// The bitwise negation (`!`) of the bits in a flags value, truncating the result.
332 #[must_use]
333 fn complement(self) -> Self {
334 Self::from_bits_truncate(!self.bits())
335 }
336}
337
338/**
339A bits type that can be used as storage for a flags type.
340*/
341pub trait Bits:
342 Clone
343 + Copy
344 + PartialEq
345 + BitAnd<Output = Self>
346 + BitOr<Output = Self>
347 + BitXor<Output = Self>
348 + Not<Output = Self>
349 + Sized
350 + 'static
351{
352 /// A value with all bits unset.
353 const EMPTY: Self;
354
355 /// A value with all bits set.
356 const ALL: Self;
357}
358
359// Not re-exported: prevent custom `Bits` impls being used in the `bitflags!` macro,
360// or they may fail to compile based on crate features
361pub trait Primitive {}
362
363macro_rules! impl_bits {
364 ($($u:ty, $i:ty,)*) => {
365 $(
366 impl Bits for $u {
367 const EMPTY: $u = 0;
368 const ALL: $u = <$u>::MAX;
369 }
370
371 impl Bits for $i {
372 const EMPTY: $i = 0;
373 const ALL: $i = <$u>::MAX as $i;
374 }
375
376 impl ParseHex for $u {
377 fn parse_hex(input: &str) -> Result<Self, ParseError> {
378 <$u>::from_str_radix(input, 16).map_err(|_| ParseError::invalid_hex_flag(input))
379 }
380 }
381
382 impl ParseHex for $i {
383 fn parse_hex(input: &str) -> Result<Self, ParseError> {
384 <$i>::from_str_radix(input, 16).map_err(|_| ParseError::invalid_hex_flag(input))
385 }
386 }
387
388 impl WriteHex for $u {
389 fn write_hex<W: fmt::Write>(&self, mut writer: W) -> fmt::Result {
390 write!(writer, "{:x}", self)
391 }
392 }
393
394 impl WriteHex for $i {
395 fn write_hex<W: fmt::Write>(&self, mut writer: W) -> fmt::Result {
396 write!(writer, "{:x}", self)
397 }
398 }
399
400 impl Primitive for $i {}
401 impl Primitive for $u {}
402 )*
403 }
404}
405
406impl_bits! {
407 u8, i8,
408 u16, i16,
409 u32, i32,
410 u64, i64,
411 u128, i128,
412 usize, isize,
413}
414
415/// A trait for referencing the `bitflags`-owned internal type
416/// without exposing it publicly.
417pub trait PublicFlags {
418 /// The type of the underlying storage.
419 type Primitive: Primitive;
420
421 /// The type of the internal field on the generated flags type.
422 type Internal;
423}
424
425#[doc(hidden)]
426#[deprecated(note = "use the `Flags` trait instead")]
427pub trait BitFlags: ImplementedByBitFlagsMacro + Flags {
428 /// An iterator over enabled flags in an instance of the type.
429 type Iter: Iterator<Item = Self>;
430
431 /// An iterator over the raw names and bits for enabled flags in an instance of the type.
432 type IterNames: Iterator<Item = (&'static str, Self)>;
433}
434
435#[allow(deprecated)]
436impl<B: Flags> BitFlags for B {
437 type Iter = iter::Iter<Self>;
438 type IterNames = iter::IterNames<Self>;
439}
440
441impl<B: Flags> ImplementedByBitFlagsMacro for B {}
442
443/// A marker trait that signals that an implementation of `BitFlags` came from the `bitflags!` macro.
444///
445/// There's nothing stopping an end-user from implementing this trait, but we don't guarantee their
446/// manual implementations won't break between non-breaking releases.
447#[doc(hidden)]
448pub trait ImplementedByBitFlagsMacro {}
449
450pub(crate) mod __private {
451 pub use super::{ImplementedByBitFlagsMacro, PublicFlags};
452}
453