Skip to main content

fprint_core/
finger.rs

1// SPDX-FileCopyrightText: 2026 fprintd (pure-Rust) contributors
2//
3// SPDX-License-Identifier: MIT OR Apache-2.0
4
5//! Finger identity — the FP3/`FpFinger` byte value, via the [`From`]/[`TryFrom`] conversions to and
6//! from `u8` (or the equivalent [`Finger::as_u8`]/[`Finger::from_u8`] inherent methods).
7//!
8//! The `net.reactivated.Fprint` D-Bus finger-name vocabulary (`"left-index-finger"`, …) is
9//! *not* here: that is interop wire vocabulary and lives at the daemon edge (`fprintd`),
10//! per `ARCHITECTURE.md` principle 3.
11
12/// A finger, matching libfprint's `FpFinger` enum ordering (see `fp-print.h`).
13///
14/// The discriminant is meaningful: it is the value stored in the FP3 template `finger`
15/// byte, and it names the per-finger files under `/var/lib/fprint/<user>/<driver>/`.
16/// `Unknown = 0`; real fingers are `1..=10`.
17#[repr(u8)]
18#[derive(Clone, Copy, PartialEq, Eq, Hash, Debug)]
19pub enum Finger {
20    /// `FP_FINGER_UNKNOWN`: no finger recorded. Not one of [`Finger::ALL`].
21    Unknown = 0,
22    /// `FP_FINGER_LEFT_THUMB`.
23    LeftThumb = 1,
24    /// `FP_FINGER_LEFT_INDEX`.
25    LeftIndex = 2,
26    /// `FP_FINGER_LEFT_MIDDLE`.
27    LeftMiddle = 3,
28    /// `FP_FINGER_LEFT_RING`.
29    LeftRing = 4,
30    /// `FP_FINGER_LEFT_LITTLE`.
31    LeftLittle = 5,
32    /// `FP_FINGER_RIGHT_THUMB`.
33    RightThumb = 6,
34    /// `FP_FINGER_RIGHT_INDEX`.
35    RightIndex = 7,
36    /// `FP_FINGER_RIGHT_MIDDLE`.
37    RightMiddle = 8,
38    /// `FP_FINGER_RIGHT_RING`.
39    RightRing = 9,
40    /// `FP_FINGER_RIGHT_LITTLE`.
41    RightLittle = 10,
42}
43
44impl Finger {
45    /// First real finger (`FP_FINGER_FIRST`).
46    pub const FIRST: Finger = Finger::LeftThumb;
47    /// Last real finger (`FP_FINGER_LAST`).
48    pub const LAST: Finger = Finger::RightLittle;
49
50    /// All ten real fingers in canonical order.
51    pub const ALL: [Finger; 10] = [
52        Finger::LeftThumb,
53        Finger::LeftIndex,
54        Finger::LeftMiddle,
55        Finger::LeftRing,
56        Finger::LeftLittle,
57        Finger::RightThumb,
58        Finger::RightIndex,
59        Finger::RightMiddle,
60        Finger::RightRing,
61        Finger::RightLittle,
62    ];
63
64    /// Reconstruct from the raw FP3/`FpFinger` byte.
65    #[must_use]
66    pub fn from_u8(v: u8) -> Option<Finger> {
67        Some(match v {
68            0 => Finger::Unknown,
69            1 => Finger::LeftThumb,
70            2 => Finger::LeftIndex,
71            3 => Finger::LeftMiddle,
72            4 => Finger::LeftRing,
73            5 => Finger::LeftLittle,
74            6 => Finger::RightThumb,
75            7 => Finger::RightIndex,
76            8 => Finger::RightMiddle,
77            9 => Finger::RightRing,
78            10 => Finger::RightLittle,
79            _ => return None,
80        })
81    }
82
83    /// The raw FP3/`FpFinger` byte value.
84    #[must_use]
85    pub fn as_u8(self) -> u8 {
86        self as u8
87    }
88}
89
90/// The error [`Finger::try_from`] returns for a byte outside the valid `0..=10` range.
91///
92/// Deliberately not `#[non_exhaustive]`: a fully-specified value error callers exhaustively match.
93#[derive(Clone, Copy, PartialEq, Eq, Debug)]
94pub struct InvalidFinger(
95    /// The offending byte.
96    pub u8,
97);
98
99impl core::fmt::Display for InvalidFinger {
100    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
101        write!(f, "{} is not a valid finger byte (expected 0..=10)", self.0)
102    }
103}
104
105impl std::error::Error for InvalidFinger {}
106
107impl From<Finger> for u8 {
108    /// The raw FP3/`FpFinger` byte value — the [`From`] form of [`Finger::as_u8`].
109    fn from(finger: Finger) -> u8 {
110        finger as u8
111    }
112}
113
114impl TryFrom<u8> for Finger {
115    type Error = InvalidFinger;
116
117    /// Reconstruct from the raw FP3/`FpFinger` byte — the [`TryFrom`] form of [`Finger::from_u8`],
118    /// naming the offending byte on failure.
119    fn try_from(v: u8) -> Result<Finger, InvalidFinger> {
120        Finger::from_u8(v).ok_or(InvalidFinger(v))
121    }
122}
123
124#[cfg(test)]
125mod tests {
126    use super::{Finger, InvalidFinger};
127
128    #[test]
129    fn byte_roundtrip_is_stable() {
130        for f in Finger::ALL {
131            assert_eq!(Finger::from_u8(f.as_u8()), Some(f));
132        }
133        assert_eq!(Finger::from_u8(0), Some(Finger::Unknown));
134        assert_eq!(Finger::from_u8(11), None);
135    }
136
137    /// The std [`From`]/[`TryFrom`] conversions agree with the inherent `as_u8`/`from_u8` over the
138    /// whole byte, and the error names the offending value.
139    #[test]
140    fn std_conversions_agree_with_inherent_methods() {
141        for v in u8::MIN..=u8::MAX {
142            assert_eq!(
143                Finger::try_from(v).ok(),
144                Finger::from_u8(v),
145                "try_from({v})"
146            );
147            match Finger::try_from(v) {
148                Ok(f) => assert_eq!(u8::from(f), v, "u8::from round-trip for {f:?}"),
149                Err(e) => assert_eq!(e, InvalidFinger(v), "error carries the byte"),
150            }
151        }
152        // Every real finger and Unknown convert to their discriminant.
153        for f in Finger::ALL.iter().chain(&[Finger::Unknown]) {
154            assert_eq!(u8::from(*f), f.as_u8());
155        }
156    }
157
158    /// [`Finger::from_u8`] is total over its input, so the accepted set is checked over the whole
159    /// byte rather than at the `10`/`11` boundary: **`Some` iff `0..=10`.**
160    #[test]
161    fn from_u8_accepts_exactly_zero_through_ten() {
162        for v in u8::MIN..=u8::MAX {
163            let decoded = Finger::from_u8(v);
164            assert_eq!(decoded.is_some(), v <= 10, "from_u8({v}) = {decoded:?}");
165            // Whatever it decodes to must encode back to the byte it came from.
166            if let Some(f) = decoded {
167                assert_eq!(f.as_u8(), v);
168            }
169        }
170    }
171
172    /// [`Finger::ALL`] is the ten real fingers — `Unknown` is not one of them — in byte order.
173    #[test]
174    fn all_lists_the_ten_real_fingers_in_byte_order() {
175        let bytes: Vec<u8> = Finger::ALL.iter().map(|f| f.as_u8()).collect();
176        assert_eq!(bytes, (1..=10).collect::<Vec<u8>>());
177        assert!(!Finger::ALL.contains(&Finger::Unknown));
178    }
179
180    #[test]
181    fn discriminants_match_libfprint() {
182        // Guards against accidental reordering that would corrupt FP3 template bytes.
183        assert_eq!(Finger::LeftThumb.as_u8(), 1);
184        assert_eq!(Finger::RightLittle.as_u8(), 10);
185        assert_eq!(Finger::FIRST, Finger::LeftThumb);
186        assert_eq!(Finger::LAST, Finger::RightLittle);
187    }
188}