CAN: returning Result instead of Option (#741)

.github/workflows/test.yml

@@ -42,5 +42,5 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      - uses: dtolnay/rust-toolchain@1.83
+      - uses: dtolnay/rust-toolchain@1.85
       - run: cargo test --workspace --all-features

embedded-can/Cargo.toml

@@ -2,7 +2,7 @@
 name = "embedded-can"
 version = "0.4.1"
 edition = "2021"
-rust-version = "1.83"
+rust-version = "1.85"
 
 description = "HAL traits for Controller Area Network (CAN) devices."
 categories = ["embedded", "hardware-support", "no-std"]

embedded-can/src/id.rs

@@ -1,5 +1,8 @@
 //! CAN Identifiers.
 
+// Import ErrorKind to return standard CAN validation errors from ID constructors
+use crate::ErrorKind;
+
 /// Standard 11-bit CAN Identifier (`0..=0x7FF`).
 #[derive(Debug, Copy, Clone, Eq, PartialEq, PartialOrd, Ord, Hash)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
@@ -14,14 +17,13 @@ impl StandardId {
 
     /// Tries to create a `StandardId` from a raw 16-bit integer.
     ///
-    /// This will return `None` if `raw` is out of range of an 11-bit integer (`> 0x7FF`).
+    /// This will return an error if `raw` is out of range of an 11-bit integer (`> 0x7FF`).
     #[inline]
-    #[must_use]
-    pub const fn new(raw: u16) -> Option<Self> {
+    pub const fn new(raw: u16) -> Result<Self, ErrorKind> {
         if raw <= 0x7FF {
-            Some(Self(raw))
+            Ok(Self(raw))
         } else {
-            None
+            Err(ErrorKind::InvalidId)
         }
     }
 
@@ -55,19 +57,17 @@ impl ExtendedId {
     /// CAN ID `0x1FFFFFFF`, the lowest priority.
     pub const MAX: Self = Self(0x1FFF_FFFF);
 
-    /// Tries to create a `ExtendedId` from a raw 32-bit integer.
+    /// Tries to create an `ExtendedId` from a raw 32-bit integer.
     ///
-    /// This will return `None` if `raw` is out of range of an 29-bit integer (`> 0x1FFF_FFFF`).
+    /// This will return an error if `raw` is out of range of a 29-bit integer (`> 0x1FFF_FFFF`).
     #[inline]
-    #[must_use]
-    pub const fn new(raw: u32) -> Option<Self> {
+    pub const fn new(raw: u32) -> Result<Self, ErrorKind> {
         if raw <= 0x1FFF_FFFF {
-            Some(Self(raw))
+            Ok(Self(raw))
         } else {
-            None
+            Err(ErrorKind::InvalidId)
         }
     }
-
     /// Creates a new `ExtendedId` without checking if it is inside the valid range.
     ///
     /// # Safety
@@ -180,17 +180,21 @@ mod tests {
 
     #[test]
     fn standard_id_new() {
+        // Test that a valid standard ID is successfully created
         assert_eq!(
             StandardId::new(StandardId::MAX.as_raw()),
-            Some(StandardId::MAX)
+            Ok(StandardId::MAX)
         );
     }
 
     #[test]
     fn standard_id_new_out_of_range() {
-        assert_eq!(StandardId::new(StandardId::MAX.as_raw() + 1), None);
+        // Test that creating a standard ID out of bounds returns an InvalidId error
+        assert_eq!(
+            StandardId::new(StandardId::MAX.as_raw() + 1),
+            Err(ErrorKind::InvalidId)
+        );
     }
-
     #[test]
     fn standard_id_new_unchecked_out_of_range() {
         let id = StandardId::MAX.as_raw() + 1;
@@ -199,15 +203,20 @@ mod tests {
 
     #[test]
     fn extended_id_new() {
+        // Test that a valid extended ID is successfully created
         assert_eq!(
             ExtendedId::new(ExtendedId::MAX.as_raw()),
-            Some(ExtendedId::MAX)
+            Ok(ExtendedId::MAX)
         );
     }
 
     #[test]
     fn extended_id_new_out_of_range() {
-        assert_eq!(ExtendedId::new(ExtendedId::MAX.as_raw() + 1), None);
+        // Test that creating an extended ID out of bounds returns an InvalidId error
+        assert_eq!(
+            ExtendedId::new(ExtendedId::MAX.as_raw() + 1),
+            Err(ErrorKind::InvalidId)
+        );
     }
 
     #[test]
@@ -218,9 +227,10 @@ mod tests {
 
     #[test]
     fn get_standard_id_from_extended_id() {
+        // Test extracting standard ID from extended ID using Result unwrap
         assert_eq!(
-            Some(ExtendedId::MAX.standard_id()),
-            StandardId::new((ExtendedId::MAX.0 >> 18) as u16)
+            ExtendedId::MAX.standard_id(),
+            StandardId::new((ExtendedId::MAX.0 >> 18) as u16).unwrap()
         );
     }
 

embedded-can/src/lib.rs

@@ -14,13 +14,13 @@ pub use id::*;
 pub trait Frame: Sized {
     /// Creates a new frame.
     ///
-    /// This will return `None` if the data slice is too long.
-    fn new(id: impl Into<Id>, data: &[u8]) -> Option<Self>;
+    /// This will return an error if the data slice is too long.
+    fn new(id: impl Into<Id>, data: &[u8]) -> Result<Self, ErrorKind>;
 
     /// Creates a new remote frame (RTR bit set).
     ///
-    /// This will return `None` if the data length code (DLC) is not valid.
-    fn new_remote(id: impl Into<Id>, dlc: usize) -> Option<Self>;
+    /// This will return an error if the data length code (DLC) is not valid.
+    fn new_remote(id: impl Into<Id>, dlc: usize) -> Result<Self, ErrorKind>;
 
     /// Returns true if this frame is an extended frame.
     fn is_extended(&self) -> bool;
@@ -102,6 +102,12 @@ pub enum ErrorKind {
 
     /// A different error occurred. The original error may contain more information.
     Other,
+
+    /// The provided identifier is invalid or out of range.
+    InvalidId,
+
+    /// The data slice or DLC is too long or invalid.
+    DataTooLong,
 }
 
 impl Error for ErrorKind {
@@ -115,6 +121,10 @@ impl core::error::Error for ErrorKind {}
 impl core::fmt::Display for ErrorKind {
     fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
         match self {
+            // The provided identifier is invalid or out of range
+            Self::InvalidId => write!(f, "The provided identifier is invalid or out of range"),
+            // The data slice or DLC is too long or invalid
+            Self::DataTooLong => write!(f, "The data slice or DLC is too long or invalid"),
             Self::Overrun => write!(f, "The peripheral receive buffer was overrun"),
             Self::Bit => write!(
                 f,

embedded-hal-bus/Cargo.toml

@@ -6,7 +6,7 @@ categories = ["embedded", "hardware-support", "no-std"]
 description = "Bus/Device connection mechanisms for embedded-hal, a Hardware Abstraction Layer (HAL) for embedded systems"
 documentation = "https://docs.rs/embedded-hal-bus"
 edition = "2021"
-rust-version = "1.83"
+rust-version = "1.85"
 keywords = ["hal", "IO"]
 license = "MIT OR Apache-2.0"
 name = "embedded-hal-bus"

embedded-hal-nb/Cargo.toml

@@ -2,7 +2,7 @@
 name = "embedded-hal-nb"
 version = "1.0.0"
 edition = "2021"
-rust-version = "1.83"
+rust-version = "1.85"
 
 categories = ["embedded", "hardware-support", "no-std"]
 description = "Non-blocking Hardware Abstraction Layer (HAL) for embedded systems using the `nb` crate."

embedded-hal/Cargo.toml

@@ -8,7 +8,7 @@ categories = ["asynchronous", "embedded", "hardware-support", "no-std"]
 description = " A Hardware Abstraction Layer (HAL) for embedded systems "
 documentation = "https://docs.rs/embedded-hal"
 edition = "2021"
-rust-version = "1.83"
+rust-version = "1.85"
 keywords = ["hal", "IO"]
 license = "MIT OR Apache-2.0"
 name = "embedded-hal"

embedded-io-adapters/Cargo.toml

@@ -2,7 +2,7 @@
 name = "embedded-io-adapters"
 version = "0.7.0"
 edition = "2021"
-rust-version = "1.83"
+rust-version = "1.85"
 description = "Adapters between the `embedded-io` traits and other I/O traits"
 repository = "https://github.com/rust-embedded/embedded-hal"
 readme = "README.md"

embedded-io-async/Cargo.toml

@@ -2,7 +2,7 @@
 name = "embedded-io-async"
 version = "0.7.0"
 edition = "2021"
-rust-version = "1.83"
+rust-version = "1.85"
 description = "Async embedded IO traits"
 repository = "https://github.com/rust-embedded/embedded-hal"
 readme = "README.md"

embedded-io/Cargo.toml

@@ -2,7 +2,7 @@
 name = "embedded-io"
 version = "0.7.1"
 edition = "2021"
-rust-version = "1.83"
+rust-version = "1.85"
 description = "Embedded IO traits"
 repository = "https://github.com/rust-embedded/embedded-hal"
 readme = "README.md"