spinoso_time/time/tzrs/
offset.rs

1use std::io::{self, Write as _};
2use std::slice;
3use std::str;
4
5use tz::timezone::{LocalTimeType, TimeZoneRef};
6use tzdb::time_zone::etc::GMT;
7
8use super::error::{TimeError, TzOutOfRangeError, TzStringError};
9
10const SECONDS_IN_MINUTE: i32 = 60;
11const SECONDS_IN_HOUR: i32 = SECONDS_IN_MINUTE * 60;
12const SECONDS_IN_DAY: i32 = SECONDS_IN_HOUR * 24;
13
14/// The maximum allowed offset in seconds from UTC in the future for a fixed
15/// offset.
16///
17/// This constant has magnitude to the number of seconds in 1 day, minus 1.
18pub const MAX_OFFSET_SECONDS: i32 = SECONDS_IN_DAY - 1;
19
20/// The maximum allowed offset in seconds from UTC in the past for a fixed
21/// offset.
22///
23/// This constant has magnitude of the number of seconds in 1 day, minus 1.
24pub const MIN_OFFSET_SECONDS: i32 = -MAX_OFFSET_SECONDS;
25
26/// `tzdb` provides [`local_tz`] to get the local system timezone. If this ever
27/// fails, we can assume `GMT`. `GMT` is used instead of `UTC` since it has a
28/// [`time_zone_designation`] - which if it is an empty string, then it is
29/// considered to be a UTC time.
30///
31/// Note: this matches MRI Ruby implementation. Where `TZ="" ruby -e "puts
32/// Time::now"` will return a new _time_ with 0 offset from UTC, but still still
33/// report as a non UTC time:
34///
35/// ```console
36/// $ TZ="" ruby -e 'puts RUBY_VERSION' -e 't = Time.now' -e 'puts t' -e 'puts t.utc?'
37/// 3.1.2
38/// 2022-06-26 22:22:25 +0000
39/// false
40/// ```
41///
42/// [`local_tz`]: tzdb::local_tz
43/// [`time_zone_designation`]: tz::timezone::LocalTimeType::time_zone_designation
44#[inline]
45#[must_use]
46#[cfg(feature = "tzrs-local")]
47fn local_time_zone() -> TimeZoneRef<'static> {
48    use std::sync::LazyLock;
49
50    // Per the docs, it is suggested to cache the result of fetching the
51    // local timezone: <https://docs.rs/tzdb/latest/tzdb/fn.local_tz.html>.
52    static LOCAL_TZ: LazyLock<TimeZoneRef<'static>> = LazyLock::new(|| {
53        let tz = iana_time_zone::get_timezone().ok().and_then(tzdb::tz_by_name);
54        tz.unwrap_or(GMT)
55    });
56
57    *LOCAL_TZ
58}
59
60#[inline]
61#[must_use]
62#[cfg(not(feature = "tzrs-local"))]
63fn local_time_zone() -> TimeZoneRef<'static> {
64    GMT
65}
66
67/// Generates a [+/-]HHMM timezone format from a given number of seconds
68/// Note: the actual seconds element is effectively ignored here
69#[inline]
70fn offset_hhmm_from_seconds(seconds: i32, buf: &mut [u8; 5]) -> io::Result<()> {
71    let flag = if seconds < 0 { '-' } else { '+' };
72    let minutes = seconds.abs() / 60;
73
74    let offset_hours = minutes / 60;
75    let offset_minutes = minutes - (offset_hours * 60);
76
77    write!(buf.as_mut_slice(), "{flag}{offset_hours:0>2}{offset_minutes:0>2}")
78}
79
80/// Represents the number of seconds offset from UTC.
81#[derive(Debug, Copy, Clone, PartialEq, Eq)]
82pub struct Offset {
83    inner: OffsetType,
84}
85
86/// Represents the type of offset from UTC.
87#[allow(variant_size_differences)]
88#[derive(Debug, Copy, Clone, PartialEq, Eq)]
89enum OffsetType {
90    /// UTC offset, zero offset, Zulu time
91    Utc,
92    /// Fixed offset from UTC.
93    ///
94    /// **Note**: A fixed offset of 0 is different from UTC time.
95    Fixed(LocalTimeType),
96    /// A time zone based offset.
97    Tz(TimeZoneRef<'static>),
98}
99
100impl Offset {
101    /// Generate a UTC based offset.
102    ///
103    /// # Examples
104    ///
105    /// ```
106    /// # use spinoso_time::tzrs::{Offset, Time, TimeError};
107    /// # fn example() -> Result<(), TimeError> {
108    /// let offset = Offset::utc();
109    /// assert!(offset.is_utc());
110    ///
111    /// let time = Time::new(2022, 7, 29, 12, 36, 0, 0, offset)?;
112    /// assert!(time.is_utc());
113    /// # Ok(())
114    /// # }
115    /// # example().unwrap();
116    /// ```
117    #[inline]
118    #[must_use]
119    pub fn utc() -> Self {
120        Self { inner: OffsetType::Utc }
121    }
122
123    /// Generate an offset based on the detected local time zone of the system.
124    ///
125    /// Detection is done by [`tzdb::local_tz`], and if it fails will return a
126    /// GMT timezone.
127    ///
128    /// The system timezone is detected on the first call to this function and
129    /// will be constant for the life of the program.
130    ///
131    /// # Examples
132    ///
133    /// ```
134    /// # use spinoso_time::tzrs::{Offset, Time, TimeError};
135    /// # fn example() -> Result<(), TimeError> {
136    /// let offset = Offset::local();
137    /// assert!(!offset.is_utc());
138    ///
139    /// let time = Time::new(2022, 7, 29, 12, 36, 0, 0, offset)?;
140    /// assert!(!time.is_utc());
141    /// # Ok(())
142    /// # }
143    /// # example().unwrap();
144    /// ```
145    ///
146    /// [`tzdb::local_tz`]: https://docs.rs/tzdb/latest/tzdb/fn.local_tz.html
147    #[inline]
148    #[must_use]
149    pub fn local() -> Self {
150        let local_tz = local_time_zone();
151        let offset = OffsetType::Tz(local_tz);
152        Self { inner: offset }
153    }
154
155    /// Generate an offset with a number of seconds from UTC.
156    ///
157    /// # Examples
158    ///
159    /// ```
160    /// # use spinoso_time::tzrs::{Offset, Time, TimeError};
161    /// # fn example() -> Result<(), TimeError> {
162    /// let offset = Offset::fixed(6600)?; // +0150
163    /// assert!(!offset.is_utc());
164    ///
165    /// let time = Time::new(2022, 7, 29, 12, 36, 0, 0, offset)?;
166    /// assert!(!time.is_utc());
167    /// # Ok(())
168    /// # }
169    /// # example().unwrap();
170    /// ```
171    ///
172    /// The offset must be in range:
173    ///
174    /// ```
175    /// # use spinoso_time::tzrs::Offset;
176    /// let offset = Offset::fixed(500_000); // +0150
177    /// assert!(offset.is_err());
178    /// ```
179    ///
180    /// # Errors
181    ///
182    /// Return a [`TimeError::TzOutOfRangeError`] when outside of range of
183    /// acceptable offset of [`MIN_OFFSET_SECONDS`] to [`MAX_OFFSET_SECONDS`].
184    #[inline]
185    #[allow(
186        clippy::missing_panics_doc,
187        reason = "Creating `LocalTimeType` is never expected to fail, constructing the offset has exhaustive tests asserting it does not panic"
188    )]
189    pub fn fixed(offset: i32) -> Result<Self, TimeError> {
190        if !(MIN_OFFSET_SECONDS..=MAX_OFFSET_SECONDS).contains(&offset) {
191            return Err(TzOutOfRangeError::new().into());
192        }
193
194        let mut offset_name = [0; 5];
195
196        offset_hhmm_from_seconds(offset, &mut offset_name).expect("offset name should be 5 bytes long");
197        // Creation of the `LocalTimeType` is never expected to fail, since the
198        // bounds we are more restrictive of the values than the struct itself.
199        let local_time_type = LocalTimeType::new(offset, false, Some(&offset_name[..]))
200            .expect("Failed to LocalTimeType for fixed offset");
201
202        Ok(Self {
203            inner: OffsetType::Fixed(local_time_type),
204        })
205    }
206
207    /// Generate an offset based on a provided [`TimeZoneRef`].
208    ///
209    /// This can be combined with [`tzdb`] to generate offsets based on
210    /// predefined IANA time zones.
211    #[inline]
212    #[must_use]
213    fn tz(tz: TimeZoneRef<'static>) -> Self {
214        Self {
215            inner: OffsetType::Tz(tz),
216        }
217    }
218
219    /// Returns whether this offset is UTC.
220    ///
221    /// # Examples
222    ///
223    /// ```
224    /// # use spinoso_time::tzrs::{Offset, Time, TimeError};
225    /// # fn example() -> Result<(), TimeError> {
226    /// let offset = Offset::utc();
227    /// assert!(offset.is_utc());
228    ///
229    /// let offset = Offset::fixed(6600)?; // +0150
230    /// assert!(!offset.is_utc());
231    /// # Ok(())
232    /// # }
233    /// # example().unwrap();
234    /// ```
235    #[inline]
236    #[must_use]
237    pub fn is_utc(&self) -> bool {
238        matches!(self.inner, OffsetType::Utc)
239    }
240
241    /// Returns a `TimeZoneRef` which can be used to generate and project
242    /// _time_.
243    #[inline]
244    #[must_use]
245    pub(crate) fn time_zone_ref(&self) -> TimeZoneRef<'_> {
246        match self.inner {
247            OffsetType::Utc => TimeZoneRef::utc(),
248            OffsetType::Fixed(ref local_time_type) => {
249                match TimeZoneRef::new(&[], slice::from_ref(local_time_type), &[], &None) {
250                    Ok(tz) => tz,
251                    Err(_) => GMT,
252                }
253            }
254
255            OffsetType::Tz(zone) => zone,
256        }
257    }
258}
259
260impl TryFrom<&str> for Offset {
261    type Error = TimeError;
262
263    /// Construct a Offset based on the [accepted MRI values].
264    ///
265    /// Accepts:
266    ///
267    /// - `[+/-]HH[:]MM`
268    /// - A-I representing +01:00 to +09:00.
269    /// - K-M representing +10:00 to +12:00.
270    /// - N-Y representing -01:00 to -12:00.
271    /// - Z representing UTC/Zulu time (0 offset).
272    ///
273    /// [accepted MRI values]: https://ruby-doc.org/core-3.1.2/Time.html#method-c-new
274    #[inline]
275    fn try_from(input: &str) -> Result<Self, Self::Error> {
276        match input {
277            "A" => Ok(Self::fixed(SECONDS_IN_HOUR)?),
278            "B" => Ok(Self::fixed(2 * SECONDS_IN_HOUR)?),
279            "C" => Ok(Self::fixed(3 * SECONDS_IN_HOUR)?),
280            "D" => Ok(Self::fixed(4 * SECONDS_IN_HOUR)?),
281            "E" => Ok(Self::fixed(5 * SECONDS_IN_HOUR)?),
282            "F" => Ok(Self::fixed(6 * SECONDS_IN_HOUR)?),
283            "G" => Ok(Self::fixed(7 * SECONDS_IN_HOUR)?),
284            "H" => Ok(Self::fixed(8 * SECONDS_IN_HOUR)?),
285            "I" => Ok(Self::fixed(9 * SECONDS_IN_HOUR)?),
286            "K" => Ok(Self::fixed(10 * SECONDS_IN_HOUR)?),
287            "L" => Ok(Self::fixed(11 * SECONDS_IN_HOUR)?),
288            "M" => Ok(Self::fixed(12 * SECONDS_IN_HOUR)?),
289            "N" => Ok(Self::fixed(-SECONDS_IN_HOUR)?),
290            "O" => Ok(Self::fixed(-2 * SECONDS_IN_HOUR)?),
291            "P" => Ok(Self::fixed(-3 * SECONDS_IN_HOUR)?),
292            "Q" => Ok(Self::fixed(-4 * SECONDS_IN_HOUR)?),
293            "R" => Ok(Self::fixed(-5 * SECONDS_IN_HOUR)?),
294            "S" => Ok(Self::fixed(-6 * SECONDS_IN_HOUR)?),
295            "T" => Ok(Self::fixed(-7 * SECONDS_IN_HOUR)?),
296            "U" => Ok(Self::fixed(-8 * SECONDS_IN_HOUR)?),
297            "V" => Ok(Self::fixed(-9 * SECONDS_IN_HOUR)?),
298            "W" => Ok(Self::fixed(-10 * SECONDS_IN_HOUR)?),
299            "X" => Ok(Self::fixed(-11 * SECONDS_IN_HOUR)?),
300            "Y" => Ok(Self::fixed(-12 * SECONDS_IN_HOUR)?),
301            // ```console
302            // [3.1.2] > Time.new(2022, 6, 26, 13, 57, 6, 'Z')
303            // => 2022-06-26 13:57:06 UTC
304            // [3.1.2] > Time.new(2022, 6, 26, 13, 57, 6, 'Z').utc?
305            // => true
306            // [3.1.2] > Time.new(2022, 6, 26, 13, 57, 6, 'UTC')
307            // => 2022-06-26 13:57:06 UTC
308            // [3.1.2] > Time.new(2022, 6, 26, 13, 57, 6, 'UTC').utc?
309            // => true
310            // ```
311            "Z" | "UTC" => Ok(Self::utc()),
312            _ => {
313                let FixedTimeZoneOffset { sign, hours, minutes } = parse_fixed_timezone_offset(input)?;
314                // Check that the parsed offset is in range, which goes from:
315                // - `00:00` to `00:59`
316                // - `00:00` to `23:59`
317                if (0..=23).contains(&hours) && (0..=59).contains(&minutes) {
318                    let offset_seconds: i32 = sign * ((hours * SECONDS_IN_HOUR) + (minutes * SECONDS_IN_MINUTE));
319                    Ok(Self::fixed(offset_seconds)?)
320                } else {
321                    Err(TzOutOfRangeError::new().into())
322                }
323            }
324        }
325    }
326}
327
328impl TryFrom<&[u8]> for Offset {
329    type Error = TimeError;
330
331    fn try_from(input: &[u8]) -> Result<Self, Self::Error> {
332        let input = str::from_utf8(input).map_err(|_| TzStringError::new())?;
333        Offset::try_from(input)
334    }
335}
336
337impl TryFrom<String> for Offset {
338    type Error = TimeError;
339
340    fn try_from(input: String) -> Result<Self, Self::Error> {
341        Offset::try_from(input.as_str())
342    }
343}
344
345impl From<TimeZoneRef<'static>> for Offset {
346    #[inline]
347    fn from(tz: TimeZoneRef<'static>) -> Self {
348        Self::tz(tz)
349    }
350}
351
352impl TryFrom<i32> for Offset {
353    type Error = TimeError;
354
355    /// Construct a Offset with the offset in seconds from UTC.
356    ///
357    /// See [`Offset::fixed`].
358    #[inline]
359    fn try_from(seconds: i32) -> Result<Self, Self::Error> {
360        Self::fixed(seconds)
361    }
362}
363
364#[derive(Debug, PartialEq, Eq)]
365struct FixedTimeZoneOffset {
366    pub sign: i32,
367    pub hours: i32,
368    pub minutes: i32,
369}
370
371/// Parses a timezone offset from a string with either the format `+hhmm` /
372/// `-hhmm` or `+hh:mm` / `-hh:mm`. Returns a fixed timezone on success.
373fn parse_fixed_timezone_offset(input: &str) -> Result<FixedTimeZoneOffset, TzStringError> {
374    if !input.is_ascii() {
375        return Err(TzStringError::new());
376    }
377
378    // Special handling of the +/- sign is required because `-00:30` must parse
379    // to a negative offset and `i32::from_str_radix` cannot preserve the `-`
380    // sign when parsing zero.
381    let (sign, hour_str, minute_str) = match input.as_bytes() {
382        // Matches `+hhmm`
383        [b'+', _, _, _, _] => (1, &input[1..3], &input[3..5]),
384        // Matches `-hhmm`
385        [b'-', _, _, _, _] => (-1, &input[1..3], &input[3..5]),
386        // Matches `+hh:mm`
387        [b'+', _, _, b':', _, _] => (1, &input[1..3], &input[4..6]),
388        // Matches `-hh:mm`
389        [b'-', _, _, b':', _, _] => (-1, &input[1..3], &input[4..6]),
390        // Anything else is an error.
391        _ => return Err(TzStringError::new()),
392    };
393
394    // Parse hours and minutes (the slices contain only ASCII digits).
395    //
396    // Both of these calls to `parse::<i32>()` ultimately boil down to
397    // `i32::from_str_radix(s, 10)`. This function strips leading zero padding
398    // as is present when parsing offsets like `+00:30` or `-08:00`.
399    let hours: i32 = hour_str.parse().map_err(|_| TzStringError::new())?;
400    let minutes: i32 = minute_str.parse().map_err(|_| TzStringError::new())?;
401
402    Ok(FixedTimeZoneOffset { sign, hours, minutes })
403}
404
405#[cfg(test)]
406mod tests {
407    use std::sync::LazyLock;
408
409    use tz::timezone::Transition;
410    use tz::{LocalTimeType, TimeZone};
411
412    use super::*;
413    use crate::tzrs::Time;
414    use crate::tzrs::error::TimeError;
415
416    fn offset_seconds_from_fixed_offset(input: &str) -> Result<i32, TimeError> {
417        let offset = Offset::try_from(input)?;
418        let local_time_type = offset.time_zone_ref().local_time_types()[0];
419        Ok(local_time_type.ut_offset())
420    }
421
422    fn fixed_offset_name(offset_seconds: i32) -> Result<String, TimeError> {
423        let offset = Offset::fixed(offset_seconds)?;
424
425        match offset.inner {
426            OffsetType::Fixed(ref local_time_type) => Ok(local_time_type.time_zone_designation().to_string()),
427            _ => unreachable!(),
428        }
429    }
430
431    #[test]
432    fn fixed_zero_is_not_utc() {
433        let offset = Offset::try_from(0).unwrap();
434        assert!(!offset.is_utc());
435    }
436
437    #[test]
438    fn utc_is_utc() {
439        let offset = Offset::utc();
440        assert!(offset.is_utc());
441    }
442
443    #[test]
444    fn z_is_utc() {
445        let offset = Offset::try_from("Z").unwrap();
446        assert!(offset.is_utc());
447    }
448
449    #[test]
450    fn from_binary_string() {
451        let tz: &[u8] = b"Z";
452        let offset = Offset::try_from(tz).unwrap();
453        assert!(offset.is_utc());
454    }
455
456    #[test]
457    fn from_str_hh_mm() {
458        assert_eq!(Some(0), offset_seconds_from_fixed_offset("+0000").ok());
459        assert_eq!(Some(0), offset_seconds_from_fixed_offset("-0000").ok());
460        assert_eq!(Some(60), offset_seconds_from_fixed_offset("+0001").ok());
461        assert_eq!(Some(-60), offset_seconds_from_fixed_offset("-0001").ok());
462        assert_eq!(Some(3600), offset_seconds_from_fixed_offset("+0100").ok());
463        assert_eq!(Some(-3600), offset_seconds_from_fixed_offset("-0100").ok());
464        assert_eq!(Some(7320), offset_seconds_from_fixed_offset("+0202").ok());
465        assert_eq!(Some(-7320), offset_seconds_from_fixed_offset("-0202").ok());
466
467        assert!(matches!(
468            offset_seconds_from_fixed_offset("+2400").unwrap_err(),
469            TimeError::TzOutOfRangeError(_)
470        ));
471
472        assert!(matches!(
473            offset_seconds_from_fixed_offset("-2400").unwrap_err(),
474            TimeError::TzOutOfRangeError(_)
475        ));
476
477        assert!(matches!(
478            offset_seconds_from_fixed_offset("+0060").unwrap_err(),
479            TimeError::TzOutOfRangeError(_)
480        ));
481
482        assert!(matches!(
483            offset_seconds_from_fixed_offset("-0060").unwrap_err(),
484            TimeError::TzOutOfRangeError(_)
485        ));
486    }
487
488    #[test]
489    fn from_str_hh_colon_mm() {
490        assert_eq!(Some(0), offset_seconds_from_fixed_offset("+00:00").ok());
491        assert_eq!(Some(0), offset_seconds_from_fixed_offset("-00:00").ok());
492        assert_eq!(Some(60), offset_seconds_from_fixed_offset("+00:01").ok());
493        assert_eq!(Some(-60), offset_seconds_from_fixed_offset("-00:01").ok());
494        assert_eq!(Some(3600), offset_seconds_from_fixed_offset("+01:00").ok());
495        assert_eq!(Some(-3600), offset_seconds_from_fixed_offset("-01:00").ok());
496        assert_eq!(Some(7320), offset_seconds_from_fixed_offset("+02:02").ok());
497        assert_eq!(Some(-7320), offset_seconds_from_fixed_offset("-02:02").ok());
498
499        assert!(matches!(
500            offset_seconds_from_fixed_offset("+24:00").unwrap_err(),
501            TimeError::TzOutOfRangeError(_)
502        ));
503
504        assert!(matches!(
505            offset_seconds_from_fixed_offset("-24:00").unwrap_err(),
506            TimeError::TzOutOfRangeError(_)
507        ));
508
509        assert!(matches!(
510            offset_seconds_from_fixed_offset("+00:60").unwrap_err(),
511            TimeError::TzOutOfRangeError(_)
512        ));
513
514        assert!(matches!(
515            offset_seconds_from_fixed_offset("-00:60").unwrap_err(),
516            TimeError::TzOutOfRangeError(_)
517        ));
518    }
519
520    #[test]
521    fn from_str_invalid_fixed_strings() {
522        let invalid_fixed_strings = [
523            "+01:010", "+010:10", "+010:010", "0110", "01:10", "01-10", "+01-10", "+01::10",
524        ];
525
526        for invalid_string in invalid_fixed_strings {
527            assert!(
528                matches!(
529                    Offset::try_from(invalid_string).unwrap_err(),
530                    TimeError::TzStringError(_)
531                ),
532                "Expected TimeError::TzStringError for {invalid_string}",
533            );
534        }
535    }
536
537    #[test]
538    fn from_str_non_ascii_numeral_fixed_strings() {
539        // This offset string is constructed out of non-ASCII numerals in the
540        // Unicode Nd character class. The sequence contains `+`, Devanagari 1,
541        // Devanagari 0, Kannada 3, and Kannada 6.
542        //
543        // See:
544        //
545        // - <https://en.wikipedia.org/wiki/Devanagari_numerals#Table>
546        // - <https://en.wikipedia.org/wiki/Kannada_script#Numerals>
547        let offset = "+१०:೩೬";
548        assert!(matches!(
549            offset_seconds_from_fixed_offset(offset).unwrap_err(),
550            TimeError::TzStringError(_)
551        ));
552    }
553
554    #[test]
555    fn from_str_fixed_strings_with_newlines() {
556        assert!(matches!(
557            offset_seconds_from_fixed_offset("+10:00\n+11:00").unwrap_err(),
558            TimeError::TzStringError(_)
559        ));
560        assert!(matches!(
561            offset_seconds_from_fixed_offset("+10:00\n").unwrap_err(),
562            TimeError::TzStringError(_)
563        ));
564        assert!(matches!(
565            offset_seconds_from_fixed_offset("\n+10:00").unwrap_err(),
566            TimeError::TzStringError(_)
567        ));
568    }
569
570    #[test]
571    fn offset_hhmm_from_seconds_exhaustive_5_bytes() {
572        // Check to make sure that the stack-allocated buffer for writing the
573        // [+/-]HHMM offset is exactly sized for the entire range of valid
574        // offset seconds.
575        for offset in MIN_OFFSET_SECONDS..=MAX_OFFSET_SECONDS {
576            let mut buf = [0xFF; 5];
577            offset_hhmm_from_seconds(offset, &mut buf).unwrap();
578            assert!(buf.into_iter().all(|b| b != 0xFF));
579        }
580    }
581
582    #[test]
583    fn fixed_time_zone_designation_exhaustive_no_panic() {
584        // Check to make sure that the stack-allocated buffer for writing the
585        // [+/-]HHMM offset is sufficiently sized for the entire range of valid
586        // offset seconds.
587        for offset in MIN_OFFSET_SECONDS..=MAX_OFFSET_SECONDS {
588            fixed_offset_name(offset).unwrap();
589        }
590    }
591
592    #[test]
593    fn fixed_time_zone_designation() {
594        assert_eq!("+0000", fixed_offset_name(0).unwrap());
595        assert_eq!("+0000", fixed_offset_name(59).unwrap());
596        assert_eq!("+0001", fixed_offset_name(60).unwrap());
597        assert_eq!("-0001", fixed_offset_name(-60).unwrap());
598        assert_eq!("+0100", fixed_offset_name(3600).unwrap());
599        assert_eq!("-0100", fixed_offset_name(-3600).unwrap());
600        assert_eq!("+0202", fixed_offset_name(7320).unwrap());
601        assert_eq!("-0202", fixed_offset_name(-7320).unwrap());
602
603        assert_eq!("+2359", fixed_offset_name(MAX_OFFSET_SECONDS).unwrap());
604        assert_eq!("-2359", fixed_offset_name(MIN_OFFSET_SECONDS).unwrap());
605
606        assert!(matches!(
607            fixed_offset_name(MAX_OFFSET_SECONDS + 1).unwrap_err(),
608            TimeError::TzOutOfRangeError(_)
609        ));
610
611        assert!(matches!(
612            fixed_offset_name(MIN_OFFSET_SECONDS - 1).unwrap_err(),
613            TimeError::TzOutOfRangeError(_)
614        ));
615    }
616
617    // https://github.com/x-hgg-x/tz-rs/issues/34#issuecomment-1206140198
618    #[test]
619    fn tzrs_gh_34_handle_missing_transition_tzif_v1() {
620        static TZ: LazyLock<TimeZone> = LazyLock::new(|| {
621            let local_time_types = vec![
622                LocalTimeType::new(0, false, None).unwrap(),
623                LocalTimeType::new(3600, false, None).unwrap(),
624            ];
625
626            TimeZone::new(
627                vec![Transition::new(0, 1), Transition::new(86400, 1)],
628                local_time_types,
629                vec![],
630                None,
631            )
632            .unwrap()
633        });
634
635        let offset = Offset {
636            inner: OffsetType::Tz(TZ.as_ref()),
637        };
638        assert!(matches!(
639            Time::new(1970, 1, 2, 12, 0, 0, 0, offset).unwrap_err(),
640            TimeError::Unknown,
641        ));
642    }
643
644    #[test]
645    fn test_valid_offsets_without_colon() {
646        // Test positive offsets without colon.
647        let tz = parse_fixed_timezone_offset("+0000").unwrap();
648        assert_eq!(
649            tz,
650            FixedTimeZoneOffset {
651                sign: 1,
652                hours: 0,
653                minutes: 0
654            }
655        );
656
657        let tz = parse_fixed_timezone_offset("+1234").unwrap();
658        assert_eq!(
659            tz,
660            FixedTimeZoneOffset {
661                sign: 1,
662                hours: 12,
663                minutes: 34
664            }
665        );
666
667        // Test negative offsets without colon.
668        let tz = parse_fixed_timezone_offset("-0000").unwrap();
669        assert_eq!(
670            tz,
671            FixedTimeZoneOffset {
672                sign: -1,
673                hours: 0,
674                minutes: 0
675            }
676        );
677
678        let tz = parse_fixed_timezone_offset("-0830").unwrap();
679        assert_eq!(
680            tz,
681            FixedTimeZoneOffset {
682                sign: -1,
683                hours: 8,
684                minutes: 30
685            }
686        );
687    }
688
689    #[test]
690    fn test_valid_offsets_with_colon() {
691        // Test positive offsets with colon.
692        let tz = parse_fixed_timezone_offset("+00:00").unwrap();
693        assert_eq!(
694            tz,
695            FixedTimeZoneOffset {
696                sign: 1,
697                hours: 0,
698                minutes: 0
699            }
700        );
701
702        let tz = parse_fixed_timezone_offset("+12:34").unwrap();
703        assert_eq!(
704            tz,
705            FixedTimeZoneOffset {
706                sign: 1,
707                hours: 12,
708                minutes: 34
709            }
710        );
711
712        // Test negative offsets with colon.
713        let tz = parse_fixed_timezone_offset("-00:00").unwrap();
714        assert_eq!(
715            tz,
716            FixedTimeZoneOffset {
717                sign: -1,
718                hours: 0,
719                minutes: 0
720            }
721        );
722
723        let tz = parse_fixed_timezone_offset("-08:30").unwrap();
724        assert_eq!(
725            tz,
726            FixedTimeZoneOffset {
727                sign: -1,
728                hours: 8,
729                minutes: 30
730            }
731        );
732    }
733
734    #[test]
735    fn test_invalid_length() {
736        // Too short.
737        assert!(parse_fixed_timezone_offset("").is_err());
738        assert!(parse_fixed_timezone_offset("+00").is_err());
739
740        // Too long.
741        assert!(parse_fixed_timezone_offset("+00000").is_err());
742        assert!(parse_fixed_timezone_offset("+12:345").is_err());
743    }
744
745    #[test]
746    fn test_invalid_non_ascii() {
747        // Use a full-width plus sign (`U+FF0B`) instead of ASCII `+`.
748        let non_ascii = "＋1234"; // Note: The first character is not ASCII.
749        assert!(parse_fixed_timezone_offset(non_ascii).is_err());
750    }
751
752    #[test]
753    fn test_invalid_format() {
754        // Missing sign.
755        assert!(parse_fixed_timezone_offset("12345").is_err());
756
757        // Invalid sign character.
758        assert!(parse_fixed_timezone_offset("*1234").is_err());
759
760        // Wrong placement of colon.
761        assert!(parse_fixed_timezone_offset("+1:234").is_err());
762        // For a 6-character string the colon must be at index 3.
763        assert!(parse_fixed_timezone_offset("+12345").is_err());
764
765        // Non-digit characters in the hour or minute fields.
766        assert!(parse_fixed_timezone_offset("+1a:34").is_err());
767        assert!(parse_fixed_timezone_offset("+12:3b").is_err());
768    }
769
770    #[test]
771    fn test_invalid_digit_parsing() {
772        // Non-digit characters in place of expected digits.
773        assert!(parse_fixed_timezone_offset("+ab:cd").is_err());
774        assert!(parse_fixed_timezone_offset("+ab12").is_err());
775    }
776}
spinoso_time/time/tzrs/offset.rs

spinoso_time/time/tzrs/
offset.rs
