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}