use-control-signal 0.0.1

Control signal validation and saturation helpers
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

#![forbid(unsafe_code)]
//! Control signal primitives.
//!
//! The crate keeps control signal transformations explicit: construct, clamp,
//! scale, or saturate a finite scalar value.
//!
//! # Examples
//!
//! ```rust
//! use use_control_signal::{clamp_signal, saturate, ControlSignal};
//!
//! let signal = ControlSignal::new(12.0).unwrap().clamp(0.0, 10.0).unwrap();
//! assert_eq!(signal.value(), 10.0);
//! assert_eq!(clamp_signal(2.5, 0.0, 2.0).unwrap(), 2.0);
//! assert_eq!(saturate(-5.0, 2.0).unwrap(), -2.0);
//! ```

#[derive(Debug, Clone, Copy, PartialEq)]
pub struct ControlSignal {
    value: f64,
}

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum ControlSignalError {
    InvalidValue,
    InvalidBounds,
    InvalidFactor,
}

impl ControlSignal {
    pub fn new(value: f64) -> Result<Self, ControlSignalError> {
        if !value.is_finite() {
            return Err(ControlSignalError::InvalidValue);
        }

        Ok(Self { value })
    }

    pub fn value(&self) -> f64 {
        self.value
    }

    pub fn clamp(self, min: f64, max: f64) -> Result<Self, ControlSignalError> {
        Self::new(clamp_signal(self.value, min, max)?)
    }

    pub fn scale(self, factor: f64) -> Result<Self, ControlSignalError> {
        if !factor.is_finite() {
            return Err(ControlSignalError::InvalidFactor);
        }

        let value = self.value * factor;
        Self::new(value)
    }
}

pub fn clamp_signal(value: f64, min: f64, max: f64) -> Result<f64, ControlSignalError> {
    if !value.is_finite() || !min.is_finite() || !max.is_finite() {
        return Err(ControlSignalError::InvalidValue);
    }

    if min > max {
        return Err(ControlSignalError::InvalidBounds);
    }

    Ok(value.clamp(min, max))
}

pub fn saturate(value: f64, limit: f64) -> Result<f64, ControlSignalError> {
    if !limit.is_finite() || limit < 0.0 {
        return Err(ControlSignalError::InvalidBounds);
    }

    clamp_signal(value, -limit, limit)
}

#[cfg(test)]
mod tests {
    use super::{ControlSignal, ControlSignalError, clamp_signal, saturate};

    #[test]
    fn clamps_and_scales_signals() {
        let signal = ControlSignal::new(12.0).unwrap().clamp(0.0, 10.0).unwrap();

        assert_eq!(signal.value(), 10.0);
        assert_eq!(signal.scale(0.5).unwrap().value(), 5.0);
        assert_eq!(clamp_signal(-2.0, 0.0, 3.0).unwrap(), 0.0);
    }

    #[test]
    fn saturates_signals() {
        assert_eq!(saturate(7.0, 5.0).unwrap(), 5.0);
        assert_eq!(saturate(-7.0, 5.0).unwrap(), -5.0);
    }

    #[test]
    fn rejects_invalid_values() {
        assert_eq!(
            ControlSignal::new(f64::NAN),
            Err(ControlSignalError::InvalidValue)
        );
        assert_eq!(
            clamp_signal(1.0, 2.0, 1.0),
            Err(ControlSignalError::InvalidBounds)
        );
        assert_eq!(
            ControlSignal::new(1.0).unwrap().scale(f64::NAN),
            Err(ControlSignalError::InvalidFactor)
        );
        assert_eq!(saturate(1.0, -1.0), Err(ControlSignalError::InvalidBounds));
    }
}