/rust/registry/src/index.crates.io-1949cf8c6b5b557f/time-0.3.47/src/utc_offset.rs

Source
//! The [`UtcOffset`] struct and its associated `impl`s.

#[cfg(feature = "formatting")]
use alloc::string::String;
use core::cmp::Ordering;
use core::fmt;
use core::hash::{Hash, Hasher};
use core::ops::Neg;
#[cfg(feature = "formatting")]
use std::io;

use deranged::{RangedI8, RangedI32};
use powerfmt::ext::FormatterExt;
use powerfmt::smart_display::{self, FormatterOptions, Metadata, SmartDisplay};

#[cfg(feature = "local-offset")]
use crate::OffsetDateTime;
use crate::convert::*;
use crate::error;
#[cfg(feature = "formatting")]
use crate::formatting::Formattable;
use crate::internal_macros::ensure_ranged;
#[cfg(feature = "parsing")]
use crate::parsing::Parsable;
#[cfg(feature = "local-offset")]
use crate::sys::local_offset_at;

/// The type of the `hours` field of `UtcOffset`.
type Hours = RangedI8<-25, 25>;
/// The type of the `minutes` field of `UtcOffset`.
type Minutes = RangedI8<{ -(Minute::per_t::<i8>(Hour) - 1) }, { Minute::per_t::<i8>(Hour) - 1 }>;
/// The type of the `seconds` field of `UtcOffset`.
type Seconds =
    RangedI8<{ -(Second::per_t::<i8>(Minute) - 1) }, { Second::per_t::<i8>(Minute) - 1 }>;
/// The type capable of storing the range of whole seconds that a `UtcOffset` can encompass.
type WholeSeconds = RangedI32<
    {
        Hours::MIN.get() as i32 * Second::per_t::<i32>(Hour)
            + Minutes::MIN.get() as i32 * Second::per_t::<i32>(Minute)
            + Seconds::MIN.get() as i32
    },
    {
        Hours::MAX.get() as i32 * Second::per_t::<i32>(Hour)
            + Minutes::MAX.get() as i32 * Second::per_t::<i32>(Minute)
            + Seconds::MAX.get() as i32
    },
>;

/// An offset from UTC.
///
/// This struct can store values up to ±25:59:59. If you need support outside this range, please
/// file an issue with your use case.
// All three components _must_ have the same sign.
#[derive(Clone, Copy, Eq)]
#[cfg_attr(not(docsrs), repr(C))]
pub struct UtcOffset {
    // The order of this struct's fields matter. Do not reorder them.

    // Little endian version
    #[cfg(target_endian = "little")]
    seconds: Seconds,
    #[cfg(target_endian = "little")]
    minutes: Minutes,
    #[cfg(target_endian = "little")]
    hours: Hours,

    // Big endian version
    #[cfg(target_endian = "big")]
    hours: Hours,
    #[cfg(target_endian = "big")]
    minutes: Minutes,
    #[cfg(target_endian = "big")]
    seconds: Seconds,
}

impl Hash for UtcOffset {
    #[inline]
    fn hash<H>(&self, state: &mut H)
    where
        H: Hasher,
    {
        state.write_u32(self.as_u32_for_equality());
    }
}

impl PartialEq for UtcOffset {
    #[inline]
    fn eq(&self, other: &Self) -> bool {
        self.as_u32_for_equality().eq(&other.as_u32_for_equality())
    }
}

impl PartialOrd for UtcOffset {
    #[inline]
    fn partial_cmp(&self, other: &Self) -> Option<Ordering> {
        Some(self.cmp(other))
    }
}

impl Ord for UtcOffset {
    #[inline]
    fn cmp(&self, other: &Self) -> Ordering {
        self.as_i32_for_comparison()
            .cmp(&other.as_i32_for_comparison())
    }
}

impl UtcOffset {
    /// Provide a representation of the `UtcOffset` as a `i32`. This value can be used for equality,
    /// and hashing. This value is not suitable for ordering; use `as_i32_for_comparison` instead.
    #[inline]
    pub(crate) const fn as_u32_for_equality(self) -> u32 {
        // Safety: Size and alignment are handled by the compiler. Both the source and destination
        // types are plain old data (POD) types.
        unsafe {
            if const { cfg!(target_endian = "little") } {
                core::mem::transmute::<[i8; 4], u32>([
                    self.seconds.get(),
                    self.minutes.get(),
                    self.hours.get(),
                    0,
                ])
            } else {
                core::mem::transmute::<[i8; 4], u32>([
                    self.hours.get(),
                    self.minutes.get(),
                    self.seconds.get(),
                    0,
                ])
            }
        }
    }

    /// Provide a representation of the `UtcOffset` as a `i32`. This value can be used for ordering.
    /// While it is suitable for equality, `as_u32_for_equality` is preferred for performance
    /// reasons.
    #[inline]
    const fn as_i32_for_comparison(self) -> i32 {
        (self.hours.get() as i32) << 16
            | (self.minutes.get() as i32) << 8
            | (self.seconds.get() as i32)
    }

    /// A `UtcOffset` that is UTC.
    ///
    /// ```rust
    /// # use time::UtcOffset;
    /// # use time_macros::offset;
    /// assert_eq!(UtcOffset::UTC, offset!(UTC));
    /// ```
    pub const UTC: Self = Self::from_whole_seconds_ranged(WholeSeconds::new_static::<0>());

    /// Create a `UtcOffset` representing an offset of the hours, minutes, and seconds provided, the
    /// validity of which must be guaranteed by the caller. All three parameters must have the same
    /// sign.
    ///
    /// # Safety
    ///
    /// - Hours must be in the range `-25..=25`.
    /// - Minutes must be in the range `-59..=59`.
    /// - Seconds must be in the range `-59..=59`.
    ///
    /// While the signs of the parameters are required to match to avoid bugs, this is not a safety
    /// invariant.
    #[doc(hidden)]
    #[inline]
    #[track_caller]
    pub const unsafe fn __from_hms_unchecked(hours: i8, minutes: i8, seconds: i8) -> Self {
        // Safety: The caller must uphold the safety invariants.
        unsafe {
            Self::from_hms_ranged_unchecked(
                Hours::new_unchecked(hours),
                Minutes::new_unchecked(minutes),
                Seconds::new_unchecked(seconds),
            )
        }
    }

    /// Create a `UtcOffset` representing an offset by the number of hours, minutes, and seconds
    /// provided.
    ///
    /// The sign of all three components should match. If they do not, all smaller components will
    /// have their signs flipped.
    ///
    /// ```rust
    /// # use time::UtcOffset;
    /// assert_eq!(UtcOffset::from_hms(1, 2, 3)?.as_hms(), (1, 2, 3));
    /// assert_eq!(UtcOffset::from_hms(1, -2, -3)?.as_hms(), (1, 2, 3));
    /// # Ok::<_, time::Error>(())
    /// ```
    #[inline]
    pub const fn from_hms(
        hours: i8,
        minutes: i8,
        seconds: i8,
    ) -> Result<Self, error::ComponentRange> {
        Ok(Self::from_hms_ranged(
            ensure_ranged!(Hours: hours("offset hour")),
            ensure_ranged!(Minutes: minutes("offset minute")),
            ensure_ranged!(Seconds: seconds("offset second")),
        ))
    }

    /// Create a `UtcOffset` representing an offset of the hours, minutes, and seconds provided. All
    /// three parameters must have the same sign.
    ///
    /// While the signs of the parameters are required to match, this is not a safety invariant.
    #[inline]
    #[track_caller]
    pub(crate) const fn from_hms_ranged_unchecked(
        hours: Hours,
        minutes: Minutes,
        seconds: Seconds,
    ) -> Self {
        if hours.get() < 0 {
            debug_assert!(minutes.get() <= 0);
            debug_assert!(seconds.get() <= 0);
        } else if hours.get() > 0 {
            debug_assert!(minutes.get() >= 0);
            debug_assert!(seconds.get() >= 0);
        }
        if minutes.get() < 0 {
            debug_assert!(seconds.get() <= 0);
        } else if minutes.get() > 0 {
            debug_assert!(seconds.get() >= 0);
        }

        Self {
            hours,
            minutes,
            seconds,
        }
    }

    /// Create a `UtcOffset` representing an offset by the number of hours, minutes, and seconds
    /// provided.
    ///
    /// The sign of all three components should match. If they do not, all smaller components will
    /// have their signs flipped.
    #[inline]
    pub(crate) const fn from_hms_ranged(
        hours: Hours,
        mut minutes: Minutes,
        mut seconds: Seconds,
    ) -> Self {
        if (hours.get() > 0 && minutes.get() < 0) || (hours.get() < 0 && minutes.get() > 0) {
            minutes = minutes.neg();
        }
        if (hours.get() > 0 && seconds.get() < 0)
            || (hours.get() < 0 && seconds.get() > 0)
            || (minutes.get() > 0 && seconds.get() < 0)
            || (minutes.get() < 0 && seconds.get() > 0)
        {
            seconds = seconds.neg();
        }

        Self {
            hours,
            minutes,
            seconds,
        }
    }

    /// Create a `UtcOffset` representing an offset by the number of seconds provided.
    ///
    /// ```rust
    /// # use time::UtcOffset;
    /// assert_eq!(UtcOffset::from_whole_seconds(3_723)?.as_hms(), (1, 2, 3));
    /// # Ok::<_, time::Error>(())
    /// ```
    #[inline]
    pub const fn from_whole_seconds(seconds: i32) -> Result<Self, error::ComponentRange> {
        Ok(Self::from_whole_seconds_ranged(
            ensure_ranged!(WholeSeconds: seconds),
        ))
    }

    /// Create a `UtcOffset` representing an offset by the number of seconds provided.
    // ignore because the function is crate-private
    /// ```rust,ignore
    /// # use time::UtcOffset;
    /// # use deranged::RangedI32;
    /// assert_eq!(
    ///     UtcOffset::from_whole_seconds_ranged(RangedI32::new_static::<3_723>()).as_hms(),
    ///     (1, 2, 3)
    /// );
    /// # Ok::<_, time::Error>(())
    /// ```
    #[inline]
    pub(crate) const fn from_whole_seconds_ranged(seconds: WholeSeconds) -> Self {
        // Safety: The type of `seconds` guarantees that all values are in range.
        unsafe {
            Self::__from_hms_unchecked(
                (seconds.get() / Second::per_t::<i32>(Hour)) as i8,
                ((seconds.get() % Second::per_t::<i32>(Hour)) / Minute::per_t::<i32>(Hour)) as i8,
                (seconds.get() % Second::per_t::<i32>(Minute)) as i8,
            )
        }
    }

    /// Obtain the UTC offset as its hours, minutes, and seconds. The sign of all three components
    /// will always match. A positive value indicates an offset to the east; a negative to the west.
    ///
    /// ```rust
    /// # use time_macros::offset;
    /// assert_eq!(offset!(+1:02:03).as_hms(), (1, 2, 3));
    /// assert_eq!(offset!(-1:02:03).as_hms(), (-1, -2, -3));
    /// ```
    #[inline]
    pub const fn as_hms(self) -> (i8, i8, i8) {
        (self.hours.get(), self.minutes.get(), self.seconds.get())
    }

    /// Obtain the UTC offset as its hours, minutes, and seconds. The sign of all three components
    /// will always match. A positive value indicates an offset to the east; a negative to the west.
    #[cfg(feature = "quickcheck")]
    #[inline]
    pub(crate) const fn as_hms_ranged(self) -> (Hours, Minutes, Seconds) {
        (self.hours, self.minutes, self.seconds)
    }

    /// Obtain the number of whole hours the offset is from UTC. A positive value indicates an
    /// offset to the east; a negative to the west.
    ///
    /// ```rust
    /// # use time_macros::offset;
    /// assert_eq!(offset!(+1:02:03).whole_hours(), 1);
    /// assert_eq!(offset!(-1:02:03).whole_hours(), -1);
    /// ```
    #[inline]
    pub const fn whole_hours(self) -> i8 {
        self.hours.get()
    }

    /// Obtain the number of whole minutes the offset is from UTC. A positive value indicates an
    /// offset to the east; a negative to the west.
    ///
    /// ```rust
    /// # use time_macros::offset;
    /// assert_eq!(offset!(+1:02:03).whole_minutes(), 62);
    /// assert_eq!(offset!(-1:02:03).whole_minutes(), -62);
    /// ```
    #[inline]
    pub const fn whole_minutes(self) -> i16 {
        self.hours.get() as i16 * Minute::per_t::<i16>(Hour) + self.minutes.get() as i16
    }

    /// Obtain the number of minutes past the hour the offset is from UTC. A positive value
    /// indicates an offset to the east; a negative to the west.
    ///
    /// ```rust
    /// # use time_macros::offset;
    /// assert_eq!(offset!(+1:02:03).minutes_past_hour(), 2);
    /// assert_eq!(offset!(-1:02:03).minutes_past_hour(), -2);
    /// ```
    #[inline]
    pub const fn minutes_past_hour(self) -> i8 {
        self.minutes.get()
    }

    /// Obtain the number of whole seconds the offset is from UTC. A positive value indicates an
    /// offset to the east; a negative to the west.
    ///
    /// ```rust
    /// # use time_macros::offset;
    /// assert_eq!(offset!(+1:02:03).whole_seconds(), 3723);
    /// assert_eq!(offset!(-1:02:03).whole_seconds(), -3723);
    /// ```
    // This may be useful for anyone manually implementing arithmetic, as it
    // would let them construct a `Duration` directly.
    #[inline]
    pub const fn whole_seconds(self) -> i32 {
        self.hours.get() as i32 * Second::per_t::<i32>(Hour)
            + self.minutes.get() as i32 * Second::per_t::<i32>(Minute)
            + self.seconds.get() as i32
    }

    /// Obtain the number of seconds past the minute the offset is from UTC. A positive value
    /// indicates an offset to the east; a negative to the west.
    ///
    /// ```rust
    /// # use time_macros::offset;
    /// assert_eq!(offset!(+1:02:03).seconds_past_minute(), 3);
    /// assert_eq!(offset!(-1:02:03).seconds_past_minute(), -3);
    /// ```
    #[inline]
    pub const fn seconds_past_minute(self) -> i8 {
        self.seconds.get()
    }

    /// Check if the offset is exactly UTC.
    ///
    ///
    /// ```rust
    /// # use time_macros::offset;
    /// assert!(!offset!(+1:02:03).is_utc());
    /// assert!(!offset!(-1:02:03).is_utc());
    /// assert!(offset!(UTC).is_utc());
    /// ```
    #[inline]
    pub const fn is_utc(self) -> bool {
        self.as_u32_for_equality() == Self::UTC.as_u32_for_equality()
    }

    /// Check if the offset is positive, or east of UTC.
    ///
    /// ```rust
    /// # use time_macros::offset;
    /// assert!(offset!(+1:02:03).is_positive());
    /// assert!(!offset!(-1:02:03).is_positive());
    /// assert!(!offset!(UTC).is_positive());
    /// ```
    #[inline]
    pub const fn is_positive(self) -> bool {
        self.as_i32_for_comparison() > Self::UTC.as_i32_for_comparison()
    }

    /// Check if the offset is negative, or west of UTC.
    ///
    /// ```rust
    /// # use time_macros::offset;
    /// assert!(!offset!(+1:02:03).is_negative());
    /// assert!(offset!(-1:02:03).is_negative());
    /// assert!(!offset!(UTC).is_negative());
    /// ```
    #[inline]
    pub const fn is_negative(self) -> bool {
        self.as_i32_for_comparison() < Self::UTC.as_i32_for_comparison()
    }

    /// Attempt to obtain the system's UTC offset at a known moment in time. If the offset cannot be
    /// determined, an error is returned.
    ///
    /// ```rust
    /// # use time::{UtcOffset, OffsetDateTime};
    /// let local_offset = UtcOffset::local_offset_at(OffsetDateTime::UNIX_EPOCH);
    /// # if false {
    /// assert!(local_offset.is_ok());
    /// # }
    /// ```
    #[cfg(feature = "local-offset")]
    #[inline]
    pub fn local_offset_at(datetime: OffsetDateTime) -> Result<Self, error::IndeterminateOffset> {
        local_offset_at(datetime).ok_or(error::IndeterminateOffset)
    }

    /// Attempt to obtain the system's current UTC offset. If the offset cannot be determined, an
    /// error is returned.
    ///
    /// ```rust
    /// # use time::UtcOffset;
    /// let local_offset = UtcOffset::current_local_offset();
    /// # if false {
    /// assert!(local_offset.is_ok());
    /// # }
    /// ```
    #[cfg(feature = "local-offset")]
    #[inline]
    pub fn current_local_offset() -> Result<Self, error::IndeterminateOffset> {
        let now = OffsetDateTime::now_utc();
        local_offset_at(now).ok_or(error::IndeterminateOffset)
    }
}

#[cfg(feature = "formatting")]
impl UtcOffset {
    /// Format the `UtcOffset` using the provided [format description](crate::format_description).
    #[inline]
    pub fn format_into(
        self,
        output: &mut (impl io::Write + ?Sized),
        format: &(impl Formattable + ?Sized),
    ) -> Result<usize, error::Format> {
        format.format_into(output, &self, &mut Default::default())
    }

    /// Format the `UtcOffset` using the provided [format description](crate::format_description).
    ///
    /// ```rust
    /// # use time::format_description;
    /// # use time_macros::offset;
    /// let format = format_description::parse("[offset_hour sign:mandatory]:[offset_minute]")?;
    /// assert_eq!(offset!(+1).format(&format)?, "+01:00");
    /// # Ok::<_, time::Error>(())
    /// ```
    #[inline]
    pub fn format(self, format: &(impl Formattable + ?Sized)) -> Result<String, error::Format> {
        format.format(&self, &mut Default::default())
    }
}

#[cfg(feature = "parsing")]
impl UtcOffset {
    /// Parse a `UtcOffset` from the input using the provided [format
    /// description](crate::format_description).
    ///
    /// ```rust
    /// # use time::UtcOffset;
    /// # use time_macros::{offset, format_description};
    /// let format = format_description!("[offset_hour]:[offset_minute]");
    /// assert_eq!(UtcOffset::parse("-03:42", &format)?, offset!(-3:42));
    /// # Ok::<_, time::Error>(())
    /// ```
    #[inline]
    pub fn parse(
        input: &str,
        description: &(impl Parsable + ?Sized),
    ) -> Result<Self, error::Parse> {
        description.parse_offset(input.as_bytes())
    }
}

mod private {
    /// Metadata for `UtcOffset`.
    #[non_exhaustive]
    #[derive(Debug, Clone, Copy)]
    pub struct UtcOffsetMetadata;
}
use private::UtcOffsetMetadata;

impl SmartDisplay for UtcOffset {
    type Metadata = UtcOffsetMetadata;

    #[inline]
    fn metadata(&self, _: FormatterOptions) -> Metadata<'_, Self> {
        let sign = if self.is_negative() { '-' } else { '+' };
        let width = smart_display::padded_width_of!(
            sign,
            self.hours.abs() => width(2),
            ":",
            self.minutes.abs() => width(2),
            ":",
            self.seconds.abs() => width(2),
        );
        Metadata::new(width, self, UtcOffsetMetadata)
    }

    #[inline]
    fn fmt_with_metadata(
        &self,
        f: &mut fmt::Formatter<'_>,
        metadata: Metadata<Self>,
    ) -> fmt::Result {
        f.pad_with_width(
            metadata.unpadded_width(),
            format_args!(
                "{}{:02}:{:02}:{:02}",
                if self.is_negative() { '-' } else { '+' },
                self.hours.abs(),
                self.minutes.abs(),
                self.seconds.abs(),
            ),
        )
    }
}

impl fmt::Display for UtcOffset {
    #[inline]
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        SmartDisplay::fmt(self, f)
    }
}

impl fmt::Debug for UtcOffset {
    #[inline]
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        fmt::Display::fmt(self, f)
    }
}

impl Neg for UtcOffset {
    type Output = Self;

    #[inline]
    fn neg(self) -> Self::Output {
        Self::from_hms_ranged(self.hours.neg(), self.minutes.neg(), self.seconds.neg())
    }
}

Coverage Report

Created: 2026-03-19 06:32

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