cantools 0.2.1

CAN-bus data analysis library
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

//! Module providing utility traits for decoding CAN-bus data.
//!
//! The module provides three traits: [TryDecode], [DefaultDecode], and [Decode].
//! [try_decode](TryDecode::try_decode) models the possibility of the decoding to fail.
//! [default_decode](DefaultDecode::default_decode) returns a default value if the decoding fails.
//! Finally, [decode](Decode::decode) panics if the internal decoding fails. Otherwise, it returns
//! the decoded value.
//!
//! # Example
//! ```
//! use cantools::data::CANRead;
//! use cantools::signals::Bit;
//! use cantools::decode::{TryDecode, DefaultDecode, Decode};
//!
//! let bit = Bit::new(20);
//! let mut data = [1u8, 2u8, 3u8, 4u8];
//!
//! let result_1 = bit.try_decode(&data);
//! let result_2 = bit.default_decode(&data);
//! let result_3 = bit.decode(&data);
//! ```

use crate::data::CANRead;

/// Type representing possible decoding errors.
#[derive(Debug, PartialEq)]
pub enum DecodeError {
    /// There is not enough byte data available from which one can decode a value.
    NotEnoughData,
}

/// A trait modeling the failable decoding of data.
pub trait TryDecode<T> {
    /// A type modeling the different possible failures of the decoding.
    type Error;

    /// Tries to decode a value.
    fn try_decode<D: CANRead>(&self, data: &D) -> Result<T, Self::Error>;
}

/// A trait modeling the failable decoding of data.
pub trait DefaultDecode<T: Default>: TryDecode<T> {
    /// Tries to decode a value. If the data is not decodable, a default value is returned.
    /// Otherwise, the decoded value is returned.
    fn default_decode<D: CANRead>(&self, data: &D) -> T {
        match self.try_decode(data) {
            Ok(value) => value,
            Err(_) => T::default(),
        }
    }
}

/// A trait modeling the not failable decoding of data.
pub trait Decode<T>: TryDecode<T> {
    /// Decodes the data.
    ///
    /// # Panics
    /// If the data is not decodable internally, the call to [decode](Decode::decode) panics.
    fn decode<D: CANRead>(&self, data: &D) -> T {
        match self.try_decode(data) {
            Ok(value) => value,
            Err(_) => panic!("cannot decode data"),
        }
    }
}