time/
utc_offset.rs

1//! The [`UtcOffset`] struct and its associated `impl`s.
2
3#[cfg(feature = "formatting")]
4use alloc::string::String;
5use core::cmp::Ordering;
6use core::fmt;
7use core::hash::{Hash, Hasher};
8use core::ops::Neg;
9#[cfg(feature = "formatting")]
10use std::io;
11
12use deranged::{RangedI32, RangedI8};
13use powerfmt::ext::FormatterExt;
14use powerfmt::smart_display::{self, FormatterOptions, Metadata, SmartDisplay};
15
16use crate::convert::*;
17use crate::error;
18#[cfg(feature = "formatting")]
19use crate::formatting::Formattable;
20use crate::internal_macros::ensure_ranged;
21#[cfg(feature = "parsing")]
22use crate::parsing::Parsable;
23#[cfg(feature = "local-offset")]
24use crate::sys::local_offset_at;
25#[cfg(feature = "local-offset")]
26use crate::OffsetDateTime;
27
28/// The type of the `hours` field of `UtcOffset`.
29type Hours = RangedI8<-25, 25>;
30/// The type of the `minutes` field of `UtcOffset`.
31type Minutes = RangedI8<{ -(Minute::per_t::<i8>(Hour) - 1) }, { Minute::per_t::<i8>(Hour) - 1 }>;
32/// The type of the `seconds` field of `UtcOffset`.
33type Seconds =
34    RangedI8<{ -(Second::per_t::<i8>(Minute) - 1) }, { Second::per_t::<i8>(Minute) - 1 }>;
35/// The type capable of storing the range of whole seconds that a `UtcOffset` can encompass.
36type WholeSeconds = RangedI32<
37    {
38        Hours::MIN.get() as i32 * Second::per_t::<i32>(Hour)
39            + Minutes::MIN.get() as i32 * Second::per_t::<i32>(Minute)
40            + Seconds::MIN.get() as i32
41    },
42    {
43        Hours::MAX.get() as i32 * Second::per_t::<i32>(Hour)
44            + Minutes::MAX.get() as i32 * Second::per_t::<i32>(Minute)
45            + Seconds::MAX.get() as i32
46    },
47>;
48
49/// An offset from UTC.
50///
51/// This struct can store values up to ±25:59:59. If you need support outside this range, please
52/// file an issue with your use case.
53// All three components _must_ have the same sign.
54#[derive(Clone, Copy, Eq)]
55#[cfg_attr(not(docsrs), repr(C))]
56pub struct UtcOffset {
57    /// The order of this struct's fields matter. Do not reorder them.
58
59    // Little endian version
60    #[cfg(target_endian = "little")]
61    seconds: Seconds,
62    #[cfg(target_endian = "little")]
63    minutes: Minutes,
64    #[cfg(target_endian = "little")]
65    hours: Hours,
66
67    // Big endian version
68    #[cfg(target_endian = "big")]
69    hours: Hours,
70    #[cfg(target_endian = "big")]
71    minutes: Minutes,
72    #[cfg(target_endian = "big")]
73    seconds: Seconds,
74}
75
76impl Hash for UtcOffset {
77    #[inline]
78    fn hash<H: Hasher>(&self, state: &mut H) {
79        state.write_u32(self.as_u32());
80    }
81}
82
83impl PartialEq for UtcOffset {
84    #[inline]
85    fn eq(&self, other: &Self) -> bool {
86        self.as_u32().eq(&other.as_u32())
87    }
88}
89
90impl PartialOrd for UtcOffset {
91    #[inline]
92    fn partial_cmp(&self, other: &Self) -> Option<Ordering> {
93        Some(self.cmp(other))
94    }
95}
96
97impl Ord for UtcOffset {
98    #[inline]
99    fn cmp(&self, other: &Self) -> Ordering {
100        self.as_u32().cmp(&other.as_u32())
101    }
102}
103
104impl UtcOffset {
105    /// Provide a representation of the `UtcOffset` as a `u32`. This value can be used for equality,
106    /// hashing, and ordering.
107    #[inline]
108    pub(crate) const fn as_u32(self) -> u32 {
109        #[cfg(target_endian = "big")]
110        return u32::from_be_bytes([
111            self.seconds.get() as u8,
112            self.minutes.get() as u8,
113            self.hours.get() as u8,
114            0,
115        ]);
116
117        #[cfg(target_endian = "little")]
118        return u32::from_le_bytes([
119            self.seconds.get() as u8,
120            self.minutes.get() as u8,
121            self.hours.get() as u8,
122            0,
123        ]);
124    }
125
126    /// A `UtcOffset` that is UTC.
127    ///
128    /// ```rust
129    /// # use time::UtcOffset;
130    /// # use time_macros::offset;
131    /// assert_eq!(UtcOffset::UTC, offset!(UTC));
132    /// ```
133    pub const UTC: Self = Self::from_whole_seconds_ranged(WholeSeconds::new_static::<0>());
134
135    /// Create a `UtcOffset` representing an offset of the hours, minutes, and seconds provided, the
136    /// validity of which must be guaranteed by the caller. All three parameters must have the same
137    /// sign.
138    ///
139    /// # Safety
140    ///
141    /// - Hours must be in the range `-25..=25`.
142    /// - Minutes must be in the range `-59..=59`.
143    /// - Seconds must be in the range `-59..=59`.
144    ///
145    /// While the signs of the parameters are required to match to avoid bugs, this is not a safety
146    /// invariant.
147    #[doc(hidden)]
148    #[inline]
149    #[track_caller]
150    pub const unsafe fn __from_hms_unchecked(hours: i8, minutes: i8, seconds: i8) -> Self {
151        // Safety: The caller must uphold the safety invariants.
152        unsafe {
153            Self::from_hms_ranged_unchecked(
154                Hours::new_unchecked(hours),
155                Minutes::new_unchecked(minutes),
156                Seconds::new_unchecked(seconds),
157            )
158        }
159    }
160
161    /// Create a `UtcOffset` representing an offset by the number of hours, minutes, and seconds
162    /// provided.
163    ///
164    /// The sign of all three components should match. If they do not, all smaller components will
165    /// have their signs flipped.
166    ///
167    /// ```rust
168    /// # use time::UtcOffset;
169    /// assert_eq!(UtcOffset::from_hms(1, 2, 3)?.as_hms(), (1, 2, 3));
170    /// assert_eq!(UtcOffset::from_hms(1, -2, -3)?.as_hms(), (1, 2, 3));
171    /// # Ok::<_, time::Error>(())
172    /// ```
173    #[inline]
174    pub const fn from_hms(
175        hours: i8,
176        minutes: i8,
177        seconds: i8,
178    ) -> Result<Self, error::ComponentRange> {
179        Ok(Self::from_hms_ranged(
180            ensure_ranged!(Hours: hours),
181            ensure_ranged!(Minutes: minutes),
182            ensure_ranged!(Seconds: seconds),
183        ))
184    }
185
186    /// Create a `UtcOffset` representing an offset of the hours, minutes, and seconds provided. All
187    /// three parameters must have the same sign.
188    ///
189    /// While the signs of the parameters are required to match, this is not a safety invariant.
190    #[inline]
191    #[track_caller]
192    pub(crate) const fn from_hms_ranged_unchecked(
193        hours: Hours,
194        minutes: Minutes,
195        seconds: Seconds,
196    ) -> Self {
197        if hours.get() < 0 {
198            debug_assert!(minutes.get() <= 0);
199            debug_assert!(seconds.get() <= 0);
200        } else if hours.get() > 0 {
201            debug_assert!(minutes.get() >= 0);
202            debug_assert!(seconds.get() >= 0);
203        }
204        if minutes.get() < 0 {
205            debug_assert!(seconds.get() <= 0);
206        } else if minutes.get() > 0 {
207            debug_assert!(seconds.get() >= 0);
208        }
209
210        Self {
211            hours,
212            minutes,
213            seconds,
214        }
215    }
216
217    /// Create a `UtcOffset` representing an offset by the number of hours, minutes, and seconds
218    /// provided.
219    ///
220    /// The sign of all three components should match. If they do not, all smaller components will
221    /// have their signs flipped.
222    #[inline]
223    pub(crate) const fn from_hms_ranged(
224        hours: Hours,
225        mut minutes: Minutes,
226        mut seconds: Seconds,
227    ) -> Self {
228        if (hours.get() > 0 && minutes.get() < 0) || (hours.get() < 0 && minutes.get() > 0) {
229            minutes = minutes.neg();
230        }
231        if (hours.get() > 0 && seconds.get() < 0)
232            || (hours.get() < 0 && seconds.get() > 0)
233            || (minutes.get() > 0 && seconds.get() < 0)
234            || (minutes.get() < 0 && seconds.get() > 0)
235        {
236            seconds = seconds.neg();
237        }
238
239        Self {
240            hours,
241            minutes,
242            seconds,
243        }
244    }
245
246    /// Create a `UtcOffset` representing an offset by the number of seconds provided.
247    ///
248    /// ```rust
249    /// # use time::UtcOffset;
250    /// assert_eq!(UtcOffset::from_whole_seconds(3_723)?.as_hms(), (1, 2, 3));
251    /// # Ok::<_, time::Error>(())
252    /// ```
253    #[inline]
254    pub const fn from_whole_seconds(seconds: i32) -> Result<Self, error::ComponentRange> {
255        Ok(Self::from_whole_seconds_ranged(
256            ensure_ranged!(WholeSeconds: seconds),
257        ))
258    }
259
260    /// Create a `UtcOffset` representing an offset by the number of seconds provided.
261    // ignore because the function is crate-private
262    /// ```rust,ignore
263    /// # use time::UtcOffset;
264    /// # use deranged::RangedI32;
265    /// assert_eq!(
266    ///     UtcOffset::from_whole_seconds_ranged(RangedI32::new_static::<3_723>()).as_hms(),
267    ///     (1, 2, 3)
268    /// );
269    /// # Ok::<_, time::Error>(())
270    /// ```
271    #[inline]
272    pub(crate) const fn from_whole_seconds_ranged(seconds: WholeSeconds) -> Self {
273        // Safety: The type of `seconds` guarantees that all values are in range.
274        unsafe {
275            Self::__from_hms_unchecked(
276                (seconds.get() / Second::per_t::<i32>(Hour)) as i8,
277                ((seconds.get() % Second::per_t::<i32>(Hour)) / Minute::per_t::<i32>(Hour)) as i8,
278                (seconds.get() % Second::per_t::<i32>(Minute)) as i8,
279            )
280        }
281    }
282
283    /// Obtain the UTC offset as its hours, minutes, and seconds. The sign of all three components
284    /// will always match. A positive value indicates an offset to the east; a negative to the west.
285    ///
286    /// ```rust
287    /// # use time_macros::offset;
288    /// assert_eq!(offset!(+1:02:03).as_hms(), (1, 2, 3));
289    /// assert_eq!(offset!(-1:02:03).as_hms(), (-1, -2, -3));
290    /// ```
291    #[inline]
292    pub const fn as_hms(self) -> (i8, i8, i8) {
293        (self.hours.get(), self.minutes.get(), self.seconds.get())
294    }
295
296    /// Obtain the UTC offset as its hours, minutes, and seconds. The sign of all three components
297    /// will always match. A positive value indicates an offset to the east; a negative to the west.
298    #[cfg(feature = "quickcheck")]
299    #[inline]
300    pub(crate) const fn as_hms_ranged(self) -> (Hours, Minutes, Seconds) {
301        (self.hours, self.minutes, self.seconds)
302    }
303
304    /// Obtain the number of whole hours the offset is from UTC. A positive value indicates an
305    /// offset to the east; a negative to the west.
306    ///
307    /// ```rust
308    /// # use time_macros::offset;
309    /// assert_eq!(offset!(+1:02:03).whole_hours(), 1);
310    /// assert_eq!(offset!(-1:02:03).whole_hours(), -1);
311    /// ```
312    #[inline]
313    pub const fn whole_hours(self) -> i8 {
314        self.hours.get()
315    }
316
317    /// Obtain the number of whole minutes the offset is from UTC. A positive value indicates an
318    /// offset to the east; a negative to the west.
319    ///
320    /// ```rust
321    /// # use time_macros::offset;
322    /// assert_eq!(offset!(+1:02:03).whole_minutes(), 62);
323    /// assert_eq!(offset!(-1:02:03).whole_minutes(), -62);
324    /// ```
325    #[inline]
326    pub const fn whole_minutes(self) -> i16 {
327        self.hours.get() as i16 * Minute::per_t::<i16>(Hour) + self.minutes.get() as i16
328    }
329
330    /// Obtain the number of minutes past the hour the offset is from UTC. A positive value
331    /// indicates an offset to the east; a negative to the west.
332    ///
333    /// ```rust
334    /// # use time_macros::offset;
335    /// assert_eq!(offset!(+1:02:03).minutes_past_hour(), 2);
336    /// assert_eq!(offset!(-1:02:03).minutes_past_hour(), -2);
337    /// ```
338    #[inline]
339    pub const fn minutes_past_hour(self) -> i8 {
340        self.minutes.get()
341    }
342
343    /// Obtain the number of whole seconds the offset is from UTC. A positive value indicates an
344    /// offset to the east; a negative to the west.
345    ///
346    /// ```rust
347    /// # use time_macros::offset;
348    /// assert_eq!(offset!(+1:02:03).whole_seconds(), 3723);
349    /// assert_eq!(offset!(-1:02:03).whole_seconds(), -3723);
350    /// ```
351    // This may be useful for anyone manually implementing arithmetic, as it
352    // would let them construct a `Duration` directly.
353    #[inline]
354    pub const fn whole_seconds(self) -> i32 {
355        self.hours.get() as i32 * Second::per_t::<i32>(Hour)
356            + self.minutes.get() as i32 * Second::per_t::<i32>(Minute)
357            + self.seconds.get() as i32
358    }
359
360    /// Obtain the number of seconds past the minute the offset is from UTC. A positive value
361    /// indicates an offset to the east; a negative to the west.
362    ///
363    /// ```rust
364    /// # use time_macros::offset;
365    /// assert_eq!(offset!(+1:02:03).seconds_past_minute(), 3);
366    /// assert_eq!(offset!(-1:02:03).seconds_past_minute(), -3);
367    /// ```
368    #[inline]
369    pub const fn seconds_past_minute(self) -> i8 {
370        self.seconds.get()
371    }
372
373    /// Check if the offset is exactly UTC.
374    ///
375    ///
376    /// ```rust
377    /// # use time_macros::offset;
378    /// assert!(!offset!(+1:02:03).is_utc());
379    /// assert!(!offset!(-1:02:03).is_utc());
380    /// assert!(offset!(UTC).is_utc());
381    /// ```
382    #[inline]
383    pub const fn is_utc(self) -> bool {
384        self.hours.get() == 0 && self.minutes.get() == 0 && self.seconds.get() == 0
385    }
386
387    /// Check if the offset is positive, or east of UTC.
388    ///
389    /// ```rust
390    /// # use time_macros::offset;
391    /// assert!(offset!(+1:02:03).is_positive());
392    /// assert!(!offset!(-1:02:03).is_positive());
393    /// assert!(!offset!(UTC).is_positive());
394    /// ```
395    #[inline]
396    pub const fn is_positive(self) -> bool {
397        self.hours.get() > 0 || self.minutes.get() > 0 || self.seconds.get() > 0
398    }
399
400    /// Check if the offset is negative, or west of UTC.
401    ///
402    /// ```rust
403    /// # use time_macros::offset;
404    /// assert!(!offset!(+1:02:03).is_negative());
405    /// assert!(offset!(-1:02:03).is_negative());
406    /// assert!(!offset!(UTC).is_negative());
407    /// ```
408    #[inline]
409    pub const fn is_negative(self) -> bool {
410        self.hours.get() < 0 || self.minutes.get() < 0 || self.seconds.get() < 0
411    }
412
413    /// Attempt to obtain the system's UTC offset at a known moment in time. If the offset cannot be
414    /// determined, an error is returned.
415    ///
416    /// ```rust
417    /// # use time::{UtcOffset, OffsetDateTime};
418    /// let local_offset = UtcOffset::local_offset_at(OffsetDateTime::UNIX_EPOCH);
419    /// # if false {
420    /// assert!(local_offset.is_ok());
421    /// # }
422    /// ```
423    #[cfg(feature = "local-offset")]
424    #[inline]
425    pub fn local_offset_at(datetime: OffsetDateTime) -> Result<Self, error::IndeterminateOffset> {
426        local_offset_at(datetime).ok_or(error::IndeterminateOffset)
427    }
428
429    /// Attempt to obtain the system's current UTC offset. If the offset cannot be determined, an
430    /// error is returned.
431    ///
432    /// ```rust
433    /// # use time::UtcOffset;
434    /// let local_offset = UtcOffset::current_local_offset();
435    /// # if false {
436    /// assert!(local_offset.is_ok());
437    /// # }
438    /// ```
439    #[cfg(feature = "local-offset")]
440    #[inline]
441    pub fn current_local_offset() -> Result<Self, error::IndeterminateOffset> {
442        let now = OffsetDateTime::now_utc();
443        local_offset_at(now).ok_or(error::IndeterminateOffset)
444    }
445}
446
447#[cfg(feature = "formatting")]
448impl UtcOffset {
449    /// Format the `UtcOffset` using the provided [format description](crate::format_description).
450    #[inline]
451    pub fn format_into(
452        self,
453        output: &mut (impl io::Write + ?Sized),
454        format: &(impl Formattable + ?Sized),
455    ) -> Result<usize, error::Format> {
456        format.format_into(output, None, None, Some(self))
457    }
458
459    /// Format the `UtcOffset` using the provided [format description](crate::format_description).
460    ///
461    /// ```rust
462    /// # use time::format_description;
463    /// # use time_macros::offset;
464    /// let format = format_description::parse("[offset_hour sign:mandatory]:[offset_minute]")?;
465    /// assert_eq!(offset!(+1).format(&format)?, "+01:00");
466    /// # Ok::<_, time::Error>(())
467    /// ```
468    #[inline]
469    pub fn format(self, format: &(impl Formattable + ?Sized)) -> Result<String, error::Format> {
470        format.format(None, None, Some(self))
471    }
472}
473
474#[cfg(feature = "parsing")]
475impl UtcOffset {
476    /// Parse a `UtcOffset` from the input using the provided [format
477    /// description](crate::format_description).
478    ///
479    /// ```rust
480    /// # use time::UtcOffset;
481    /// # use time_macros::{offset, format_description};
482    /// let format = format_description!("[offset_hour]:[offset_minute]");
483    /// assert_eq!(UtcOffset::parse("-03:42", &format)?, offset!(-3:42));
484    /// # Ok::<_, time::Error>(())
485    /// ```
486    #[inline]
487    pub fn parse(
488        input: &str,
489        description: &(impl Parsable + ?Sized),
490    ) -> Result<Self, error::Parse> {
491        description.parse_offset(input.as_bytes())
492    }
493}
494
495mod private {
496    #[non_exhaustive]
497    #[derive(Debug, Clone, Copy)]
498    pub struct UtcOffsetMetadata;
499}
500use private::UtcOffsetMetadata;
501
502impl SmartDisplay for UtcOffset {
503    type Metadata = UtcOffsetMetadata;
504
505    #[inline]
506    fn metadata(&self, _: FormatterOptions) -> Metadata<'_, Self> {
507        let sign = if self.is_negative() { '-' } else { '+' };
508        let width = smart_display::padded_width_of!(
509            sign,
510            self.hours.abs() => width(2),
511            ":",
512            self.minutes.abs() => width(2),
513            ":",
514            self.seconds.abs() => width(2),
515        );
516        Metadata::new(width, self, UtcOffsetMetadata)
517    }
518
519    #[inline]
520    fn fmt_with_metadata(
521        &self,
522        f: &mut fmt::Formatter<'_>,
523        metadata: Metadata<Self>,
524    ) -> fmt::Result {
525        f.pad_with_width(
526            metadata.unpadded_width(),
527            format_args!(
528                "{}{:02}:{:02}:{:02}",
529                if self.is_negative() { '-' } else { '+' },
530                self.hours.abs(),
531                self.minutes.abs(),
532                self.seconds.abs(),
533            ),
534        )
535    }
536}
537
538impl fmt::Display for UtcOffset {
539    #[inline]
540    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
541        SmartDisplay::fmt(self, f)
542    }
543}
544
545impl fmt::Debug for UtcOffset {
546    #[inline]
547    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
548        fmt::Display::fmt(self, f)
549    }
550}
551
552impl Neg for UtcOffset {
553    type Output = Self;
554
555    #[inline]
556    fn neg(self) -> Self::Output {
557        Self::from_hms_ranged(self.hours.neg(), self.minutes.neg(), self.seconds.neg())
558    }
559}