1//! CAN Identifiers.
2
3/// Standard 11-bit CAN Identifier (`0..=0x7FF`).
4#[derive(Debug, Copy, Clone, Eq, PartialEq, PartialOrd, Ord, Hash)]
5pub struct StandardId(u16);
6
7impl StandardId {
8 /// CAN ID `0`, the highest priority.
9 pub const ZERO: Self = Self(0);
10
11 /// CAN ID `0x7FF`, the lowest priority.
12 pub const MAX: Self = Self(0x7FF);
13
14 /// Tries to create a `StandardId` from a raw 16-bit integer.
15 ///
16 /// This will return `None` if `raw` is out of range of an 11-bit integer (`> 0x7FF`).
17 #[inline]
18 pub const fn new(raw: u16) -> Option<Self> {
19 if raw <= 0x7FF {
20 Some(Self(raw))
21 } else {
22 None
23 }
24 }
25
26 /// Creates a new `StandardId` without checking if it is inside the valid range.
27 ///
28 /// # Safety
29 /// Using this method can create an invalid ID and is thus marked as unsafe.
30 #[inline]
31 pub const unsafe fn new_unchecked(raw: u16) -> Self {
32 Self(raw)
33 }
34
35 /// Returns this CAN Identifier as a raw 16-bit integer.
36 #[inline]
37 pub fn as_raw(&self) -> u16 {
38 self.0
39 }
40}
41
42/// Extended 29-bit CAN Identifier (`0..=1FFF_FFFF`).
43#[derive(Debug, Copy, Clone, Eq, PartialEq, PartialOrd, Ord, Hash)]
44pub struct ExtendedId(u32);
45
46impl ExtendedId {
47 /// CAN ID `0`, the highest priority.
48 pub const ZERO: Self = Self(0);
49
50 /// CAN ID `0x1FFFFFFF`, the lowest priority.
51 pub const MAX: Self = Self(0x1FFF_FFFF);
52
53 /// Tries to create a `ExtendedId` from a raw 32-bit integer.
54 ///
55 /// This will return `None` if `raw` is out of range of an 29-bit integer (`> 0x1FFF_FFFF`).
56 #[inline]
57 pub const fn new(raw: u32) -> Option<Self> {
58 if raw <= 0x1FFF_FFFF {
59 Some(Self(raw))
60 } else {
61 None
62 }
63 }
64
65 /// Creates a new `ExtendedId` without checking if it is inside the valid range.
66 ///
67 /// # Safety
68 /// Using this method can create an invalid ID and is thus marked as unsafe.
69 #[inline]
70 pub const unsafe fn new_unchecked(raw: u32) -> Self {
71 Self(raw)
72 }
73
74 /// Returns this CAN Identifier as a raw 32-bit integer.
75 #[inline]
76 pub fn as_raw(&self) -> u32 {
77 self.0
78 }
79
80 /// Returns the Base ID part of this extended identifier.
81 pub fn standard_id(&self) -> StandardId {
82 // ID-28 to ID-18
83 StandardId((self.0 >> 18) as u16)
84 }
85}
86
87/// A CAN Identifier (standard or extended).
88#[derive(Debug, Copy, Clone, Eq, PartialEq, Hash)]
89pub enum Id {
90 /// Standard 11-bit Identifier (`0..=0x7FF`).
91 Standard(StandardId),
92
93 /// Extended 29-bit Identifier (`0..=0x1FFF_FFFF`).
94 Extended(ExtendedId),
95}
96
97/// Implement `Ord` according to the CAN arbitration rules
98///
99/// When performing arbitration, frames are looked at bit for bit starting
100/// from the beginning. A bit with the value 0 is dominant and a bit with
101/// value of 1 is recessive.
102///
103/// When two devices are sending frames at the same time, as soon as the first
104/// bit is found which differs, the frame with the corresponding dominant
105/// 0 bit will win and get to send the rest of the frame.
106///
107/// This implementation of `Ord` for `Id` will take this into consideration
108/// and when comparing two different instances of `Id` the "smallest" will
109/// always be the ID which would form the most dominant frame, all other
110/// things being equal.
111impl Ord for Id {
112 fn cmp(&self, other: &Self) -> core::cmp::Ordering {
113 let split_id: impl Fn(&Id) -> (u16, i32, …) = |id: &Id| {
114 let (standard_id_part: u16, ide_bit: i32, extended_id_part: u32) = match id {
115 Id::Standard(StandardId(x: &u16)) => (*x, 0, 0),
116 Id::Extended(x: &ExtendedId) => (
117 x.standard_id().0,
118 1,
119 x.0 & ((1 << 18) - 1), // Bit ID-17 to ID-0
120 ),
121 };
122 (standard_id_part, ide_bit, extended_id_part)
123 };
124
125 split_id(self).cmp(&split_id(id:other))
126 }
127}
128
129impl PartialOrd for Id {
130 fn partial_cmp(&self, other: &Id) -> Option<core::cmp::Ordering> {
131 Some(self.cmp(other))
132 }
133}
134
135impl From<StandardId> for Id {
136 #[inline]
137 fn from(id: StandardId) -> Self {
138 Id::Standard(id)
139 }
140}
141
142impl From<ExtendedId> for Id {
143 #[inline]
144 fn from(id: ExtendedId) -> Self {
145 Id::Extended(id)
146 }
147}
148
149#[cfg(test)]
150mod tests {
151 use super::*;
152
153 #[test]
154 fn standard_id_new() {
155 assert_eq!(
156 StandardId::new(StandardId::MAX.as_raw()),
157 Some(StandardId::MAX)
158 );
159 }
160
161 #[test]
162 fn standard_id_new_out_of_range() {
163 assert_eq!(StandardId::new(StandardId::MAX.as_raw() + 1), None);
164 }
165
166 #[test]
167 fn standard_id_new_unchecked_out_of_range() {
168 let id = StandardId::MAX.as_raw() + 1;
169 assert_eq!(unsafe { StandardId::new_unchecked(id) }, StandardId(id));
170 }
171
172 #[test]
173 fn extended_id_new() {
174 assert_eq!(
175 ExtendedId::new(ExtendedId::MAX.as_raw()),
176 Some(ExtendedId::MAX)
177 );
178 }
179
180 #[test]
181 fn extended_id_new_out_of_range() {
182 assert_eq!(ExtendedId::new(ExtendedId::MAX.as_raw() + 1), None);
183 }
184
185 #[test]
186 fn extended_id_new_unchecked_out_of_range() {
187 let id = ExtendedId::MAX.as_raw() + 1;
188 assert_eq!(unsafe { ExtendedId::new_unchecked(id) }, ExtendedId(id));
189 }
190
191 #[test]
192 fn get_standard_id_from_extended_id() {
193 assert_eq!(
194 Some(ExtendedId::MAX.standard_id()),
195 StandardId::new((ExtendedId::MAX.0 >> 18) as u16)
196 );
197 }
198
199 #[test]
200 fn cmp_id() {
201 assert!(StandardId::ZERO < StandardId::MAX);
202 assert!(ExtendedId::ZERO < ExtendedId::MAX);
203
204 assert!(Id::Standard(StandardId::ZERO) < Id::Extended(ExtendedId::ZERO));
205 assert!(Id::Extended(ExtendedId::ZERO) < Id::Extended(ExtendedId::MAX));
206 assert!(Id::Extended(ExtendedId((1 << 11) - 1)) < Id::Standard(StandardId(1)));
207 assert!(Id::Standard(StandardId(1)) < Id::Extended(ExtendedId::MAX));
208 }
209}
210