time/utc_date_time.rs
1//! The [`UtcDateTime`] struct and associated `impl`s.
2
3#[cfg(feature = "formatting")]
4use alloc::string::String;
5use core::fmt;
6use core::ops::{Add, AddAssign, Sub, SubAssign};
7use core::time::Duration as StdDuration;
8#[cfg(feature = "formatting")]
9use std::io;
10
11use deranged::RangedI64;
12use powerfmt::ext::FormatterExt as _;
13use powerfmt::smart_display::{self, FormatterOptions, Metadata, SmartDisplay};
14
15use crate::convert::*;
16use crate::date::{MAX_YEAR, MIN_YEAR};
17#[cfg(feature = "formatting")]
18use crate::formatting::Formattable;
19use crate::internal_macros::{
20 carry, cascade, const_try, const_try_opt, div_floor, ensure_ranged, expect_opt,
21};
22#[cfg(feature = "parsing")]
23use crate::parsing::Parsable;
24use crate::{
25 error, util, Date, Duration, Month, OffsetDateTime, PrimitiveDateTime, Time, UtcOffset, Weekday,
26};
27
28/// The Julian day of the Unix epoch.
29const UNIX_EPOCH_JULIAN_DAY: i32 = UtcDateTime::UNIX_EPOCH.to_julian_day();
30
31/// A [`PrimitiveDateTime`] that is known to be UTC.
32///
33/// `UtcDateTime` is guaranteed to be ABI-compatible with [`PrimitiveDateTime`], meaning that
34/// transmuting from one to the other will not result in undefined behavior.
35#[repr(transparent)]
36#[derive(Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
37pub struct UtcDateTime {
38 inner: PrimitiveDateTime,
39}
40
41impl UtcDateTime {
42 /// Midnight, 1 January, 1970.
43 ///
44 /// ```rust
45 /// # use time::UtcDateTime;
46 /// # use time_macros::utc_datetime;
47 /// assert_eq!(UtcDateTime::UNIX_EPOCH, utc_datetime!(1970-01-01 0:00));
48 /// ```
49 pub const UNIX_EPOCH: Self = Self::new(Date::UNIX_EPOCH, Time::MIDNIGHT);
50
51 /// The smallest value that can be represented by `UtcDateTime`.
52 ///
53 /// Depending on `large-dates` feature flag, value of this constant may vary.
54 ///
55 /// 1. With `large-dates` disabled it is equal to `-9999-01-01 00:00:00.0`
56 /// 2. With `large-dates` enabled it is equal to `-999999-01-01 00:00:00.0`
57 ///
58 /// ```rust
59 /// # use time::UtcDateTime;
60 /// # use time_macros::utc_datetime;
61 #[cfg_attr(
62 feature = "large-dates",
63 doc = "// Assuming `large-dates` feature is enabled."
64 )]
65 #[cfg_attr(
66 feature = "large-dates",
67 doc = "assert_eq!(UtcDateTime::MIN, utc_datetime!(-999999-01-01 0:00));"
68 )]
69 #[cfg_attr(
70 not(feature = "large-dates"),
71 doc = "// Assuming `large-dates` feature is disabled."
72 )]
73 #[cfg_attr(
74 not(feature = "large-dates"),
75 doc = "assert_eq!(UtcDateTime::MIN, utc_datetime!(-9999-01-01 0:00));"
76 )]
77 /// ```
78 pub const MIN: Self = Self::new(Date::MIN, Time::MIDNIGHT);
79
80 /// The largest value that can be represented by `UtcDateTime`.
81 ///
82 /// Depending on `large-dates` feature flag, value of this constant may vary.
83 ///
84 /// 1. With `large-dates` disabled it is equal to `9999-12-31 23:59:59.999_999_999`
85 /// 2. With `large-dates` enabled it is equal to `999999-12-31 23:59:59.999_999_999`
86 ///
87 /// ```rust
88 /// # use time::UtcDateTime;
89 /// # use time_macros::utc_datetime;
90 #[cfg_attr(
91 feature = "large-dates",
92 doc = "// Assuming `large-dates` feature is enabled."
93 )]
94 #[cfg_attr(
95 feature = "large-dates",
96 doc = "assert_eq!(UtcDateTime::MAX, utc_datetime!(+999999-12-31 23:59:59.999_999_999));"
97 )]
98 #[cfg_attr(
99 not(feature = "large-dates"),
100 doc = "// Assuming `large-dates` feature is disabled."
101 )]
102 #[cfg_attr(
103 not(feature = "large-dates"),
104 doc = "assert_eq!(UtcDateTime::MAX, utc_datetime!(+9999-12-31 23:59:59.999_999_999));"
105 )]
106 /// ```
107 pub const MAX: Self = Self::new(Date::MAX, Time::MAX);
108
109 /// Create a new `UtcDateTime` with the current date and time.
110 ///
111 /// ```rust
112 /// # use time::UtcDateTime;
113 /// assert!(UtcDateTime::now().year() >= 2019);
114 /// ```
115 #[cfg(feature = "std")]
116 #[inline]
117 pub fn now() -> Self {
118 #[cfg(all(
119 target_family = "wasm",
120 not(any(target_os = "emscripten", target_os = "wasi")),
121 feature = "wasm-bindgen"
122 ))]
123 {
124 js_sys::Date::new_0().into()
125 }
126
127 #[cfg(not(all(
128 target_family = "wasm",
129 not(any(target_os = "emscripten", target_os = "wasi")),
130 feature = "wasm-bindgen"
131 )))]
132 std::time::SystemTime::now().into()
133 }
134
135 /// Create a new `UtcDateTime` from the provided [`Date`] and [`Time`].
136 ///
137 /// ```rust
138 /// # use time::UtcDateTime;
139 /// # use time_macros::{date, utc_datetime, time};
140 /// assert_eq!(
141 /// UtcDateTime::new(date!(2019-01-01), time!(0:00)),
142 /// utc_datetime!(2019-01-01 0:00),
143 /// );
144 /// ```
145 #[inline]
146 pub const fn new(date: Date, time: Time) -> Self {
147 Self {
148 inner: PrimitiveDateTime::new(date, time),
149 }
150 }
151
152 /// Create a new `UtcDateTime` from the [`PrimitiveDateTime`], assuming that the latter is UTC.
153 #[inline]
154 pub(crate) const fn from_primitive(date_time: PrimitiveDateTime) -> Self {
155 Self { inner: date_time }
156 }
157
158 /// Obtain the [`PrimitiveDateTime`] that this `UtcDateTime` represents. The no-longer-attached
159 /// [`UtcOffset`] is assumed to be UTC.
160 #[inline]
161 pub(crate) const fn as_primitive(self) -> PrimitiveDateTime {
162 self.inner
163 }
164
165 /// Create a `UtcDateTime` from the provided Unix timestamp.
166 ///
167 /// ```rust
168 /// # use time::UtcDateTime;
169 /// # use time_macros::utc_datetime;
170 /// assert_eq!(
171 /// UtcDateTime::from_unix_timestamp(0),
172 /// Ok(UtcDateTime::UNIX_EPOCH),
173 /// );
174 /// assert_eq!(
175 /// UtcDateTime::from_unix_timestamp(1_546_300_800),
176 /// Ok(utc_datetime!(2019-01-01 0:00)),
177 /// );
178 /// ```
179 ///
180 /// If you have a timestamp-nanosecond pair, you can use something along the lines of the
181 /// following:
182 ///
183 /// ```rust
184 /// # use time::{Duration, UtcDateTime, ext::NumericalDuration};
185 /// let (timestamp, nanos) = (1, 500_000_000);
186 /// assert_eq!(
187 /// UtcDateTime::from_unix_timestamp(timestamp)? + Duration::nanoseconds(nanos),
188 /// UtcDateTime::UNIX_EPOCH + 1.5.seconds()
189 /// );
190 /// # Ok::<_, time::Error>(())
191 /// ```
192 #[inline]
193 pub const fn from_unix_timestamp(timestamp: i64) -> Result<Self, error::ComponentRange> {
194 type Timestamp =
195 RangedI64<{ UtcDateTime::MIN.unix_timestamp() }, { UtcDateTime::MAX.unix_timestamp() }>;
196 ensure_ranged!(Timestamp: timestamp);
197
198 // Use the unchecked method here, as the input validity has already been verified.
199 // Safety: The Julian day number is in range.
200 let date = unsafe {
201 Date::from_julian_day_unchecked(
202 UNIX_EPOCH_JULIAN_DAY + div_floor!(timestamp, Second::per_t::<i64>(Day)) as i32,
203 )
204 };
205
206 let seconds_within_day = timestamp.rem_euclid(Second::per_t::<i64>(Day));
207 // Safety: All values are in range.
208 let time = unsafe {
209 Time::__from_hms_nanos_unchecked(
210 (seconds_within_day / Second::per_t::<i64>(Hour)) as u8,
211 ((seconds_within_day % Second::per_t::<i64>(Hour)) / Minute::per_t::<i64>(Hour))
212 as u8,
213 (seconds_within_day % Second::per_t::<i64>(Minute)) as u8,
214 0,
215 )
216 };
217
218 Ok(Self::new(date, time))
219 }
220
221 /// Construct an `UtcDateTime` from the provided Unix timestamp (in nanoseconds).
222 ///
223 /// ```rust
224 /// # use time::UtcDateTime;
225 /// # use time_macros::utc_datetime;
226 /// assert_eq!(
227 /// UtcDateTime::from_unix_timestamp_nanos(0),
228 /// Ok(UtcDateTime::UNIX_EPOCH),
229 /// );
230 /// assert_eq!(
231 /// UtcDateTime::from_unix_timestamp_nanos(1_546_300_800_000_000_000),
232 /// Ok(utc_datetime!(2019-01-01 0:00)),
233 /// );
234 /// ```
235 #[inline]
236 pub const fn from_unix_timestamp_nanos(timestamp: i128) -> Result<Self, error::ComponentRange> {
237 let datetime = const_try!(Self::from_unix_timestamp(div_floor!(
238 timestamp,
239 Nanosecond::per_t::<i128>(Second)
240 ) as i64));
241
242 Ok(Self::new(
243 datetime.date(),
244 // Safety: `nanosecond` is in range due to `rem_euclid`.
245 unsafe {
246 Time::__from_hms_nanos_unchecked(
247 datetime.hour(),
248 datetime.minute(),
249 datetime.second(),
250 timestamp.rem_euclid(Nanosecond::per_t(Second)) as u32,
251 )
252 },
253 ))
254 }
255
256 /// Convert the `UtcDateTime` from UTC to the provided [`UtcOffset`], returning an
257 /// [`OffsetDateTime`].
258 ///
259 /// ```rust
260 /// # use time_macros::{utc_datetime, offset};
261 /// assert_eq!(
262 /// utc_datetime!(2000-01-01 0:00)
263 /// .to_offset(offset!(-1))
264 /// .year(),
265 /// 1999,
266 /// );
267 ///
268 /// // Construct midnight on new year's, UTC.
269 /// let utc = utc_datetime!(2000-01-01 0:00);
270 /// let new_york = utc.to_offset(offset!(-5));
271 /// let los_angeles = utc.to_offset(offset!(-8));
272 /// assert_eq!(utc.hour(), 0);
273 /// assert_eq!(new_york.hour(), 19);
274 /// assert_eq!(los_angeles.hour(), 16);
275 /// ```
276 ///
277 /// # Panics
278 ///
279 /// This method panics if the local date-time in the new offset is outside the supported range.
280 #[inline]
281 #[track_caller]
282 pub const fn to_offset(self, offset: UtcOffset) -> OffsetDateTime {
283 expect_opt!(
284 self.checked_to_offset(offset),
285 "local datetime out of valid range"
286 )
287 }
288
289 /// Convert the `UtcDateTime` from UTC to the provided [`UtcOffset`], returning an
290 /// [`OffsetDateTime`]. `None` is returned if the date-time in the resulting offset is
291 /// invalid.
292 ///
293 /// ```rust
294 /// # use time::UtcDateTime;
295 /// # use time_macros::{utc_datetime, offset};
296 /// assert_eq!(
297 /// utc_datetime!(2000-01-01 0:00)
298 /// .checked_to_offset(offset!(-1))
299 /// .unwrap()
300 /// .year(),
301 /// 1999,
302 /// );
303 /// assert_eq!(
304 /// UtcDateTime::MAX.checked_to_offset(offset!(+1)),
305 /// None,
306 /// );
307 /// ```
308 #[inline]
309 pub const fn checked_to_offset(self, offset: UtcOffset) -> Option<OffsetDateTime> {
310 // Fast path for when no conversion is necessary.
311 if offset.is_utc() {
312 return Some(self.inner.assume_utc());
313 }
314
315 let (year, ordinal, time) = self.to_offset_raw(offset);
316
317 if year > MAX_YEAR || year < MIN_YEAR {
318 return None;
319 }
320
321 Some(OffsetDateTime::new_in_offset(
322 // Safety: `ordinal` is not zero.
323 unsafe { Date::__from_ordinal_date_unchecked(year, ordinal) },
324 time,
325 offset,
326 ))
327 }
328
329 /// Equivalent to `.to_offset(offset)`, but returning the year, ordinal, and time. This avoids
330 /// constructing an invalid [`Date`] if the new value is out of range.
331 #[inline]
332 pub(crate) const fn to_offset_raw(self, offset: UtcOffset) -> (i32, u16, Time) {
333 let (second, carry) = carry!(@most_once
334 self.second() as i8 + offset.seconds_past_minute(),
335 0..Second::per_t(Minute)
336 );
337 let (minute, carry) = carry!(@most_once
338 self.minute() as i8 + offset.minutes_past_hour() + carry,
339 0..Minute::per_t(Hour)
340 );
341 let (hour, carry) = carry!(@most_twice
342 self.hour() as i8 + offset.whole_hours() + carry,
343 0..Hour::per_t(Day)
344 );
345 let (mut year, ordinal) = self.to_ordinal_date();
346 let mut ordinal = ordinal as i16 + carry;
347 cascade!(ordinal => year);
348
349 debug_assert!(ordinal > 0);
350 debug_assert!(ordinal <= util::days_in_year(year) as i16);
351
352 (
353 year,
354 ordinal as u16,
355 // Safety: The cascades above ensure the values are in range.
356 unsafe {
357 Time::__from_hms_nanos_unchecked(
358 hour as u8,
359 minute as u8,
360 second as u8,
361 self.nanosecond(),
362 )
363 },
364 )
365 }
366
367 /// Get the [Unix timestamp](https://en.wikipedia.org/wiki/Unix_time).
368 ///
369 /// ```rust
370 /// # use time_macros::utc_datetime;
371 /// assert_eq!(utc_datetime!(1970-01-01 0:00).unix_timestamp(), 0);
372 /// assert_eq!(utc_datetime!(1970-01-01 1:00).unix_timestamp(), 3_600);
373 /// ```
374 #[inline]
375 pub const fn unix_timestamp(self) -> i64 {
376 let days = (self.to_julian_day() as i64 - UNIX_EPOCH_JULIAN_DAY as i64)
377 * Second::per_t::<i64>(Day);
378 let hours = self.hour() as i64 * Second::per_t::<i64>(Hour);
379 let minutes = self.minute() as i64 * Second::per_t::<i64>(Minute);
380 let seconds = self.second() as i64;
381 days + hours + minutes + seconds
382 }
383
384 /// Get the Unix timestamp in nanoseconds.
385 ///
386 /// ```rust
387 /// use time_macros::utc_datetime;
388 /// assert_eq!(utc_datetime!(1970-01-01 0:00).unix_timestamp_nanos(), 0);
389 /// assert_eq!(
390 /// utc_datetime!(1970-01-01 1:00).unix_timestamp_nanos(),
391 /// 3_600_000_000_000,
392 /// );
393 /// ```
394 #[inline]
395 pub const fn unix_timestamp_nanos(self) -> i128 {
396 self.unix_timestamp() as i128 * Nanosecond::per_t::<i128>(Second)
397 + self.nanosecond() as i128
398 }
399
400 /// Get the [`Date`] component of the `UtcDateTime`.
401 ///
402 /// ```rust
403 /// # use time_macros::{date, utc_datetime};
404 /// assert_eq!(utc_datetime!(2019-01-01 0:00).date(), date!(2019-01-01));
405 /// ```
406 #[inline]
407 pub const fn date(self) -> Date {
408 self.inner.date()
409 }
410
411 /// Get the [`Time`] component of the `UtcDateTime`.
412 ///
413 /// ```rust
414 /// # use time_macros::{utc_datetime, time};
415 /// assert_eq!(utc_datetime!(2019-01-01 0:00).time(), time!(0:00));
416 /// ```
417 #[inline]
418 pub const fn time(self) -> Time {
419 self.inner.time()
420 }
421
422 /// Get the year of the date.
423 ///
424 /// ```rust
425 /// # use time_macros::utc_datetime;
426 /// assert_eq!(utc_datetime!(2019-01-01 0:00).year(), 2019);
427 /// assert_eq!(utc_datetime!(2019-12-31 0:00).year(), 2019);
428 /// assert_eq!(utc_datetime!(2020-01-01 0:00).year(), 2020);
429 /// ```
430 #[inline]
431 pub const fn year(self) -> i32 {
432 self.date().year()
433 }
434
435 /// Get the month of the date.
436 ///
437 /// ```rust
438 /// # use time::Month;
439 /// # use time_macros::utc_datetime;
440 /// assert_eq!(utc_datetime!(2019-01-01 0:00).month(), Month::January);
441 /// assert_eq!(utc_datetime!(2019-12-31 0:00).month(), Month::December);
442 /// ```
443 #[inline]
444 pub const fn month(self) -> Month {
445 self.date().month()
446 }
447
448 /// Get the day of the date.
449 ///
450 /// The returned value will always be in the range `1..=31`.
451 ///
452 /// ```rust
453 /// # use time_macros::utc_datetime;
454 /// assert_eq!(utc_datetime!(2019-01-01 0:00).day(), 1);
455 /// assert_eq!(utc_datetime!(2019-12-31 0:00).day(), 31);
456 /// ```
457 #[inline]
458 pub const fn day(self) -> u8 {
459 self.date().day()
460 }
461
462 /// Get the day of the year.
463 ///
464 /// The returned value will always be in the range `1..=366` (`1..=365` for common years).
465 ///
466 /// ```rust
467 /// # use time_macros::utc_datetime;
468 /// assert_eq!(utc_datetime!(2019-01-01 0:00).ordinal(), 1);
469 /// assert_eq!(utc_datetime!(2019-12-31 0:00).ordinal(), 365);
470 /// ```
471 #[inline]
472 pub const fn ordinal(self) -> u16 {
473 self.date().ordinal()
474 }
475
476 /// Get the ISO week number.
477 ///
478 /// The returned value will always be in the range `1..=53`.
479 ///
480 /// ```rust
481 /// # use time_macros::utc_datetime;
482 /// assert_eq!(utc_datetime!(2019-01-01 0:00).iso_week(), 1);
483 /// assert_eq!(utc_datetime!(2019-10-04 0:00).iso_week(), 40);
484 /// assert_eq!(utc_datetime!(2020-01-01 0:00).iso_week(), 1);
485 /// assert_eq!(utc_datetime!(2020-12-31 0:00).iso_week(), 53);
486 /// assert_eq!(utc_datetime!(2021-01-01 0:00).iso_week(), 53);
487 /// ```
488 #[inline]
489 pub const fn iso_week(self) -> u8 {
490 self.date().iso_week()
491 }
492
493 /// Get the week number where week 1 begins on the first Sunday.
494 ///
495 /// The returned value will always be in the range `0..=53`.
496 ///
497 /// ```rust
498 /// # use time_macros::utc_datetime;
499 /// assert_eq!(utc_datetime!(2019-01-01 0:00).sunday_based_week(), 0);
500 /// assert_eq!(utc_datetime!(2020-01-01 0:00).sunday_based_week(), 0);
501 /// assert_eq!(utc_datetime!(2020-12-31 0:00).sunday_based_week(), 52);
502 /// assert_eq!(utc_datetime!(2021-01-01 0:00).sunday_based_week(), 0);
503 /// ```
504 #[inline]
505 pub const fn sunday_based_week(self) -> u8 {
506 self.date().sunday_based_week()
507 }
508
509 /// Get the week number where week 1 begins on the first Monday.
510 ///
511 /// The returned value will always be in the range `0..=53`.
512 ///
513 /// ```rust
514 /// # use time_macros::utc_datetime;
515 /// assert_eq!(utc_datetime!(2019-01-01 0:00).monday_based_week(), 0);
516 /// assert_eq!(utc_datetime!(2020-01-01 0:00).monday_based_week(), 0);
517 /// assert_eq!(utc_datetime!(2020-12-31 0:00).monday_based_week(), 52);
518 /// assert_eq!(utc_datetime!(2021-01-01 0:00).monday_based_week(), 0);
519 /// ```
520 #[inline]
521 pub const fn monday_based_week(self) -> u8 {
522 self.date().monday_based_week()
523 }
524
525 /// Get the year, month, and day.
526 ///
527 /// ```rust
528 /// # use time::Month;
529 /// # use time_macros::utc_datetime;
530 /// assert_eq!(
531 /// utc_datetime!(2019-01-01 0:00).to_calendar_date(),
532 /// (2019, Month::January, 1)
533 /// );
534 /// ```
535 #[inline]
536 pub const fn to_calendar_date(self) -> (i32, Month, u8) {
537 self.date().to_calendar_date()
538 }
539
540 /// Get the year and ordinal day number.
541 ///
542 /// ```rust
543 /// # use time_macros::utc_datetime;
544 /// assert_eq!(utc_datetime!(2019-01-01 0:00).to_ordinal_date(), (2019, 1));
545 /// ```
546 #[inline]
547 pub const fn to_ordinal_date(self) -> (i32, u16) {
548 self.date().to_ordinal_date()
549 }
550
551 /// Get the ISO 8601 year, week number, and weekday.
552 ///
553 /// ```rust
554 /// # use time::Weekday::*;
555 /// # use time_macros::utc_datetime;
556 /// assert_eq!(
557 /// utc_datetime!(2019-01-01 0:00).to_iso_week_date(),
558 /// (2019, 1, Tuesday)
559 /// );
560 /// assert_eq!(
561 /// utc_datetime!(2019-10-04 0:00).to_iso_week_date(),
562 /// (2019, 40, Friday)
563 /// );
564 /// assert_eq!(
565 /// utc_datetime!(2020-01-01 0:00).to_iso_week_date(),
566 /// (2020, 1, Wednesday)
567 /// );
568 /// assert_eq!(
569 /// utc_datetime!(2020-12-31 0:00).to_iso_week_date(),
570 /// (2020, 53, Thursday)
571 /// );
572 /// assert_eq!(
573 /// utc_datetime!(2021-01-01 0:00).to_iso_week_date(),
574 /// (2020, 53, Friday)
575 /// );
576 /// ```
577 #[inline]
578 pub const fn to_iso_week_date(self) -> (i32, u8, Weekday) {
579 self.date().to_iso_week_date()
580 }
581
582 /// Get the weekday.
583 ///
584 /// ```rust
585 /// # use time::Weekday::*;
586 /// # use time_macros::utc_datetime;
587 /// assert_eq!(utc_datetime!(2019-01-01 0:00).weekday(), Tuesday);
588 /// assert_eq!(utc_datetime!(2019-02-01 0:00).weekday(), Friday);
589 /// assert_eq!(utc_datetime!(2019-03-01 0:00).weekday(), Friday);
590 /// assert_eq!(utc_datetime!(2019-04-01 0:00).weekday(), Monday);
591 /// assert_eq!(utc_datetime!(2019-05-01 0:00).weekday(), Wednesday);
592 /// assert_eq!(utc_datetime!(2019-06-01 0:00).weekday(), Saturday);
593 /// assert_eq!(utc_datetime!(2019-07-01 0:00).weekday(), Monday);
594 /// assert_eq!(utc_datetime!(2019-08-01 0:00).weekday(), Thursday);
595 /// assert_eq!(utc_datetime!(2019-09-01 0:00).weekday(), Sunday);
596 /// assert_eq!(utc_datetime!(2019-10-01 0:00).weekday(), Tuesday);
597 /// assert_eq!(utc_datetime!(2019-11-01 0:00).weekday(), Friday);
598 /// assert_eq!(utc_datetime!(2019-12-01 0:00).weekday(), Sunday);
599 /// ```
600 #[inline]
601 pub const fn weekday(self) -> Weekday {
602 self.date().weekday()
603 }
604
605 /// Get the Julian day for the date. The time is not taken into account for this calculation.
606 ///
607 /// The algorithm to perform this conversion is derived from one provided by Peter Baum; it is
608 /// freely available [here](https://www.researchgate.net/publication/316558298_Date_Algorithms).
609 ///
610 /// ```rust
611 /// # use time_macros::utc_datetime;
612 /// assert_eq!(utc_datetime!(-4713-11-24 0:00).to_julian_day(), 0);
613 /// assert_eq!(utc_datetime!(2000-01-01 0:00).to_julian_day(), 2_451_545);
614 /// assert_eq!(utc_datetime!(2019-01-01 0:00).to_julian_day(), 2_458_485);
615 /// assert_eq!(utc_datetime!(2019-12-31 0:00).to_julian_day(), 2_458_849);
616 /// ```
617 #[inline]
618 pub const fn to_julian_day(self) -> i32 {
619 self.date().to_julian_day()
620 }
621
622 /// Get the clock hour, minute, and second.
623 ///
624 /// ```rust
625 /// # use time_macros::utc_datetime;
626 /// assert_eq!(utc_datetime!(2020-01-01 0:00:00).as_hms(), (0, 0, 0));
627 /// assert_eq!(utc_datetime!(2020-01-01 23:59:59).as_hms(), (23, 59, 59));
628 /// ```
629 #[inline]
630 pub const fn as_hms(self) -> (u8, u8, u8) {
631 self.time().as_hms()
632 }
633
634 /// Get the clock hour, minute, second, and millisecond.
635 ///
636 /// ```rust
637 /// # use time_macros::utc_datetime;
638 /// assert_eq!(utc_datetime!(2020-01-01 0:00:00).as_hms_milli(), (0, 0, 0, 0));
639 /// assert_eq!(
640 /// utc_datetime!(2020-01-01 23:59:59.999).as_hms_milli(),
641 /// (23, 59, 59, 999)
642 /// );
643 /// ```
644 #[inline]
645 pub const fn as_hms_milli(self) -> (u8, u8, u8, u16) {
646 self.time().as_hms_milli()
647 }
648
649 /// Get the clock hour, minute, second, and microsecond.
650 ///
651 /// ```rust
652 /// # use time_macros::utc_datetime;
653 /// assert_eq!(utc_datetime!(2020-01-01 0:00:00).as_hms_micro(), (0, 0, 0, 0));
654 /// assert_eq!(
655 /// utc_datetime!(2020-01-01 23:59:59.999_999).as_hms_micro(),
656 /// (23, 59, 59, 999_999)
657 /// );
658 /// ```
659 #[inline]
660 pub const fn as_hms_micro(self) -> (u8, u8, u8, u32) {
661 self.time().as_hms_micro()
662 }
663
664 /// Get the clock hour, minute, second, and nanosecond.
665 ///
666 /// ```rust
667 /// # use time_macros::utc_datetime;
668 /// assert_eq!(utc_datetime!(2020-01-01 0:00:00).as_hms_nano(), (0, 0, 0, 0));
669 /// assert_eq!(
670 /// utc_datetime!(2020-01-01 23:59:59.999_999_999).as_hms_nano(),
671 /// (23, 59, 59, 999_999_999)
672 /// );
673 /// ```
674 #[inline]
675 pub const fn as_hms_nano(self) -> (u8, u8, u8, u32) {
676 self.time().as_hms_nano()
677 }
678
679 /// Get the clock hour.
680 ///
681 /// The returned value will always be in the range `0..24`.
682 ///
683 /// ```rust
684 /// # use time_macros::utc_datetime;
685 /// assert_eq!(utc_datetime!(2019-01-01 0:00).hour(), 0);
686 /// assert_eq!(utc_datetime!(2019-01-01 23:59:59).hour(), 23);
687 /// ```
688 #[inline]
689 pub const fn hour(self) -> u8 {
690 self.time().hour()
691 }
692
693 /// Get the minute within the hour.
694 ///
695 /// The returned value will always be in the range `0..60`.
696 ///
697 /// ```rust
698 /// # use time_macros::utc_datetime;
699 /// assert_eq!(utc_datetime!(2019-01-01 0:00).minute(), 0);
700 /// assert_eq!(utc_datetime!(2019-01-01 23:59:59).minute(), 59);
701 /// ```
702 #[inline]
703 pub const fn minute(self) -> u8 {
704 self.time().minute()
705 }
706
707 /// Get the second within the minute.
708 ///
709 /// The returned value will always be in the range `0..60`.
710 ///
711 /// ```rust
712 /// # use time_macros::utc_datetime;
713 /// assert_eq!(utc_datetime!(2019-01-01 0:00).second(), 0);
714 /// assert_eq!(utc_datetime!(2019-01-01 23:59:59).second(), 59);
715 /// ```
716 #[inline]
717 pub const fn second(self) -> u8 {
718 self.time().second()
719 }
720
721 /// Get the milliseconds within the second.
722 ///
723 /// The returned value will always be in the range `0..1_000`.
724 ///
725 /// ```rust
726 /// # use time_macros::utc_datetime;
727 /// assert_eq!(utc_datetime!(2019-01-01 0:00).millisecond(), 0);
728 /// assert_eq!(utc_datetime!(2019-01-01 23:59:59.999).millisecond(), 999);
729 /// ```
730 #[inline]
731 pub const fn millisecond(self) -> u16 {
732 self.time().millisecond()
733 }
734
735 /// Get the microseconds within the second.
736 ///
737 /// The returned value will always be in the range `0..1_000_000`.
738 ///
739 /// ```rust
740 /// # use time_macros::utc_datetime;
741 /// assert_eq!(utc_datetime!(2019-01-01 0:00).microsecond(), 0);
742 /// assert_eq!(
743 /// utc_datetime!(2019-01-01 23:59:59.999_999).microsecond(),
744 /// 999_999
745 /// );
746 /// ```
747 #[inline]
748 pub const fn microsecond(self) -> u32 {
749 self.time().microsecond()
750 }
751
752 /// Get the nanoseconds within the second.
753 ///
754 /// The returned value will always be in the range `0..1_000_000_000`.
755 ///
756 /// ```rust
757 /// # use time_macros::utc_datetime;
758 /// assert_eq!(utc_datetime!(2019-01-01 0:00).nanosecond(), 0);
759 /// assert_eq!(
760 /// utc_datetime!(2019-01-01 23:59:59.999_999_999).nanosecond(),
761 /// 999_999_999,
762 /// );
763 /// ```
764 #[inline]
765 pub const fn nanosecond(self) -> u32 {
766 self.time().nanosecond()
767 }
768
769 /// Computes `self + duration`, returning `None` if an overflow occurred.
770 ///
771 /// ```rust
772 /// # use time::{UtcDateTime, ext::NumericalDuration};
773 /// # use time_macros::utc_datetime;
774 /// assert_eq!(UtcDateTime::MIN.checked_add((-2).days()), None);
775 /// assert_eq!(UtcDateTime::MAX.checked_add(1.days()), None);
776 /// assert_eq!(
777 /// utc_datetime!(2019 - 11 - 25 15:30).checked_add(27.hours()),
778 /// Some(utc_datetime!(2019 - 11 - 26 18:30))
779 /// );
780 /// ```
781 #[inline]
782 pub const fn checked_add(self, duration: Duration) -> Option<Self> {
783 Some(Self::from_primitive(const_try_opt!(self
784 .inner
785 .checked_add(duration))))
786 }
787
788 /// Computes `self - duration`, returning `None` if an overflow occurred.
789 ///
790 /// ```rust
791 /// # use time::{UtcDateTime, ext::NumericalDuration};
792 /// # use time_macros::utc_datetime;
793 /// assert_eq!(UtcDateTime::MIN.checked_sub(2.days()), None);
794 /// assert_eq!(UtcDateTime::MAX.checked_sub((-1).days()), None);
795 /// assert_eq!(
796 /// utc_datetime!(2019 - 11 - 25 15:30).checked_sub(27.hours()),
797 /// Some(utc_datetime!(2019 - 11 - 24 12:30))
798 /// );
799 /// ```
800 #[inline]
801 pub const fn checked_sub(self, duration: Duration) -> Option<Self> {
802 Some(Self::from_primitive(const_try_opt!(self
803 .inner
804 .checked_sub(duration))))
805 }
806
807 /// Computes `self + duration`, saturating value on overflow.
808 ///
809 /// ```rust
810 /// # use time::{UtcDateTime, ext::NumericalDuration};
811 /// # use time_macros::utc_datetime;
812 /// assert_eq!(
813 /// UtcDateTime::MIN.saturating_add((-2).days()),
814 /// UtcDateTime::MIN
815 /// );
816 /// assert_eq!(
817 /// UtcDateTime::MAX.saturating_add(2.days()),
818 /// UtcDateTime::MAX
819 /// );
820 /// assert_eq!(
821 /// utc_datetime!(2019 - 11 - 25 15:30).saturating_add(27.hours()),
822 /// utc_datetime!(2019 - 11 - 26 18:30)
823 /// );
824 /// ```
825 #[inline]
826 pub const fn saturating_add(self, duration: Duration) -> Self {
827 Self::from_primitive(self.inner.saturating_add(duration))
828 }
829
830 /// Computes `self - duration`, saturating value on overflow.
831 ///
832 /// ```rust
833 /// # use time::{UtcDateTime, ext::NumericalDuration};
834 /// # use time_macros::utc_datetime;
835 /// assert_eq!(
836 /// UtcDateTime::MIN.saturating_sub(2.days()),
837 /// UtcDateTime::MIN
838 /// );
839 /// assert_eq!(
840 /// UtcDateTime::MAX.saturating_sub((-2).days()),
841 /// UtcDateTime::MAX
842 /// );
843 /// assert_eq!(
844 /// utc_datetime!(2019 - 11 - 25 15:30).saturating_sub(27.hours()),
845 /// utc_datetime!(2019 - 11 - 24 12:30)
846 /// );
847 /// ```
848 #[inline]
849 pub const fn saturating_sub(self, duration: Duration) -> Self {
850 Self::from_primitive(self.inner.saturating_sub(duration))
851 }
852}
853
854/// Methods that replace part of the `UtcDateTime`.
855impl UtcDateTime {
856 /// Replace the time, preserving the date.
857 ///
858 /// ```rust
859 /// # use time_macros::{utc_datetime, time};
860 /// assert_eq!(
861 /// utc_datetime!(2020-01-01 17:00).replace_time(time!(5:00)),
862 /// utc_datetime!(2020-01-01 5:00)
863 /// );
864 /// ```
865 #[must_use = "This method does not mutate the original `UtcDateTime`."]
866 #[inline]
867 pub const fn replace_time(self, time: Time) -> Self {
868 Self::from_primitive(self.inner.replace_time(time))
869 }
870
871 /// Replace the date, preserving the time.
872 ///
873 /// ```rust
874 /// # use time_macros::{utc_datetime, date};
875 /// assert_eq!(
876 /// utc_datetime!(2020-01-01 12:00).replace_date(date!(2020-01-30)),
877 /// utc_datetime!(2020-01-30 12:00)
878 /// );
879 /// ```
880 #[must_use = "This method does not mutate the original `UtcDateTime`."]
881 #[inline]
882 pub const fn replace_date(self, date: Date) -> Self {
883 Self::from_primitive(self.inner.replace_date(date))
884 }
885
886 /// Replace the year. The month and day will be unchanged.
887 ///
888 /// ```rust
889 /// # use time_macros::utc_datetime;
890 /// assert_eq!(
891 /// utc_datetime!(2022 - 02 - 18 12:00).replace_year(2019),
892 /// Ok(utc_datetime!(2019 - 02 - 18 12:00))
893 /// );
894 /// assert!(utc_datetime!(2022 - 02 - 18 12:00).replace_year(-1_000_000_000).is_err()); // -1_000_000_000 isn't a valid year
895 /// assert!(utc_datetime!(2022 - 02 - 18 12:00).replace_year(1_000_000_000).is_err()); // 1_000_000_000 isn't a valid year
896 /// ```
897 #[must_use = "This method does not mutate the original `UtcDateTime`."]
898 #[inline]
899 pub const fn replace_year(self, year: i32) -> Result<Self, error::ComponentRange> {
900 Ok(Self::from_primitive(const_try!(self
901 .inner
902 .replace_year(year))))
903 }
904
905 /// Replace the month of the year.
906 ///
907 /// ```rust
908 /// # use time_macros::utc_datetime;
909 /// # use time::Month;
910 /// assert_eq!(
911 /// utc_datetime!(2022 - 02 - 18 12:00).replace_month(Month::January),
912 /// Ok(utc_datetime!(2022 - 01 - 18 12:00))
913 /// );
914 /// assert!(utc_datetime!(2022 - 01 - 30 12:00).replace_month(Month::February).is_err()); // 30 isn't a valid day in February
915 /// ```
916 #[must_use = "This method does not mutate the original `UtcDateTime`."]
917 #[inline]
918 pub const fn replace_month(self, month: Month) -> Result<Self, error::ComponentRange> {
919 Ok(Self::from_primitive(const_try!(self
920 .inner
921 .replace_month(month))))
922 }
923
924 /// Replace the day of the month.
925 ///
926 /// ```rust
927 /// # use time_macros::utc_datetime;
928 /// assert_eq!(
929 /// utc_datetime!(2022 - 02 - 18 12:00).replace_day(1),
930 /// Ok(utc_datetime!(2022 - 02 - 01 12:00))
931 /// );
932 /// assert!(utc_datetime!(2022 - 02 - 18 12:00).replace_day(0).is_err()); // 00 isn't a valid day
933 /// assert!(utc_datetime!(2022 - 02 - 18 12:00).replace_day(30).is_err()); // 30 isn't a valid day in February
934 /// ```
935 #[must_use = "This method does not mutate the original `UtcDateTime`."]
936 #[inline]
937 pub const fn replace_day(self, day: u8) -> Result<Self, error::ComponentRange> {
938 Ok(Self::from_primitive(const_try!(self
939 .inner
940 .replace_day(day))))
941 }
942
943 /// Replace the day of the year.
944 ///
945 /// ```rust
946 /// # use time_macros::utc_datetime;
947 /// assert_eq!(utc_datetime!(2022-049 12:00).replace_ordinal(1), Ok(utc_datetime!(2022-001 12:00)));
948 /// assert!(utc_datetime!(2022-049 12:00).replace_ordinal(0).is_err()); // 0 isn't a valid ordinal
949 /// assert!(utc_datetime!(2022-049 12:00).replace_ordinal(366).is_err()); // 2022 isn't a leap year
950 /// ```
951 #[must_use = "This method does not mutate the original `UtcDateTime`."]
952 #[inline]
953 pub const fn replace_ordinal(self, ordinal: u16) -> Result<Self, error::ComponentRange> {
954 Ok(Self::from_primitive(const_try!(self
955 .inner
956 .replace_ordinal(ordinal))))
957 }
958
959 /// Replace the clock hour.
960 ///
961 /// ```rust
962 /// # use time_macros::utc_datetime;
963 /// assert_eq!(
964 /// utc_datetime!(2022 - 02 - 18 01:02:03.004_005_006).replace_hour(7),
965 /// Ok(utc_datetime!(2022 - 02 - 18 07:02:03.004_005_006))
966 /// );
967 /// assert!(utc_datetime!(2022 - 02 - 18 01:02:03.004_005_006).replace_hour(24).is_err()); // 24 isn't a valid hour
968 /// ```
969 #[must_use = "This method does not mutate the original `UtcDateTime`."]
970 #[inline]
971 pub const fn replace_hour(self, hour: u8) -> Result<Self, error::ComponentRange> {
972 Ok(Self::from_primitive(const_try!(self
973 .inner
974 .replace_hour(hour))))
975 }
976
977 /// Replace the minutes within the hour.
978 ///
979 /// ```rust
980 /// # use time_macros::utc_datetime;
981 /// assert_eq!(
982 /// utc_datetime!(2022 - 02 - 18 01:02:03.004_005_006).replace_minute(7),
983 /// Ok(utc_datetime!(2022 - 02 - 18 01:07:03.004_005_006))
984 /// );
985 /// assert!(utc_datetime!(2022 - 02 - 18 01:02:03.004_005_006).replace_minute(60).is_err()); // 60 isn't a valid minute
986 /// ```
987 #[must_use = "This method does not mutate the original `UtcDateTime`."]
988 #[inline]
989 pub const fn replace_minute(
990 self,
991 sunday_based_week: u8,
992 ) -> Result<Self, error::ComponentRange> {
993 Ok(Self::from_primitive(const_try!(self
994 .inner
995 .replace_minute(sunday_based_week))))
996 }
997
998 /// Replace the seconds within the minute.
999 ///
1000 /// ```rust
1001 /// # use time_macros::utc_datetime;
1002 /// assert_eq!(
1003 /// utc_datetime!(2022 - 02 - 18 01:02:03.004_005_006).replace_second(7),
1004 /// Ok(utc_datetime!(2022 - 02 - 18 01:02:07.004_005_006))
1005 /// );
1006 /// assert!(utc_datetime!(2022 - 02 - 18 01:02:03.004_005_006).replace_second(60).is_err()); // 60 isn't a valid second
1007 /// ```
1008 #[must_use = "This method does not mutate the original `UtcDateTime`."]
1009 #[inline]
1010 pub const fn replace_second(
1011 self,
1012 monday_based_week: u8,
1013 ) -> Result<Self, error::ComponentRange> {
1014 Ok(Self::from_primitive(const_try!(self
1015 .inner
1016 .replace_second(monday_based_week))))
1017 }
1018
1019 /// Replace the milliseconds within the second.
1020 ///
1021 /// ```rust
1022 /// # use time_macros::utc_datetime;
1023 /// assert_eq!(
1024 /// utc_datetime!(2022 - 02 - 18 01:02:03.004_005_006).replace_millisecond(7),
1025 /// Ok(utc_datetime!(2022 - 02 - 18 01:02:03.007))
1026 /// );
1027 /// assert!(utc_datetime!(2022 - 02 - 18 01:02:03.004_005_006).replace_millisecond(1_000).is_err()); // 1_000 isn't a valid millisecond
1028 /// ```
1029 #[must_use = "This method does not mutate the original `UtcDateTime`."]
1030 #[inline]
1031 pub const fn replace_millisecond(
1032 self,
1033 millisecond: u16,
1034 ) -> Result<Self, error::ComponentRange> {
1035 Ok(Self::from_primitive(const_try!(self
1036 .inner
1037 .replace_millisecond(millisecond))))
1038 }
1039
1040 /// Replace the microseconds within the second.
1041 ///
1042 /// ```rust
1043 /// # use time_macros::utc_datetime;
1044 /// assert_eq!(
1045 /// utc_datetime!(2022 - 02 - 18 01:02:03.004_005_006).replace_microsecond(7_008),
1046 /// Ok(utc_datetime!(2022 - 02 - 18 01:02:03.007_008))
1047 /// );
1048 /// assert!(utc_datetime!(2022 - 02 - 18 01:02:03.004_005_006).replace_microsecond(1_000_000).is_err()); // 1_000_000 isn't a valid microsecond
1049 /// ```
1050 #[must_use = "This method does not mutate the original `UtcDateTime`."]
1051 #[inline]
1052 pub const fn replace_microsecond(
1053 self,
1054 microsecond: u32,
1055 ) -> Result<Self, error::ComponentRange> {
1056 Ok(Self::from_primitive(const_try!(self
1057 .inner
1058 .replace_microsecond(microsecond))))
1059 }
1060
1061 /// Replace the nanoseconds within the second.
1062 ///
1063 /// ```rust
1064 /// # use time_macros::utc_datetime;
1065 /// assert_eq!(
1066 /// utc_datetime!(2022 - 02 - 18 01:02:03.004_005_006).replace_nanosecond(7_008_009),
1067 /// Ok(utc_datetime!(2022 - 02 - 18 01:02:03.007_008_009))
1068 /// );
1069 /// assert!(utc_datetime!(2022 - 02 - 18 01:02:03.004_005_006).replace_nanosecond(1_000_000_000).is_err()); // 1_000_000_000 isn't a valid nanosecond
1070 /// ```
1071 #[must_use = "This method does not mutate the original `UtcDateTime`."]
1072 #[inline]
1073 pub const fn replace_nanosecond(self, nanosecond: u32) -> Result<Self, error::ComponentRange> {
1074 Ok(Self::from_primitive(const_try!(self
1075 .inner
1076 .replace_nanosecond(nanosecond))))
1077 }
1078}
1079
1080#[cfg(feature = "formatting")]
1081impl UtcDateTime {
1082 /// Format the `UtcDateTime` using the provided [format
1083 /// description](crate::format_description).
1084 #[inline]
1085 pub fn format_into(
1086 self,
1087 output: &mut (impl io::Write + ?Sized),
1088 format: &(impl Formattable + ?Sized),
1089 ) -> Result<usize, error::Format> {
1090 format.format_into(
1091 output,
1092 Some(self.date()),
1093 Some(self.time()),
1094 Some(UtcOffset::UTC),
1095 )
1096 }
1097
1098 /// Format the `UtcDateTime` using the provided [format
1099 /// description](crate::format_description).
1100 ///
1101 /// ```rust
1102 /// # use time::format_description;
1103 /// # use time_macros::utc_datetime;
1104 /// let format = format_description::parse(
1105 /// "[year]-[month]-[day] [hour]:[minute]:[second] [offset_hour \
1106 /// sign:mandatory]:[offset_minute]:[offset_second]",
1107 /// )?;
1108 /// assert_eq!(
1109 /// utc_datetime!(2020-01-02 03:04:05).format(&format)?,
1110 /// "2020-01-02 03:04:05 +00:00:00"
1111 /// );
1112 /// # Ok::<_, time::Error>(())
1113 /// ```
1114 #[inline]
1115 pub fn format(self, format: &(impl Formattable + ?Sized)) -> Result<String, error::Format> {
1116 format.format(Some(self.date()), Some(self.time()), Some(UtcOffset::UTC))
1117 }
1118}
1119
1120#[cfg(feature = "parsing")]
1121impl UtcDateTime {
1122 /// Parse an `UtcDateTime` from the input using the provided [format
1123 /// description](crate::format_description). A [`UtcOffset`] is permitted, but not required to
1124 /// be present. If present, the value will be converted to UTC.
1125 ///
1126 /// ```rust
1127 /// # use time::UtcDateTime;
1128 /// # use time_macros::{utc_datetime, format_description};
1129 /// let format = format_description!("[year]-[month]-[day] [hour]:[minute]:[second]");
1130 /// assert_eq!(
1131 /// UtcDateTime::parse("2020-01-02 03:04:05", &format)?,
1132 /// utc_datetime!(2020-01-02 03:04:05)
1133 /// );
1134 /// # Ok::<_, time::Error>(())
1135 /// ```
1136 #[inline]
1137 pub fn parse(
1138 input: &str,
1139 description: &(impl Parsable + ?Sized),
1140 ) -> Result<Self, error::Parse> {
1141 description.parse_utc_date_time(input.as_bytes())
1142 }
1143
1144 /// A helper method to check if the `UtcDateTime` is a valid representation of a leap second.
1145 /// Leap seconds, when parsed, are represented as the preceding nanosecond. However, leap
1146 /// seconds can only occur as the last second of a month UTC.
1147 #[cfg(feature = "parsing")]
1148 #[inline]
1149 pub(crate) const fn is_valid_leap_second_stand_in(self) -> bool {
1150 let dt = self.inner;
1151
1152 dt.hour() == 23
1153 && dt.minute() == 59
1154 && dt.second() == 59
1155 && dt.nanosecond() == 999_999_999
1156 && dt.day() == dt.month().length(dt.year())
1157 }
1158}
1159
1160impl SmartDisplay for UtcDateTime {
1161 type Metadata = ();
1162
1163 #[inline]
1164 fn metadata(&self, _: FormatterOptions) -> Metadata<'_, Self> {
1165 let width = smart_display::padded_width_of!(self.date(), " ", self.time(), " +00");
1166 Metadata::new(width, self, ())
1167 }
1168
1169 #[inline]
1170 fn fmt_with_metadata(
1171 &self,
1172 f: &mut fmt::Formatter<'_>,
1173 metadata: Metadata<Self>,
1174 ) -> fmt::Result {
1175 f.pad_with_width(
1176 metadata.unpadded_width(),
1177 format_args!("{} {} +00", self.date(), self.time()),
1178 )
1179 }
1180}
1181
1182impl fmt::Display for UtcDateTime {
1183 #[inline]
1184 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
1185 SmartDisplay::fmt(self, f)
1186 }
1187}
1188
1189impl fmt::Debug for UtcDateTime {
1190 #[inline]
1191 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
1192 fmt::Display::fmt(self, f)
1193 }
1194}
1195
1196impl Add<Duration> for UtcDateTime {
1197 type Output = Self;
1198
1199 /// # Panics
1200 ///
1201 /// This may panic if an overflow occurs.
1202 #[inline]
1203 #[track_caller]
1204 fn add(self, duration: Duration) -> Self::Output {
1205 self.inner.add(duration).as_utc()
1206 }
1207}
1208
1209impl Add<StdDuration> for UtcDateTime {
1210 type Output = Self;
1211
1212 /// # Panics
1213 ///
1214 /// This may panic if an overflow occurs.
1215 #[inline]
1216 #[track_caller]
1217 fn add(self, duration: StdDuration) -> Self::Output {
1218 self.inner.add(duration).as_utc()
1219 }
1220}
1221
1222impl AddAssign<Duration> for UtcDateTime {
1223 /// # Panics
1224 ///
1225 /// This may panic if an overflow occurs.
1226 #[inline]
1227 #[track_caller]
1228 fn add_assign(&mut self, rhs: Duration) {
1229 self.inner.add_assign(rhs);
1230 }
1231}
1232
1233impl AddAssign<StdDuration> for UtcDateTime {
1234 /// # Panics
1235 ///
1236 /// This may panic if an overflow occurs.
1237 #[inline]
1238 #[track_caller]
1239 fn add_assign(&mut self, rhs: StdDuration) {
1240 self.inner.add_assign(rhs);
1241 }
1242}
1243
1244impl Sub<Duration> for UtcDateTime {
1245 type Output = Self;
1246
1247 /// # Panics
1248 ///
1249 /// This may panic if an overflow occurs.
1250 #[inline]
1251 #[track_caller]
1252 fn sub(self, rhs: Duration) -> Self::Output {
1253 self.checked_sub(rhs)
1254 .expect("resulting value is out of range")
1255 }
1256}
1257
1258impl Sub<StdDuration> for UtcDateTime {
1259 type Output = Self;
1260
1261 /// # Panics
1262 ///
1263 /// This may panic if an overflow occurs.
1264 #[inline]
1265 #[track_caller]
1266 fn sub(self, duration: StdDuration) -> Self::Output {
1267 Self::from_primitive(self.inner.sub(duration))
1268 }
1269}
1270
1271impl SubAssign<Duration> for UtcDateTime {
1272 /// # Panics
1273 ///
1274 /// This may panic if an overflow occurs.
1275 #[inline]
1276 #[track_caller]
1277 fn sub_assign(&mut self, rhs: Duration) {
1278 self.inner.sub_assign(rhs);
1279 }
1280}
1281
1282impl SubAssign<StdDuration> for UtcDateTime {
1283 /// # Panics
1284 ///
1285 /// This may panic if an overflow occurs.
1286 #[inline]
1287 #[track_caller]
1288 fn sub_assign(&mut self, rhs: StdDuration) {
1289 self.inner.sub_assign(rhs);
1290 }
1291}
1292
1293impl Sub for UtcDateTime {
1294 type Output = Duration;
1295
1296 /// # Panics
1297 ///
1298 /// This may panic if an overflow occurs.
1299 #[inline]
1300 #[track_caller]
1301 fn sub(self, rhs: Self) -> Self::Output {
1302 self.inner.sub(rhs.inner)
1303 }
1304}