spinoso_time/time/tzrs/
mod.rs

1use core::cmp::Ordering;
2use core::hash::{Hash, Hasher};
3
4use tz::datetime::DateTime;
5
6mod build;
7mod convert;
8mod error;
9mod math;
10mod offset;
11mod parts;
12mod strftime;
13mod timezone;
14mod to_a;
15
16pub use error::{IntOverflowError, TimeError, TzOutOfRangeError, TzStringError};
17pub use offset::{MAX_OFFSET_SECONDS, MIN_OFFSET_SECONDS, Offset};
18pub use to_a::ToA;
19
20/// Alias for [`std::result::Result`] with the unified [`TimeError`].
21pub type Result<T> = std::result::Result<T, TimeError>;
22
23use crate::NANOS_IN_SECOND;
24
25/// Implementation of Ruby [`Time`], a timezone-aware datetime, based on
26/// [`tz-rs`] and [`tzdb`].
27///
28/// `Time` is represented as:
29///
30/// - a 64-bit signed integer of seconds since January 1, 1970 UTC (a Unix
31///   timestamp).
32/// - an unsigned 32-bit integer of nanoseconds since the timestamp.
33/// - An offset from UTC. See [`Offset`] for the types of supported offsets.
34///
35/// This data structure allows representing roughly 584 billion years. Unlike
36/// MRI, there is no promotion to `Bignum` or `Rational`. The maximum
37/// granularity of a `Time` object is nanoseconds.
38///
39/// # Examples
40///
41/// ```
42/// # use spinoso_time::tzrs::{Time, TimeError};
43/// # fn example() -> Result<(), TimeError> {
44/// // Create a Time to the current system clock with local offset
45/// let time = Time::now()?;
46/// assert!(!time.is_utc());
47/// println!("{}", time.is_sunday());
48/// # Ok(())
49/// # }
50/// # example().unwrap();
51/// ```
52///
53/// ```
54/// # use spinoso_time::tzrs::{Time, TimeError};
55/// # fn example() -> Result<(), TimeError> {
56/// let time = Time::now()?;
57/// let one_hour_ago: Time = time.checked_sub_u64(60 * 60)?;
58/// assert_eq!(time.to_int() - 3600, one_hour_ago.to_int());
59/// assert_eq!(time.nanoseconds(), one_hour_ago.nanoseconds());
60/// # Ok(())
61/// # }
62/// # example().unwrap();
63/// ```
64///
65/// [`tz-rs`]: tz
66/// [`Time`]: https://ruby-doc.org/core-3.1.2/Time.html
67#[must_use]
68#[derive(Debug, Clone, Copy)]
69pub struct Time {
70    /// A wrapper around [`tz::datetime::DateTime`] to provide date and time
71    /// formatting.
72    inner: DateTime,
73    /// The offset to used for the provided _time_.
74    offset: Offset,
75}
76
77impl Hash for Time {
78    #[inline]
79    fn hash<H: Hasher>(&self, state: &mut H) {
80        // Hash is only based on the nanos since epoch:
81        //
82        // ```console
83        // [3.1.2] > t = Time.now
84        // => 2022-06-26 14:41:03.192545 -0700
85        // [3.1.2] > t.zone
86        // => "PDT"
87        // [3.1.2] > t.hash
88        // => 3894887943343456722
89        // [3.1.2] > u = t.utc
90        // => 2022-06-26 21:41:03.192545 UTC
91        // [3.1.2] > u.zone
92        // => "UTC"
93        // [3.1.2] > u.hash
94        // => 3894887943343456722
95        // ```
96        state.write_i128(self.inner.total_nanoseconds());
97    }
98}
99
100impl PartialEq for Time {
101    fn eq(&self, other: &Time) -> bool {
102        self.inner.total_nanoseconds() == other.inner.total_nanoseconds()
103    }
104}
105
106impl Eq for Time {}
107
108impl PartialOrd for Time {
109    fn partial_cmp(&self, other: &Self) -> Option<Ordering> {
110        Some(self.cmp(other))
111    }
112}
113
114impl Ord for Time {
115    fn cmp(&self, other: &Self) -> Ordering {
116        self.inner.total_nanoseconds().cmp(&other.inner.total_nanoseconds())
117    }
118}
119
120// constructors
121impl Time {
122    /// Returns a new Time from the given values in the provided `offset`.
123    ///
124    /// Can be used to implement the Ruby method [`Time#new`] (using a
125    /// [`Timezone`] Object).
126    ///
127    /// **Note**: During DST transitions, a specific time can be ambiguous. This
128    /// method will always pick the latest date.
129    ///
130    /// # Examples
131    ///
132    /// ```
133    /// # use spinoso_time::tzrs::{Time, Offset, TimeError};
134    /// # fn example() -> Result<(), TimeError> {
135    /// let offset = Offset::try_from("+1200")?;
136    /// let t = Time::new(2022, 9, 25, 1, 30, 0, 0, offset);
137    /// # Ok(())
138    /// # }
139    /// # example().unwrap();
140    /// ```
141    ///
142    /// # Errors
143    ///
144    /// Can produce a [`TimeError`], generally when provided values are out of range.
145    ///
146    /// [`Time#new`]: https://ruby-doc.org/core-3.1.2/Time.html#method-c-new
147    /// [`Timezone`]: https://ruby-doc.org/core-3.1.2/Time.html#class-Time-label-Timezone+argument
148    #[inline]
149    #[expect(clippy::too_many_arguments, reason = "Implementing a Ruby constructor")]
150    pub fn new(
151        year: i32,
152        month: u8,
153        day: u8,
154        hour: u8,
155        minute: u8,
156        second: u8,
157        nanoseconds: u32,
158        offset: Offset,
159    ) -> Result<Self> {
160        let tz = offset.time_zone_ref();
161        let found_date_times = DateTime::find(year, month, day, hour, minute, second, nanoseconds, tz)?;
162
163        // According to the `tz-rs` author, `FoundDateTimeList::latest` and
164        // `FoundDateTimeList::first` can return `None` if the provided time
165        // zone has no extra rule and the date time would be located after the
166        // last transition.
167        //
168        // This situation can happen when using a TZif v1 file, which cannot
169        // contain a footer with an extra rule definition. If you are using the
170        // last version of the Time Zone Database, all TZif v1 files have been
171        // replaced by TZif v2 or v3 files, so this error should be uncommon.
172        //
173        // As of `tzdb` 0.4.0, the Time Zone Database is version `2022a` which has
174        // this property, which means an `expect` below can never panic, however
175        // upstream has provided a test case which means we have a test that
176        // simulates this failure condition and requires us to handle it.
177        //
178        // See: https://github.com/x-hgg-x/tz-rs/issues/34#issuecomment-1206140198
179        let dt = found_date_times.latest().ok_or(TimeError::Unknown)?;
180        Ok(Self { inner: dt, offset })
181    }
182
183    /// Returns a Time with the current time in the System Timezone.
184    ///
185    /// Can be used to implement the Ruby method [`Time#now`].
186    ///
187    /// # Examples
188    ///
189    /// ```
190    /// # use spinoso_time::tzrs::{Time, Offset, TimeError};
191    /// # fn example() -> Result<(), TimeError> {
192    /// let now = Time::now()?;
193    /// # Ok(())
194    /// # }
195    /// # example().unwrap();
196    /// ```
197    ///
198    /// # Errors
199    ///
200    /// Can produce a [`TimeError`], however these should never been seen in regular usage.
201    ///
202    /// [`Time#now`]: https://ruby-doc.org/core-3.1.2/Time.html#method-c-now
203    #[inline]
204    pub fn now() -> Result<Self> {
205        let offset = Offset::local();
206        let time_zone_ref = offset.time_zone_ref();
207        let now = DateTime::now(time_zone_ref)?;
208        Ok(Self { inner: now, offset })
209    }
210
211    /// Returns a Time in the given timezone with the number of `seconds` and
212    /// `nanoseconds` since the Epoch in the specified timezone.
213    ///
214    /// Can be used to implement the Ruby method [`Time#at`].
215    ///
216    /// # Examples
217    ///
218    /// ```
219    /// # use spinoso_time::tzrs::{Time, Offset, TimeError};
220    /// # fn example() -> Result<(), TimeError> {
221    /// let offset = Offset::utc();
222    /// let t = Time::with_timespec_and_offset(0, 0, offset)?;
223    /// assert_eq!(t.to_int(), 0);
224    /// # Ok(())
225    /// # }
226    /// # example().unwrap();
227    /// ```
228    ///
229    /// # Errors
230    ///
231    /// Can produce a [`TimeError`], however these should not be seen during regular usage.
232    ///
233    /// [`Time#at`]: https://ruby-doc.org/core-3.1.2/Time.html#method-c-at
234    #[inline]
235    pub fn with_timespec_and_offset(seconds: i64, nanoseconds: u32, offset: Offset) -> Result<Self> {
236        let time_zone_ref = offset.time_zone_ref();
237        let dt = DateTime::from_timespec(seconds, nanoseconds, time_zone_ref)?;
238        Ok(Self { inner: dt, offset })
239    }
240}
241
242impl TryFrom<ToA> for Time {
243    type Error = TimeError;
244
245    /// Create a new Time object base on a `ToA`
246    ///
247    /// **Note**: This converting from a Time object to a `ToA` and back again
248    /// is lossy since `ToA` does not store nanoseconds.
249    ///
250    /// # Examples
251    ///
252    /// ```
253    /// # use spinoso_time::tzrs::{Time, Offset, TimeError};
254    /// # fn example() -> Result<(), TimeError> {
255    /// let now = Time::local(2022, 7, 8, 12, 34, 56, 1000)?;
256    /// let to_a = now.to_array();
257    /// let from_to_a = Time::try_from(to_a)?;
258    /// assert_eq!(now.second(), from_to_a.second());
259    /// assert_ne!(now.nanoseconds(), from_to_a.nanoseconds());
260    /// # Ok(())
261    /// # }
262    /// # example().unwrap();
263    /// ```
264    ///
265    /// # Errors
266    ///
267    /// Can produce a [`TimeError`], generally when provided values are out of range.
268    #[inline]
269    fn try_from(to_a: ToA) -> Result<Self> {
270        let offset = Offset::try_from(to_a.zone).unwrap_or_else(|_| Offset::utc());
271
272        Self::new(
273            to_a.year, to_a.month, to_a.day, to_a.hour, to_a.min, to_a.sec, 0, offset,
274        )
275    }
276}
277
278// Core
279impl Time {
280    /// Returns the number of seconds as a signed integer since the Epoch.
281    ///
282    /// This function can be used to implement the Ruby methods [`Time#to_i`]
283    /// and [`Time#tv_sec`].
284    ///
285    /// # Examples
286    ///
287    /// ```
288    /// # use spinoso_time::tzrs::{Time, Offset, TimeError};
289    /// # fn example() -> Result<(), TimeError> {
290    /// let t = Time::utc(1970, 1, 1, 0, 1, 0, 0)?;
291    /// assert_eq!(t.to_int(), 60);
292    /// # Ok(())
293    /// # }
294    /// # example().unwrap();
295    /// ```
296    ///
297    /// [`Time#to_i`]: https://ruby-doc.org/core-3.1.2/Time.html#method-i-to_i
298    /// [`Time#tv_sec`]: https://ruby-doc.org/core-3.1.2/Time.html#method-i-tv_sec
299    #[inline]
300    #[must_use]
301    pub fn to_int(&self) -> i64 {
302        self.inner.unix_time()
303    }
304
305    /// Returns the number of seconds since the Epoch with fractional nanos
306    /// included at IEEE 754-2008 accuracy.
307    ///
308    /// This function can be used to implement the Ruby method [`Time#to_f`].
309    ///
310    /// # Examples
311    ///
312    /// ```
313    /// # use spinoso_time::tzrs::{Time, Offset, TimeError};
314    /// # fn example() -> Result<(), TimeError> {
315    /// let now = Time::utc(1970, 1, 1, 0, 1, 0, 1000)?;
316    /// assert_eq!(now.to_float(), 60.000001);
317    /// # Ok(())
318    /// # }
319    /// # example().unwrap();
320    /// ```
321    ///
322    /// [`Time#to_f`]: https://ruby-doc.org/core-3.1.2/Time.html#method-i-to_f
323    #[inline]
324    #[must_use]
325    pub fn to_float(&self) -> f64 {
326        // A `f64` mantissa is only 52 bits wide, so putting 64 bits in there
327        // will result in a rounding issues, however this is expected in the
328        // Ruby spec.
329        #[expect(
330            clippy::cast_precision_loss,
331            reason = "rounding issues are expected in the Ruby spec"
332        )]
333        let sec = self.to_int() as f64;
334        let nanos_fractional = f64::from(self.inner.nanoseconds()) / f64::from(NANOS_IN_SECOND);
335        sec + nanos_fractional
336    }
337
338    /// Returns the numerator and denominator for the number of nanoseconds of
339    /// the Time struct unsimplified.
340    ///
341    /// This can be used directly to implement [`Time#subsec`].
342    ///
343    /// This function can be used in combination with [`to_int`] to implement
344    /// [`Time#to_r`].
345    ///
346    /// # Examples
347    ///
348    /// ```
349    /// # use spinoso_time::tzrs::{Time, Offset, TimeError};
350    /// # fn example() -> Result<(), TimeError> {
351    /// let t = Time::utc(1970, 1, 1, 0, 0, 1, 1000)?;
352    /// assert_eq!(t.subsec_fractional(), (1000, 1000000000));
353    /// # Ok(())
354    /// # }
355    /// # example().unwrap();
356    /// ```
357    ///
358    /// [`Time#subsec`]: https://ruby-doc.org/core-3.1.2/Time.html#method-i-subsec
359    /// [`to_int`]: struct.Time.html#method.to_int
360    /// [`Time#to_r`]: https://ruby-doc.org/core-3.1.2/Time.html#method-i-to_r
361    #[inline]
362    #[must_use]
363    pub fn subsec_fractional(&self) -> (u32, u32) {
364        (self.inner.nanoseconds(), NANOS_IN_SECOND)
365    }
366}
367
368#[cfg(test)]
369mod tests {
370    use super::*;
371
372    fn time_with_fixed_offset(offset: i32) -> Time {
373        let offset = Offset::fixed(offset).unwrap();
374        Time::with_timespec_and_offset(0, 0, offset).unwrap()
375    }
376
377    #[test]
378    fn time_zone_fixed_offset() {
379        assert_eq!("-0202", time_with_fixed_offset(-7320).time_zone());
380        assert_eq!("+0000", time_with_fixed_offset(0).time_zone());
381        assert_eq!("+0000", time_with_fixed_offset(59).time_zone());
382    }
383}
spinoso_time/time/tzrs/mod.rs

spinoso_time/time/tzrs/
mod.rs
