bitflags/
traits.rs

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(#[automatically_derived]
impl<B: ::core::fmt::Debug> ::core::fmt::Debug for Flag<B> {
    #[inline]
    fn fmt(&self, f: &mut ::core::fmt::Formatter) -> ::core::fmt::Result {
        ::core::fmt::Formatter::debug_struct_field2_finish(f, "Flag", "name",
            &self.name, "value", &&self.value)
    }
}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    /// Yield a set of all named flags defined by [`Self::FLAGS`].
222    fn iter_defined_names() -> iter::IterDefinedNames<Self> {
223        iter::IterDefinedNames::new()
224    }
225
226    /// Whether all bits in this flags value are unset.
227    fn is_empty(&self) -> bool {
228        self.bits() == Self::Bits::EMPTY
229    }
230
231    /// Whether all known bits in this flags value are set.
232    fn is_all(&self) -> bool {
233        // NOTE: We check against `Self::all` here, not `Self::Bits::ALL`
234        // because the set of all flags may not use all bits
235        Self::all().bits() | self.bits() == self.bits()
236    }
237
238    /// Whether any set bits in a source flags value are also set in a target flags value.
239    fn intersects(&self, other: Self) -> bool
240    where
241        Self: Sized,
242    {
243        self.bits() & other.bits() != Self::Bits::EMPTY
244    }
245
246    /// Whether all set bits in a source flags value are also set in a target flags value.
247    fn contains(&self, other: Self) -> bool
248    where
249        Self: Sized,
250    {
251        self.bits() & other.bits() == other.bits()
252    }
253
254    /// Remove any unknown bits from the flags.
255    fn truncate(&mut self)
256    where
257        Self: Sized,
258    {
259        *self = Self::from_bits_truncate(self.bits());
260    }
261
262    /// The bitwise or (`|`) of the bits in two flags values.
263    fn insert(&mut self, other: Self)
264    where
265        Self: Sized,
266    {
267        *self = Self::from_bits_retain(self.bits()).union(other);
268    }
269
270    /// The intersection of a source flags value with the complement of a target flags value (`&!`).
271    ///
272    /// This method is not equivalent to `self & !other` when `other` has unknown bits set.
273    /// `remove` won't truncate `other`, but the `!` operator will.
274    fn remove(&mut self, other: Self)
275    where
276        Self: Sized,
277    {
278        *self = Self::from_bits_retain(self.bits()).difference(other);
279    }
280
281    /// The bitwise exclusive-or (`^`) of the bits in two flags values.
282    fn toggle(&mut self, other: Self)
283    where
284        Self: Sized,
285    {
286        *self = Self::from_bits_retain(self.bits()).symmetric_difference(other);
287    }
288
289    /// Call [`Flags::insert`] when `value` is `true` or [`Flags::remove`] when `value` is `false`.
290    fn set(&mut self, other: Self, value: bool)
291    where
292        Self: Sized,
293    {
294        if value {
295            self.insert(other);
296        } else {
297            self.remove(other);
298        }
299    }
300
301    /// Unsets all bits in the flags.
302    fn clear(&mut self)
303    where
304        Self: Sized,
305    {
306        *self = Self::empty();
307    }
308
309    /// The bitwise and (`&`) of the bits in two flags values.
310    #[must_use]
311    fn intersection(self, other: Self) -> Self {
312        Self::from_bits_retain(self.bits() & other.bits())
313    }
314
315    /// The bitwise or (`|`) of the bits in two flags values.
316    #[must_use]
317    fn union(self, other: Self) -> Self {
318        Self::from_bits_retain(self.bits() | other.bits())
319    }
320
321    /// The intersection of a source flags value with the complement of a target flags value (`&!`).
322    ///
323    /// This method is not equivalent to `self & !other` when `other` has unknown bits set.
324    /// `difference` won't truncate `other`, but the `!` operator will.
325    #[must_use]
326    fn difference(self, other: Self) -> Self {
327        Self::from_bits_retain(self.bits() & !other.bits())
328    }
329
330    /// The bitwise exclusive-or (`^`) of the bits in two flags values.
331    #[must_use]
332    fn symmetric_difference(self, other: Self) -> Self {
333        Self::from_bits_retain(self.bits() ^ other.bits())
334    }
335
336    /// The bitwise negation (`!`) of the bits in a flags value, truncating the result.
337    #[must_use]
338    fn complement(self) -> Self {
339        Self::from_bits_truncate(!self.bits())
340    }
341}
342
343/**
344A bits type that can be used as storage for a flags type.
345*/
346pub trait Bits:
347    Clone
348    + Copy
349    + PartialEq
350    + BitAnd<Output = Self>
351    + BitOr<Output = Self>
352    + BitXor<Output = Self>
353    + Not<Output = Self>
354    + Sized
355    + 'static
356{
357    /// A value with all bits unset.
358    const EMPTY: Self;
359
360    /// A value with all bits set.
361    const ALL: Self;
362}
363
364// Not re-exported: prevent custom `Bits` impls being used in the `bitflags!` macro,
365// or they may fail to compile based on crate features
366pub trait Primitive {}
367
368macro_rules! impl_bits {
369    ($($u:ty, $i:ty,)*) => {
370        $(
371            impl Bits for $u {
372                const EMPTY: $u = 0;
373                const ALL: $u = <$u>::MAX;
374            }
375
376            impl Bits for $i {
377                const EMPTY: $i = 0;
378                const ALL: $i = <$u>::MAX as $i;
379            }
380
381            impl ParseHex for $u {
382                fn parse_hex(input: &str) -> Result<Self, ParseError> {
383                    <$u>::from_str_radix(input, 16).map_err(|_| ParseError::invalid_hex_flag(input))
384                }
385            }
386
387            impl ParseHex for $i {
388                fn parse_hex(input: &str) -> Result<Self, ParseError> {
389                    <$i>::from_str_radix(input, 16).map_err(|_| ParseError::invalid_hex_flag(input))
390                }
391            }
392
393            impl WriteHex for $u {
394                fn write_hex<W: fmt::Write>(&self, mut writer: W) -> fmt::Result {
395                    write!(writer, "{:x}", self)
396                }
397            }
398
399            impl WriteHex for $i {
400                fn write_hex<W: fmt::Write>(&self, mut writer: W) -> fmt::Result {
401                    write!(writer, "{:x}", self)
402                }
403            }
404
405            impl Primitive for $i {}
406            impl Primitive for $u {}
407        )*
408    }
409}
410
411impl Bits for usize {
    const EMPTY: usize = 0;
    const ALL: usize = <usize>::MAX;
}
impl Bits for isize {
    const EMPTY: isize = 0;
    const ALL: isize = <usize>::MAX as isize;
}
impl ParseHex for usize {
    fn parse_hex(input: &str) -> Result<Self, ParseError> {
        <usize>::from_str_radix(input,
                16).map_err(|_| ParseError::invalid_hex_flag(input))
    }
}
impl ParseHex for isize {
    fn parse_hex(input: &str) -> Result<Self, ParseError> {
        <isize>::from_str_radix(input,
                16).map_err(|_| ParseError::invalid_hex_flag(input))
    }
}
impl WriteHex for usize {
    fn write_hex<W: fmt::Write>(&self, mut writer: W) -> fmt::Result {
        writer.write_fmt(format_args!("{0:x}", self))
    }
}
impl WriteHex for isize {
    fn write_hex<W: fmt::Write>(&self, mut writer: W) -> fmt::Result {
        writer.write_fmt(format_args!("{0:x}", self))
    }
}
impl Primitive for isize {}
impl Primitive for usize {}impl_bits! {
412    u8, i8,
413    u16, i16,
414    u32, i32,
415    u64, i64,
416    u128, i128,
417    usize, isize,
418}
419
420/// A trait for referencing the `bitflags`-owned internal type
421/// without exposing it publicly.
422pub trait PublicFlags {
423    /// The type of the underlying storage.
424    type Primitive: Primitive;
425
426    /// The type of the internal field on the generated flags type.
427    type Internal;
428}
429
430#[doc(hidden)]
431#[deprecated(note = "use the `Flags` trait instead")]
432pub trait BitFlags: ImplementedByBitFlagsMacro + Flags {
433    /// An iterator over enabled flags in an instance of the type.
434    type Iter: Iterator<Item = Self>;
435
436    /// An iterator over the raw names and bits for enabled flags in an instance of the type.
437    type IterNames: Iterator<Item = (&'static str, Self)>;
438}
439
440#[allow(deprecated)]
441impl<B: Flags> BitFlags for B {
442    type Iter = iter::Iter<Self>;
443    type IterNames = iter::IterNames<Self>;
444}
445
446impl<B: Flags> ImplementedByBitFlagsMacro for B {}
447
448/// A marker trait that signals that an implementation of `BitFlags` came from the `bitflags!` macro.
449///
450/// There's nothing stopping an end-user from implementing this trait, but we don't guarantee their
451/// manual implementations won't break between non-breaking releases.
452#[doc(hidden)]
453pub trait ImplementedByBitFlagsMacro {}
454
455pub(crate) mod __private {
456    pub use super::{ImplementedByBitFlagsMacro, PublicFlags};
457}
bitflags/traits.rs

bitflags/
traits.rs
