crafter 0.3.0

Packet-level network interaction for Rust tools and agents.
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
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155

//! Field state tracking for protocol encoders.

/// The state of a protocol field.
///
/// Protocol builders use this to distinguish fields that may be auto-filled
/// from fields the caller set explicitly.
#[derive(Debug, Clone, PartialEq, Eq, Default)]
pub enum Field<T> {
    /// No value has been assigned.
    #[default]
    Unset,
    /// The library assigned a default value.
    Defaulted(T),
    /// The caller explicitly supplied a value.
    User(T),
}

/// A compact copyable view of a [`Field`]'s state.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum FieldState {
    /// No value has been assigned.
    Unset,
    /// The library assigned a default value.
    Defaulted,
    /// The caller explicitly supplied a value.
    User,
}

impl<T> Field<T> {
    /// Create an unset field.
    pub const fn unset() -> Self {
        Self::Unset
    }

    /// Create a field with a library default value.
    pub const fn defaulted(value: T) -> Self {
        Self::Defaulted(value)
    }

    /// Create a field with a caller-supplied value.
    pub const fn user(value: T) -> Self {
        Self::User(value)
    }

    /// Return a copyable description of the field state.
    pub const fn state(&self) -> FieldState {
        match self {
            Self::Unset => FieldState::Unset,
            Self::Defaulted(_) => FieldState::Defaulted,
            Self::User(_) => FieldState::User,
        }
    }

    /// Return true when the field has no value.
    pub const fn is_unset(&self) -> bool {
        matches!(self, Self::Unset)
    }

    /// Return true when the field has a library default value.
    pub const fn is_defaulted(&self) -> bool {
        matches!(self, Self::Defaulted(_))
    }

    /// Return true when the caller explicitly supplied the value.
    pub const fn is_user_set(&self) -> bool {
        matches!(self, Self::User(_))
    }

    /// Read the current value, if any.
    pub const fn value(&self) -> Option<&T> {
        match self {
            Self::Unset => None,
            Self::Defaulted(value) | Self::User(value) => Some(value),
        }
    }

    /// Mutably read the current value, if any.
    pub fn value_mut(&mut self) -> Option<&mut T> {
        match self {
            Self::Unset => None,
            Self::Defaulted(value) | Self::User(value) => Some(value),
        }
    }

    /// Assign a library default only when the field is currently unset.
    pub fn set_default_if_unset(&mut self, value: T) -> bool {
        if self.is_unset() {
            *self = Self::Defaulted(value);
            true
        } else {
            false
        }
    }

    /// Assign or replace the caller-supplied value.
    pub fn set_user(&mut self, value: T) {
        *self = Self::User(value);
    }

    /// Consume the field and return the value, if any.
    pub fn into_value(self) -> Option<T> {
        match self {
            Self::Unset => None,
            Self::Defaulted(value) | Self::User(value) => Some(value),
        }
    }
}

impl<T> From<T> for Field<T> {
    fn from(value: T) -> Self {
        Self::User(value)
    }
}

#[cfg(test)]
mod field_primitives {
    use super::{Field, FieldState};

    #[test]
    fn unset_fields_have_no_value() {
        let field = Field::<u16>::unset();

        assert_eq!(field.state(), FieldState::Unset);
        assert!(field.is_unset());
        assert_eq!(field.value(), None);
    }

    #[test]
    fn defaults_do_not_overwrite_user_values() {
        let mut field = Field::user(7u8);

        assert!(!field.set_default_if_unset(9));
        assert_eq!(field.state(), FieldState::User);
        assert_eq!(field.value(), Some(&7));
    }

    #[test]
    fn defaults_fill_only_unset_values() {
        let mut field = Field::unset();

        assert!(field.set_default_if_unset(9u8));
        assert_eq!(field.state(), FieldState::Defaulted);
        assert_eq!(field.into_value(), Some(9));
    }

    #[test]
    fn user_assignment_replaces_defaults() {
        let mut field = Field::defaulted(9u16);

        field.set_user(42);

        assert_eq!(field.state(), FieldState::User);
        assert_eq!(field.value(), Some(&42));
    }
}