bitflags-lite 0.1.0

Lightweight generics-based bitflags
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124

/// Associates a bit-storage type `T` with the set of bits that are valid for a
/// particular [`BitFlags`] tag.
///
/// Implement this trait for the tag type `U` in [`BitFlags<T, U>`].
/// [`VALID_BITS_MASK`](Self::VALID_BITS_MASK) defines which bits are valid for
/// the flag set.
///
/// Bits not set in `VALID_BITS_MASK` are invalid:
/// - [`BitFlags::try_from_bits`] rejects them.
/// - [`BitFlags::from_bits_truncate`] and [`BitFlags::truncate`] clear them.
/// - [`BitFlags::complement`] and [`Not`](core::ops::Not) clear them.
/// - [`BitFlags::from_bits_retain`] and operations that do not explicitly
///   truncate may preserve them.
///
/// Unlike the `bitflags` crate, valid bits are not declared by a macro. They
/// are part of this trait implementation for the tag type.
///
/// # Examples
///
/// ```
/// use bitflags_lite::{BitFlags, BitFlagsSpec, NameMatcher};
///
/// struct PermissionsTag;
///
/// impl BitFlagsSpec<u32> for PermissionsTag {
///     const VALID_BITS_MASK: u32 = (1 << 3) - 1;
///     const FLAG_NAMES: &[&[&str]] = &[&["read"], &["write"], &["exec", "execute"]];
///     const DEFAULT_NAME_MATCHER: NameMatcher = NameMatcher::Exact;
/// }
///
/// type Permissions = BitFlags<u32, PermissionsTag>;
///
/// const READ: Permissions = Permissions::try_from_bit(0).unwrap();
/// const WRITE: Permissions = Permissions::try_from_bit(1).unwrap();
/// const EXEC: Permissions = Permissions::try_from_bit(2).unwrap();
///
/// assert_eq!(Permissions::try_from_bits(0b1), Some(READ));
/// assert_eq!(Permissions::try_from_bits(0b11), Some(READ | WRITE));
/// assert_eq!(Permissions::try_from_bits(0b111), Some(READ | WRITE | EXEC));
/// assert_eq!(Permissions::try_from_bits(0b1111), None);
/// ```
///
/// [`BitFlags`]: struct.BitFlags.html
/// [`BitFlags<T, U>`]: struct.BitFlags.html
/// [`BitFlags::try_from_bits`]: struct.BitFlags.html#method.try_from_bits
/// [`BitFlags::from_bits_truncate`]: struct.BitFlags.html#method.from_bits_truncate
/// [`BitFlags::truncate`]: struct.BitFlags.html#method.truncate
/// [`BitFlags::complement`]: struct.BitFlags.html#method.complement
/// [`BitFlags::from_bits_retain`]: struct.BitFlags.html#method.from_bits_retain
pub trait BitFlagsSpec<T> {
    /// A bit pattern whose set bits are the valid bits for this flag set.
    ///
    /// Bits not set in this value are invalid for the associated [`BitFlags`]
    /// type.
    /// They are rejected by [`BitFlags::try_from_bits`] and cleared by
    /// [`BitFlags::from_bits_truncate`], [`BitFlags::truncate`],
    /// [`BitFlags::complement`], and [`Not`](core::ops::Not).
    ///
    /// [`BitFlags`]: struct.BitFlags.html
    /// [`BitFlags::try_from_bits`]: struct.BitFlags.html#method.try_from_bits
    /// [`BitFlags::from_bits_truncate`]: struct.BitFlags.html#method.from_bits_truncate
    /// [`BitFlags::truncate`]: struct.BitFlags.html#method.truncate
    /// [`BitFlags::complement`]: struct.BitFlags.html#method.complement
    const VALID_BITS_MASK: T;

    /// A slice indexed by bit position, where each element contains the names
    /// associated with that bit.
    ///
    /// The first name in each inner slice is used by [`BitFlag`]'s and
    /// [`BitFlags`]'s [`Display`](core::fmt::Display) implementations.
    /// All names are accepted when parsing.
    /// An empty inner slice means the bit has no name.
    ///
    /// The index `i` corresponds to the bit mask `1 << i`.
    ///
    /// [`BitFlag`]: struct.BitFlag.html
    /// [`BitFlags`]: struct.BitFlags.html
    const FLAG_NAMES: &[&[&str]];

    /// Controls whether the default [`FromStr`](core::str::FromStr) and
    /// `Deserialize` implementations for [`BitFlags`] parse named flags
    /// case-sensitively.
    ///
    /// If [`NameMatcher::Exact`], named flags are matched exactly.
    /// If [`NameMatcher::AsciiCaseInsensitive`], named flags are matched
    /// using ASCII case-insensitive comparison.
    ///
    /// This value does not affect methods that accept an explicit
    /// [`NameMatcher`], such as [`BitFlags::try_from_str`].
    ///
    /// [`BitFlags`]: struct.BitFlags.html
    /// [`BitFlags::try_from_str`]: struct.BitFlags.html#method.try_from_str
    const DEFAULT_NAME_MATCHER: NameMatcher;
}

/// Controls how flag names are matched when parsing.
///
/// # Why `#[non_exhaustive]`
///
/// `NameMatcher` is only used as an input parameter to parsing APIs, never
/// returned as a result.
/// `#[non_exhaustive]` is appropriate here because new matcher variants can
/// then be added in minor releases without breaking callers.
#[derive(Copy, Clone, Eq, PartialEq, Ord, PartialOrd, Hash, Debug)]
#[non_exhaustive]
pub enum NameMatcher {
    /// Matches flag names exactly.
    Exact,

    /// Matches flag names using ASCII case-insensitive comparison.
    AsciiCaseInsensitive,
}

impl NameMatcher {
    /// Returns `true` if `given` matches `expected` according to this matcher.
    #[inline]
    #[must_use]
    pub fn matches(self, given: &str, expected: &str) -> bool {
        match self {
            Self::Exact => given == expected,
            Self::AsciiCaseInsensitive => given.eq_ignore_ascii_case(expected),
        }
    }
}