uefi: Make TimeError more descriptive

When returning a TimeError, it'd be helpful to specify to the user which field
is invalid so that it can be handled accordingly, or at least communicated. This
change does this by adding bool fields to the TimeError struct, representing the
validity of each field of a Time struct.

Author: andre-braga

uefi/CHANGELOG.md

@@ -14,6 +14,7 @@
 - Added `TryFrom<&[u8]>` for `DevicePathHeader`, `DevicePathNode` and `DevicePath`.
 - Added `ByteConversionError`.
 - Re-exported `CapsuleFlags`.
+- One can now specify in `TimeError` what fields of `Time` are outside its valid range.  `Time::is_valid` has been updated accordingly. 
 
 ## Changed
 - `SystemTable::exit_boot_services` is now `unsafe`. See that method's

uefi/src/table/runtime.rs

@@ -371,19 +371,66 @@ pub struct TimeParams {
     pub daylight: Daylight,
 }
 
-/// Error returned by [`Time`] methods if the input is outside the valid range.
-#[derive(Copy, Clone, Debug, Default, Eq, PartialEq)]
-pub struct TimeError;
+/// Error returned by [`Time`] methods. A bool value of `true` means
+/// the specified field is outside of its valid range.
+#[allow(missing_docs)]
+#[derive(Debug, Default, PartialEq, Eq)]
+pub struct TimeError {
+    pub year: bool,
+    pub month: bool,
+    pub day: bool,
+    pub hour: bool,
+    pub minute: bool,
+    pub second: bool,
+    pub nanosecond: bool,
+    pub timezone: bool,
+    pub daylight: bool,
+}
+
+#[cfg(feature = "unstable")]
+impl core::error::Error for TimeError {}
 
 impl Display for TimeError {
     fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
-        write!(f, "{self:?}")
+        if *self == TimeError::default() {
+            write!(f, "No erroneous fields found in EFI Time.")?;
+        } else {
+            write!(f, "Erroneous fields found in EFI Time:")?;
+            if self.year {
+                write!(f, "\nyear not within `1900..=9999`")?;
+            }
+            if self.month {
+                write!(f, "\nmonth not within `1..=12")?;
+            }
+            if self.day {
+                write!(f, "\nday not within `1..=31`")?;
+            }
+            if self.hour {
+                write!(f, "\nhour not within `0..=23`")?;
+            }
+            if self.minute {
+                write!(f, "\nminute not within `0..=59`")?;
+            }
+            if self.second {
+                write!(f, "\nsecond not within `0..=59`")?;
+            }
+            if self.nanosecond {
+                write!(f, "\nnanosecond not within `0..=999_999_999`")?;
+            }
+            if self.timezone {
+                write!(
+                    f,
+                    "\ntime_zone not `Time::UNSPECIFIED_TIMEZONE` nor within `-1440..=1440`"
+                )?;
+            }
+            if self.daylight {
+                write!(f, "\nunknown bits set for daylight")?;
+            }
+        }
+        Ok(())
     }
 }
 
-#[cfg(feature = "unstable")]
-impl core::error::Error for TimeError {}
-
 impl Time {
     /// Unspecified Timezone/local time.
     const UNSPECIFIED_TIMEZONE: i16 = uefi_raw::time::Time::UNSPECIFIED_TIMEZONE;
@@ -404,11 +451,8 @@ impl Time {
             daylight: params.daylight,
             pad2: 0,
         });
-        if time.is_valid() {
-            Ok(time)
-        } else {
-            Err(TimeError)
-        }
+
+        time.is_valid().map(|_| time)
     }
 
     /// Create an invalid `Time` with all fields set to zero. This can
@@ -422,10 +466,38 @@ impl Time {
         Self(uefi_raw::time::Time::invalid())
     }
 
-    /// True if all fields are within valid ranges, false otherwise.
-    #[must_use]
-    pub fn is_valid(&self) -> bool {
-        self.0.is_valid()
+    /// `Ok()` if all fields are within valid ranges, `Err(TimeError)` otherwise.
+    pub fn is_valid(&self) -> core::result::Result<(), TimeError> {
+        let mut err = TimeError::default();
+        if !(1900..=9999).contains(&self.year()) {
+            err.year = true;
+        }
+        if !(1..=12).contains(&self.month()) {
+            err.month = true;
+        }
+        if !(1..=31).contains(&self.day()) {
+            err.day = true;
+        }
+        if self.hour() > 23 {
+            err.hour = true;
+        }
+        if self.minute() > 59 {
+            err.minute = true;
+        }
+        if self.second() > 59 {
+            err.second = true;
+        }
+        if self.nanosecond() > 999_999_999 {
+            err.nanosecond = true;
+        }
+        if self.time_zone().is_some() && !((-1440..=1440).contains(&self.time_zone().unwrap())) {
+            err.timezone = true;
+        }
+        if err == TimeError::default() {
+            Ok(())
+        } else {
+            Err(err)
+        }
     }
 
     /// Query the year.