spinoso_time/time/tzrs/
error.rs

1#![allow(clippy::module_name_repetitions)]
2
3use core::fmt;
4use core::num::TryFromIntError;
5use core::time::TryFromFloatSecsError;
6use std::error;
7use std::str::Utf8Error;
8
9use tz::error::TzError;
10use tz::error::datetime::DateTimeError;
11use tz::error::timezone::LocalTimeTypeError;
12
13/// A wrapper around some of the errors provided by `tz-rs`.
14#[derive(Debug)]
15pub enum TimeError {
16    /// Created when trying to create a `DateTime`, however the local time zone
17    /// designation is malformed.
18    LocalTimeType(LocalTimeTypeError),
19
20    /// Created when one of the parameters of a `DateTime` falls outside the
21    /// allowed ranges (e.g. 13th month, 32 day, 24th hour, etc).
22    ///
23    /// Note: [`tz::error::datetime::DateTimeError`] is only thrown from `tz-rs`
24    /// when a provided component value is out of range.
25    ///
26    /// Note: This is different from how MRI ruby is implemented. e.g. Second
27    /// 60 is valid in MRI, and will just add an additional second instead of
28    /// erroring.
29    ComponentOutOfRangeError(DateTimeError),
30
31    /// A rescuable error originally from the `tz-rs` library.
32    UnknownTzError(TzError),
33
34    /// Indicates that there was an issue when parsing a string for an offset.
35    TzStringError(TzStringError),
36
37    /// The provided tz offset seconds offset is outside of the allowed range.
38    TzOutOfRangeError(TzOutOfRangeError),
39
40    /// A rescuable Integer overflow error. Caused when trying to exceed the
41    /// bounds of an int.
42    IntOverflowError(IntOverflowError),
43
44    /// An rescuable unknown error (instead of panicking).
45    Unknown,
46}
47
48impl error::Error for TimeError {
49    fn source(&self) -> Option<&(dyn error::Error + 'static)> {
50        match self {
51            Self::LocalTimeType(err) => Some(err),
52            Self::ComponentOutOfRangeError(err) => Some(err),
53            Self::UnknownTzError(err) => Some(err),
54            Self::TzStringError(err) => Some(err),
55            Self::TzOutOfRangeError(err) => Some(err),
56            Self::IntOverflowError(err) => Some(err),
57            Self::Unknown => None,
58        }
59    }
60}
61
62impl fmt::Display for TimeError {
63    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
64        match self {
65            Self::LocalTimeType(error) => error.fmt(f),
66            Self::ComponentOutOfRangeError(error) => error.fmt(f),
67            Self::UnknownTzError(error) => error.fmt(f),
68            Self::TzStringError(error) => error.fmt(f),
69            Self::TzOutOfRangeError(error) => error.fmt(f),
70            Self::IntOverflowError(error) => error.fmt(f),
71            Self::Unknown => write!(f, "An unknown error occurred"),
72        }
73    }
74}
75
76impl From<LocalTimeTypeError> for TimeError {
77    fn from(err: LocalTimeTypeError) -> Self {
78        Self::LocalTimeType(err)
79    }
80}
81
82impl From<DateTimeError> for TimeError {
83    fn from(err: DateTimeError) -> Self {
84        Self::ComponentOutOfRangeError(err)
85    }
86}
87
88impl From<TzError> for TimeError {
89    fn from(error: TzError) -> Self {
90        #[expect(clippy::match_same_arms, reason = "for documentation on each arm")]
91        match error {
92            // These two are generally recoverable within the usable of `spinoso_time`
93            TzError::DateTime(error) => Self::from(error),
94            TzError::LocalTimeType(error) => Self::from(error),
95
96            // The rest will bleed through, but are included here for reference
97            //
98            // Occurs when there is no available local time type for the given timestamp.
99            TzError::NoAvailableLocalTimeType => Self::UnknownTzError(error),
100            // Occurs during int conversion (e.g. `i64` => `i32`)
101            TzError::OutOfRange => Self::UnknownTzError(error),
102            // Occurs during creation of `TimeZoneRef`
103            TzError::TimeZone(_) => Self::UnknownTzError(error),
104            // Occurs during creation of `TimeZoneRef`
105            TzError::TransitionRule(_) => Self::UnknownTzError(error),
106            // Occurs during parsing of TZif files
107            TzError::TzFile(_) => Self::UnknownTzError(error),
108            // Occurs during parsing of TZif files (POSIX string parsing)
109            TzError::TzString(_) => Self::UnknownTzError(error),
110            _ => Self::Unknown,
111        }
112    }
113}
114
115impl From<TzStringError> for TimeError {
116    fn from(err: TzStringError) -> Self {
117        Self::TzStringError(err)
118    }
119}
120
121impl From<TzOutOfRangeError> for TimeError {
122    fn from(err: TzOutOfRangeError) -> Self {
123        Self::TzOutOfRangeError(err)
124    }
125}
126
127impl From<IntOverflowError> for TimeError {
128    fn from(err: IntOverflowError) -> Self {
129        Self::IntOverflowError(err)
130    }
131}
132
133impl From<TryFromFloatSecsError> for TimeError {
134    fn from(err: TryFromFloatSecsError) -> Self {
135        Self::TzOutOfRangeError(err.into())
136    }
137}
138
139/// Error that indicates that the provided string cannot be used in the creation
140/// of a timezone.
141///
142/// This error is returned by [`Offset::try_from`].
143///
144/// [`Offset::try_from`]: super::Offset::try_from
145#[derive(Debug, Clone, Copy, Hash, PartialEq, Eq, PartialOrd, Ord)]
146pub struct TzStringError {
147    _private: (),
148}
149
150impl fmt::Display for TzStringError {
151    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> Result<(), fmt::Error> {
152        f.write_str(r#""+HH:MM", "-HH:MM", "UTC" or "A".."I","K".."Z" expected for utc_offset"#)
153    }
154}
155impl error::Error for TzStringError {}
156
157impl TzStringError {
158    // This error is not to be constructed outside of this crate.
159    pub(crate) const fn new() -> Self {
160        Self { _private: () }
161    }
162}
163
164impl From<Utf8Error> for TzStringError {
165    fn from(_: Utf8Error) -> Self {
166        TzStringError::new()
167    }
168}
169
170/// Error that indicates that a provided value is outside the allowed range of
171/// values. Generally seen when constructing an offset that is greater than the
172/// allowed range.
173///
174/// This error is returned by [`Offset::try_from`].
175///
176/// [`Offset::try_from`]: super::Offset::try_from
177#[derive(Debug, Clone, Copy, Hash, PartialEq, Eq, PartialOrd, Ord)]
178pub struct TzOutOfRangeError {
179    _private: (),
180}
181
182impl fmt::Display for TzOutOfRangeError {
183    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> Result<(), fmt::Error> {
184        f.write_str("utc_offset out of range")
185    }
186}
187
188impl error::Error for TzOutOfRangeError {}
189
190impl TzOutOfRangeError {
191    // This error is not to be constructed outside of this crate.
192    pub(crate) const fn new() -> Self {
193        Self { _private: () }
194    }
195}
196
197impl From<TryFromFloatSecsError> for TzOutOfRangeError {
198    fn from(_err: TryFromFloatSecsError) -> Self {
199        Self::new()
200    }
201}
202
203/// Error that indicates a given operation has resulted in an integer overflow.
204#[derive(Debug, Clone, Copy, Hash, PartialEq, Eq, PartialOrd, Ord)]
205pub struct IntOverflowError {
206    _private: (),
207}
208
209impl fmt::Display for IntOverflowError {
210    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> Result<(), fmt::Error> {
211        f.write_str("out of int range")
212    }
213}
214
215impl error::Error for IntOverflowError {}
216
217impl IntOverflowError {
218    // This error is not to be constructed outside of this crate.
219    pub(crate) const fn new() -> Self {
220        Self { _private: () }
221    }
222}
223
224impl From<TryFromIntError> for TimeError {
225    fn from(_: TryFromIntError) -> Self {
226        Self::IntOverflowError(IntOverflowError::new())
227    }
228}
spinoso_time/time/tzrs/error.rs

spinoso_time/time/tzrs/
error.rs
