Skip to main content

tor_protover/
value.rs

1//! `Value`, the numerical part of a protocol capability
2
3use super::*;
4
5/// Maximum allowable value for a protocol's version field.
6//
7// TODO this should be a u8, not a usize, probably
8pub(crate) const MAX_VER: usize = 63;
9
10/// "Value", the numerical part of a protocol capability
11//
12// Invariant: valid, ie in the range 1..=MAX_VER.
13#[derive(Debug, Clone, Copy, Hash, Eq, PartialEq, Ord, PartialOrd)] //
14#[derive(derive_more::Into, derive_more::Display)]
15#[display("{_0}")]
16pub struct Value(u8);
17
18/// A `Value` was out of range (zero, or >63)
19#[derive(Error, Debug, PartialEq, Eq, Clone, derive_more::Into)]
20#[error("Protocol version {v} out of range")]
21pub struct ValueOutOfRange {
22    /// The value that was wrong
23    v: u8,
24}
25
26impl Value {
27    /// Create a `Value` from a raw integer
28    pub const fn new(v: u8) -> Result<Self, ValueOutOfRange> {
29        if 1 <= v && v <= MAX_VER as _ {
30            Ok(Value(v))
31        } else {
32            Err(ValueOutOfRange { v })
33        }
34    }
35
36    /// Create a `Value` from a raw integer, in const context
37    ///
38    /// # Panics
39    ///
40    /// Panics if `v` is out of range.
41    ///
42    /// Not ideal in non-const contexts if panicking is remotely possible,
43    /// since the panic message is very bad.
44    pub const fn new_const(v: u8) -> Self {
45        match Self::new(v) {
46            Ok(y) => y,
47            Err(ValueOutOfRange { .. }) => panic!(),
48        }
49    }
50
51    /// Return a mask with precisely this bit set
52    pub fn to_bit(self) -> u64 {
53        1_u64 << self.0
54    }
55
56    /// Iterate over all legal `Value`s
57    pub fn iter_all() -> impl Iterator<Item = Self> + Clone {
58        (1..=(MAX_VER as _)).map(Value::new_const)
59    }
60}
61
62impl TryFrom<u8> for Value {
63    type Error = ValueOutOfRange;
64    fn try_from(v: u8) -> Result<Self, ValueOutOfRange> {
65        Self::new(v)
66    }
67}
68
69#[cfg(test)]
70mod test {
71    // @@ begin test lint list maintained by maint/add_warning @@
72    #![allow(clippy::bool_assert_comparison)]
73    #![allow(clippy::clone_on_copy)]
74    #![allow(clippy::dbg_macro)]
75    #![allow(clippy::mixed_attributes_style)]
76    #![allow(clippy::print_stderr)]
77    #![allow(clippy::print_stdout)]
78    #![allow(clippy::single_char_pattern)]
79    #![allow(clippy::unwrap_used)]
80    #![allow(clippy::unchecked_time_subtraction)]
81    #![allow(clippy::useless_vec)]
82    #![allow(clippy::needless_pass_by_value)]
83    #![allow(clippy::string_slice)] // See arti#2571
84    //! <!-- @@ end test lint list maintained by maint/add_warning @@ -->
85
86    use super::*;
87
88    #[test]
89    fn simple() {
90        let good = |v| assert_eq!(Value::try_from(v), Ok(Value(v)));
91        let bad = |v| assert_eq!(Value::try_from(v), Err(ValueOutOfRange { v }));
92        bad(0);
93        good(1);
94        good(63);
95        bad(64);
96        bad(255);
97    }
98}