gnss_time/
error.rs

1//! Error types for the `gnss-time` crate.
2//!
3//! This module defines the unified error type used across all fallible
4//! operations in the crate, including conversions, arithmetic, and
5//! time-scale transformations.
6//!
7//! The design follows a strict principle:
8//!
9//! - **No hidden failure modes** — all fallible operations return `Result`
10//! - **Explicit error context** — each variant describes a recoverable class of
11//!   failure
12//! - **`#[non_exhaustive]` for forward compatibility**
13
14use core::fmt;
15
16/// Errors returned by fallible `gnss-time` operations.
17///
18/// `GnssTimeError` is used throughout the crate for arithmetic overflow,
19/// invalid inputs, and missing auxiliary data (e.g. leap seconds).
20///
21/// This type is intentionally `#[non_exhaustive]` to allow new error cases
22/// without breaking semver compatibility.
23///
24/// # Usage
25///
26/// ```rust
27/// use gnss_time::GnssTimeError;
28///
29/// fn example() -> Result<(), GnssTimeError> {
30///     Err(GnssTimeError::Overflow)
31/// }
32/// ```
33#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
34#[must_use = "errors must be handled; use `?` or `match` to inspect the failure"]
35#[non_exhaustive]
36pub enum GnssTimeError {
37    /// Arithmetic overflow occurred during nanosecond-based computations.
38    ///
39    /// This indicates that an operation exceeded the representable range of
40    /// the underlying `i64` nanosecond storage.
41    Overflow,
42
43    /// The provided input value is invalid for the requested operation.
44    ///
45    /// The attached string provides a short static description of the issue.
46    InvalidInput(&'static str),
47
48    /// The operation requires leap-second information that is not available.
49    ///
50    /// This is typically required for conversions between UTC-based and
51    /// atomic time scales (e.g. GPS ↔ UTC, GLONASS ↔ GPS).
52    LeapSecondsRequired,
53}
54
55impl fmt::Display for GnssTimeError {
56    fn fmt(
57        &self,
58        f: &mut fmt::Formatter<'_>,
59    ) -> fmt::Result {
60        match self {
61            GnssTimeError::Overflow => f.write_str("arithmetic overflow in nanosecond computation"),
62            GnssTimeError::InvalidInput(msg) => {
63                write!(f, "invalid input: {msg}")
64            }
65            GnssTimeError::LeapSecondsRequired => {
66                f.write_str("leap-second data required for this conversion")
67            }
68        }
69    }
70}
71
72// `std::error::Error` impl behind the `std` feature gate.
73#[cfg(feature = "std")]
74impl std::error::Error for GnssTimeError {}
75
76// defmt support: embedded logging via probe-rs / defmt-rtt.
77#[cfg(feature = "defmt")]
78impl defmt::Format for GnssTimeError {
79    fn format(
80        &self,
81        f: defmt::Formatter,
82    ) {
83        match self {
84            GnssTimeError::Overflow => {
85                defmt::write!(f, "arithmetic overflow in nanoseconds")
86            }
87            GnssTimeError::InvalidInput(msg) => {
88                defmt::write!(f, "invalid input: {}", msg)
89            }
90            GnssTimeError::LeapSecondsRequired => {
91                defmt::write!(f, "leap-second data required")
92            }
93        }
94    }
95}
gnss_time/error.rs

gnss_time/
error.rs
