time/
primitive_date_time.rs

1//! The [`PrimitiveDateTime`] struct and its 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 powerfmt::ext::FormatterExt as _;
12use powerfmt::smart_display::{self, FormatterOptions, Metadata, SmartDisplay};
13
14#[cfg(feature = "formatting")]
15use crate::formatting::Formattable;
16use crate::internal_macros::{const_try, const_try_opt};
17#[cfg(feature = "parsing")]
18use crate::parsing::Parsable;
19use crate::{error, util, Date, Duration, Month, OffsetDateTime, Time, UtcOffset, Weekday};
20
21/// Combined date and time.
22#[derive(Clone, Copy, PartialEq, Eq, Hash, PartialOrd, Ord)]
23pub struct PrimitiveDateTime {
24    date: Date,
25    time: Time,
26}
27
28impl PrimitiveDateTime {
29    /// The smallest value that can be represented by `PrimitiveDateTime`.
30    ///
31    /// Depending on `large-dates` feature flag, value of this constant may vary.
32    ///
33    /// 1. With `large-dates` disabled it is equal to `-9999-01-01 00:00:00.0`
34    /// 2. With `large-dates` enabled it is equal to `-999999-01-01 00:00:00.0`
35    ///
36    /// ```rust
37    /// # use time::PrimitiveDateTime;
38    /// # use time_macros::datetime;
39    #[cfg_attr(
40        feature = "large-dates",
41        doc = "// Assuming `large-dates` feature is enabled."
42    )]
43    #[cfg_attr(
44        feature = "large-dates",
45        doc = "assert_eq!(PrimitiveDateTime::MIN, datetime!(-999999-01-01 0:00));"
46    )]
47    #[cfg_attr(
48        not(feature = "large-dates"),
49        doc = "// Assuming `large-dates` feature is disabled."
50    )]
51    #[cfg_attr(
52        not(feature = "large-dates"),
53        doc = "assert_eq!(PrimitiveDateTime::MIN, datetime!(-9999-01-01 0:00));"
54    )]
55    /// ```
56    pub const MIN: Self = Self {
57        date: Date::MIN,
58        time: Time::MIDNIGHT,
59    };
60
61    /// The largest value that can be represented by `PrimitiveDateTime`.
62    ///
63    /// Depending on `large-dates` feature flag, value of this constant may vary.
64    ///
65    /// 1. With `large-dates` disabled it is equal to `9999-12-31 23:59:59.999_999_999`
66    /// 2. With `large-dates` enabled it is equal to `999999-12-31 23:59:59.999_999_999`
67    ///
68    /// ```rust
69    /// # use time::PrimitiveDateTime;
70    /// # use time_macros::datetime;
71    #[cfg_attr(
72        feature = "large-dates",
73        doc = "// Assuming `large-dates` feature is enabled."
74    )]
75    #[cfg_attr(
76        feature = "large-dates",
77        doc = "assert_eq!(PrimitiveDateTime::MAX, datetime!(+999999-12-31 23:59:59.999_999_999));"
78    )]
79    #[cfg_attr(
80        not(feature = "large-dates"),
81        doc = "// Assuming `large-dates` feature is disabled."
82    )]
83    #[cfg_attr(
84        not(feature = "large-dates"),
85        doc = "assert_eq!(PrimitiveDateTime::MAX, datetime!(+9999-12-31 23:59:59.999_999_999));"
86    )]
87    /// ```
88    pub const MAX: Self = Self {
89        date: Date::MAX,
90        time: Time::MAX,
91    };
92
93    /// Create a new `PrimitiveDateTime` from the provided [`Date`] and [`Time`].
94    ///
95    /// ```rust
96    /// # use time::PrimitiveDateTime;
97    /// # use time_macros::{date, datetime, time};
98    /// assert_eq!(
99    ///     PrimitiveDateTime::new(date!(2019-01-01), time!(0:00)),
100    ///     datetime!(2019-01-01 0:00),
101    /// );
102    /// ```
103    pub const fn new(date: Date, time: Time) -> Self {
104        Self { date, time }
105    }
106
107    // region: component getters
108    /// Get the [`Date`] component of the `PrimitiveDateTime`.
109    ///
110    /// ```rust
111    /// # use time_macros::{date, datetime};
112    /// assert_eq!(datetime!(2019-01-01 0:00).date(), date!(2019-01-01));
113    /// ```
114    pub const fn date(self) -> Date {
115        self.date
116    }
117
118    /// Get the [`Time`] component of the `PrimitiveDateTime`.
119    ///
120    /// ```rust
121    /// # use time_macros::{datetime, time};
122    /// assert_eq!(datetime!(2019-01-01 0:00).time(), time!(0:00));
123    /// ```
124    pub const fn time(self) -> Time {
125        self.time
126    }
127    // endregion component getters
128
129    // region: date getters
130    /// Get the year of the date.
131    ///
132    /// ```rust
133    /// # use time_macros::datetime;
134    /// assert_eq!(datetime!(2019-01-01 0:00).year(), 2019);
135    /// assert_eq!(datetime!(2019-12-31 0:00).year(), 2019);
136    /// assert_eq!(datetime!(2020-01-01 0:00).year(), 2020);
137    /// ```
138    pub const fn year(self) -> i32 {
139        self.date().year()
140    }
141
142    /// Get the month of the date.
143    ///
144    /// ```rust
145    /// # use time::Month;
146    /// # use time_macros::datetime;
147    /// assert_eq!(datetime!(2019-01-01 0:00).month(), Month::January);
148    /// assert_eq!(datetime!(2019-12-31 0:00).month(), Month::December);
149    /// ```
150    pub const fn month(self) -> Month {
151        self.date().month()
152    }
153
154    /// Get the day of the date.
155    ///
156    /// The returned value will always be in the range `1..=31`.
157    ///
158    /// ```rust
159    /// # use time_macros::datetime;
160    /// assert_eq!(datetime!(2019-01-01 0:00).day(), 1);
161    /// assert_eq!(datetime!(2019-12-31 0:00).day(), 31);
162    /// ```
163    pub const fn day(self) -> u8 {
164        self.date().day()
165    }
166
167    /// Get the day of the year.
168    ///
169    /// The returned value will always be in the range `1..=366` (`1..=365` for common years).
170    ///
171    /// ```rust
172    /// # use time_macros::datetime;
173    /// assert_eq!(datetime!(2019-01-01 0:00).ordinal(), 1);
174    /// assert_eq!(datetime!(2019-12-31 0:00).ordinal(), 365);
175    /// ```
176    pub const fn ordinal(self) -> u16 {
177        self.date().ordinal()
178    }
179
180    /// Get the ISO week number.
181    ///
182    /// The returned value will always be in the range `1..=53`.
183    ///
184    /// ```rust
185    /// # use time_macros::datetime;
186    /// assert_eq!(datetime!(2019-01-01 0:00).iso_week(), 1);
187    /// assert_eq!(datetime!(2019-10-04 0:00).iso_week(), 40);
188    /// assert_eq!(datetime!(2020-01-01 0:00).iso_week(), 1);
189    /// assert_eq!(datetime!(2020-12-31 0:00).iso_week(), 53);
190    /// assert_eq!(datetime!(2021-01-01 0:00).iso_week(), 53);
191    /// ```
192    pub const fn iso_week(self) -> u8 {
193        self.date().iso_week()
194    }
195
196    /// Get the week number where week 1 begins on the first Sunday.
197    ///
198    /// The returned value will always be in the range `0..=53`.
199    ///
200    /// ```rust
201    /// # use time_macros::datetime;
202    /// assert_eq!(datetime!(2019-01-01 0:00).sunday_based_week(), 0);
203    /// assert_eq!(datetime!(2020-01-01 0:00).sunday_based_week(), 0);
204    /// assert_eq!(datetime!(2020-12-31 0:00).sunday_based_week(), 52);
205    /// assert_eq!(datetime!(2021-01-01 0:00).sunday_based_week(), 0);
206    /// ```
207    pub const fn sunday_based_week(self) -> u8 {
208        self.date().sunday_based_week()
209    }
210
211    /// Get the week number where week 1 begins on the first Monday.
212    ///
213    /// The returned value will always be in the range `0..=53`.
214    ///
215    /// ```rust
216    /// # use time_macros::datetime;
217    /// assert_eq!(datetime!(2019-01-01 0:00).monday_based_week(), 0);
218    /// assert_eq!(datetime!(2020-01-01 0:00).monday_based_week(), 0);
219    /// assert_eq!(datetime!(2020-12-31 0:00).monday_based_week(), 52);
220    /// assert_eq!(datetime!(2021-01-01 0:00).monday_based_week(), 0);
221    /// ```
222    pub const fn monday_based_week(self) -> u8 {
223        self.date().monday_based_week()
224    }
225
226    /// Get the year, month, and day.
227    ///
228    /// ```rust
229    /// # use time::Month;
230    /// # use time_macros::datetime;
231    /// assert_eq!(
232    ///     datetime!(2019-01-01 0:00).to_calendar_date(),
233    ///     (2019, Month::January, 1)
234    /// );
235    /// ```
236    pub const fn to_calendar_date(self) -> (i32, Month, u8) {
237        self.date().to_calendar_date()
238    }
239
240    /// Get the year and ordinal day number.
241    ///
242    /// ```rust
243    /// # use time_macros::datetime;
244    /// assert_eq!(datetime!(2019-01-01 0:00).to_ordinal_date(), (2019, 1));
245    /// ```
246    pub const fn to_ordinal_date(self) -> (i32, u16) {
247        self.date().to_ordinal_date()
248    }
249
250    /// Get the ISO 8601 year, week number, and weekday.
251    ///
252    /// ```rust
253    /// # use time::Weekday::*;
254    /// # use time_macros::datetime;
255    /// assert_eq!(
256    ///     datetime!(2019-01-01 0:00).to_iso_week_date(),
257    ///     (2019, 1, Tuesday)
258    /// );
259    /// assert_eq!(
260    ///     datetime!(2019-10-04 0:00).to_iso_week_date(),
261    ///     (2019, 40, Friday)
262    /// );
263    /// assert_eq!(
264    ///     datetime!(2020-01-01 0:00).to_iso_week_date(),
265    ///     (2020, 1, Wednesday)
266    /// );
267    /// assert_eq!(
268    ///     datetime!(2020-12-31 0:00).to_iso_week_date(),
269    ///     (2020, 53, Thursday)
270    /// );
271    /// assert_eq!(
272    ///     datetime!(2021-01-01 0:00).to_iso_week_date(),
273    ///     (2020, 53, Friday)
274    /// );
275    /// ```
276    pub const fn to_iso_week_date(self) -> (i32, u8, Weekday) {
277        self.date().to_iso_week_date()
278    }
279
280    /// Get the weekday.
281    ///
282    /// ```rust
283    /// # use time::Weekday::*;
284    /// # use time_macros::datetime;
285    /// assert_eq!(datetime!(2019-01-01 0:00).weekday(), Tuesday);
286    /// assert_eq!(datetime!(2019-02-01 0:00).weekday(), Friday);
287    /// assert_eq!(datetime!(2019-03-01 0:00).weekday(), Friday);
288    /// assert_eq!(datetime!(2019-04-01 0:00).weekday(), Monday);
289    /// assert_eq!(datetime!(2019-05-01 0:00).weekday(), Wednesday);
290    /// assert_eq!(datetime!(2019-06-01 0:00).weekday(), Saturday);
291    /// assert_eq!(datetime!(2019-07-01 0:00).weekday(), Monday);
292    /// assert_eq!(datetime!(2019-08-01 0:00).weekday(), Thursday);
293    /// assert_eq!(datetime!(2019-09-01 0:00).weekday(), Sunday);
294    /// assert_eq!(datetime!(2019-10-01 0:00).weekday(), Tuesday);
295    /// assert_eq!(datetime!(2019-11-01 0:00).weekday(), Friday);
296    /// assert_eq!(datetime!(2019-12-01 0:00).weekday(), Sunday);
297    /// ```
298    pub const fn weekday(self) -> Weekday {
299        self.date().weekday()
300    }
301
302    /// Get the Julian day for the date. The time is not taken into account for this calculation.
303    ///
304    /// The algorithm to perform this conversion is derived from one provided by Peter Baum; it is
305    /// freely available [here](https://www.researchgate.net/publication/316558298_Date_Algorithms).
306    ///
307    /// ```rust
308    /// # use time_macros::datetime;
309    /// assert_eq!(datetime!(-4713-11-24 0:00).to_julian_day(), 0);
310    /// assert_eq!(datetime!(2000-01-01 0:00).to_julian_day(), 2_451_545);
311    /// assert_eq!(datetime!(2019-01-01 0:00).to_julian_day(), 2_458_485);
312    /// assert_eq!(datetime!(2019-12-31 0:00).to_julian_day(), 2_458_849);
313    /// ```
314    pub const fn to_julian_day(self) -> i32 {
315        self.date().to_julian_day()
316    }
317    // endregion date getters
318
319    // region: time getters
320    /// Get the clock hour, minute, and second.
321    ///
322    /// ```rust
323    /// # use time_macros::datetime;
324    /// assert_eq!(datetime!(2020-01-01 0:00:00).as_hms(), (0, 0, 0));
325    /// assert_eq!(datetime!(2020-01-01 23:59:59).as_hms(), (23, 59, 59));
326    /// ```
327    pub const fn as_hms(self) -> (u8, u8, u8) {
328        self.time().as_hms()
329    }
330
331    /// Get the clock hour, minute, second, and millisecond.
332    ///
333    /// ```rust
334    /// # use time_macros::datetime;
335    /// assert_eq!(datetime!(2020-01-01 0:00:00).as_hms_milli(), (0, 0, 0, 0));
336    /// assert_eq!(
337    ///     datetime!(2020-01-01 23:59:59.999).as_hms_milli(),
338    ///     (23, 59, 59, 999)
339    /// );
340    /// ```
341    pub const fn as_hms_milli(self) -> (u8, u8, u8, u16) {
342        self.time().as_hms_milli()
343    }
344
345    /// Get the clock hour, minute, second, and microsecond.
346    ///
347    /// ```rust
348    /// # use time_macros::datetime;
349    /// assert_eq!(datetime!(2020-01-01 0:00:00).as_hms_micro(), (0, 0, 0, 0));
350    /// assert_eq!(
351    ///     datetime!(2020-01-01 23:59:59.999_999).as_hms_micro(),
352    ///     (23, 59, 59, 999_999)
353    /// );
354    /// ```
355    pub const fn as_hms_micro(self) -> (u8, u8, u8, u32) {
356        self.time().as_hms_micro()
357    }
358
359    /// Get the clock hour, minute, second, and nanosecond.
360    ///
361    /// ```rust
362    /// # use time_macros::datetime;
363    /// assert_eq!(datetime!(2020-01-01 0:00:00).as_hms_nano(), (0, 0, 0, 0));
364    /// assert_eq!(
365    ///     datetime!(2020-01-01 23:59:59.999_999_999).as_hms_nano(),
366    ///     (23, 59, 59, 999_999_999)
367    /// );
368    /// ```
369    pub const fn as_hms_nano(self) -> (u8, u8, u8, u32) {
370        self.time().as_hms_nano()
371    }
372
373    /// Get the clock hour.
374    ///
375    /// The returned value will always be in the range `0..24`.
376    ///
377    /// ```rust
378    /// # use time_macros::datetime;
379    /// assert_eq!(datetime!(2019-01-01 0:00).hour(), 0);
380    /// assert_eq!(datetime!(2019-01-01 23:59:59).hour(), 23);
381    /// ```
382    pub const fn hour(self) -> u8 {
383        self.time().hour()
384    }
385
386    /// Get the minute within the hour.
387    ///
388    /// The returned value will always be in the range `0..60`.
389    ///
390    /// ```rust
391    /// # use time_macros::datetime;
392    /// assert_eq!(datetime!(2019-01-01 0:00).minute(), 0);
393    /// assert_eq!(datetime!(2019-01-01 23:59:59).minute(), 59);
394    /// ```
395    pub const fn minute(self) -> u8 {
396        self.time().minute()
397    }
398
399    /// Get the second within the minute.
400    ///
401    /// The returned value will always be in the range `0..60`.
402    ///
403    /// ```rust
404    /// # use time_macros::datetime;
405    /// assert_eq!(datetime!(2019-01-01 0:00).second(), 0);
406    /// assert_eq!(datetime!(2019-01-01 23:59:59).second(), 59);
407    /// ```
408    pub const fn second(self) -> u8 {
409        self.time().second()
410    }
411
412    /// Get the milliseconds within the second.
413    ///
414    /// The returned value will always be in the range `0..1_000`.
415    ///
416    /// ```rust
417    /// # use time_macros::datetime;
418    /// assert_eq!(datetime!(2019-01-01 0:00).millisecond(), 0);
419    /// assert_eq!(datetime!(2019-01-01 23:59:59.999).millisecond(), 999);
420    /// ```
421    pub const fn millisecond(self) -> u16 {
422        self.time().millisecond()
423    }
424
425    /// Get the microseconds within the second.
426    ///
427    /// The returned value will always be in the range `0..1_000_000`.
428    ///
429    /// ```rust
430    /// # use time_macros::datetime;
431    /// assert_eq!(datetime!(2019-01-01 0:00).microsecond(), 0);
432    /// assert_eq!(
433    ///     datetime!(2019-01-01 23:59:59.999_999).microsecond(),
434    ///     999_999
435    /// );
436    /// ```
437    pub const fn microsecond(self) -> u32 {
438        self.time().microsecond()
439    }
440
441    /// Get the nanoseconds within the second.
442    ///
443    /// The returned value will always be in the range `0..1_000_000_000`.
444    ///
445    /// ```rust
446    /// # use time_macros::datetime;
447    /// assert_eq!(datetime!(2019-01-01 0:00).nanosecond(), 0);
448    /// assert_eq!(
449    ///     datetime!(2019-01-01 23:59:59.999_999_999).nanosecond(),
450    ///     999_999_999,
451    /// );
452    /// ```
453    pub const fn nanosecond(self) -> u32 {
454        self.time().nanosecond()
455    }
456    // endregion time getters
457
458    // region: attach offset
459    /// Assuming that the existing `PrimitiveDateTime` represents a moment in the provided
460    /// [`UtcOffset`], return an [`OffsetDateTime`].
461    ///
462    /// ```rust
463    /// # use time_macros::{datetime, offset};
464    /// assert_eq!(
465    ///     datetime!(2019-01-01 0:00)
466    ///         .assume_offset(offset!(UTC))
467    ///         .unix_timestamp(),
468    ///     1_546_300_800,
469    /// );
470    /// assert_eq!(
471    ///     datetime!(2019-01-01 0:00)
472    ///         .assume_offset(offset!(-1))
473    ///         .unix_timestamp(),
474    ///     1_546_304_400,
475    /// );
476    /// ```
477    pub const fn assume_offset(self, offset: UtcOffset) -> OffsetDateTime {
478        OffsetDateTime::new_in_offset(self.date, self.time, offset)
479    }
480
481    /// Assuming that the existing `PrimitiveDateTime` represents a moment in UTC, return an
482    /// [`OffsetDateTime`].
483    ///
484    /// ```rust
485    /// # use time_macros::datetime;
486    /// assert_eq!(
487    ///     datetime!(2019-01-01 0:00).assume_utc().unix_timestamp(),
488    ///     1_546_300_800,
489    /// );
490    /// ```
491    pub const fn assume_utc(self) -> OffsetDateTime {
492        self.assume_offset(UtcOffset::UTC)
493    }
494    // endregion attach offset
495
496    // region: checked arithmetic
497    /// Computes `self + duration`, returning `None` if an overflow occurred.
498    ///
499    /// ```
500    /// # use time::{Date, ext::NumericalDuration};
501    /// # use time_macros::datetime;
502    /// let datetime = Date::MIN.midnight();
503    /// assert_eq!(datetime.checked_add((-2).days()), None);
504    ///
505    /// let datetime = Date::MAX.midnight();
506    /// assert_eq!(datetime.checked_add(1.days()), None);
507    ///
508    /// assert_eq!(
509    ///     datetime!(2019-11-25 15:30).checked_add(27.hours()),
510    ///     Some(datetime!(2019-11-26 18:30))
511    /// );
512    /// ```
513    pub const fn checked_add(self, duration: Duration) -> Option<Self> {
514        let (date_adjustment, time) = self.time.adjusting_add(duration);
515        let date = const_try_opt!(self.date.checked_add(duration));
516
517        Some(Self {
518            date: match date_adjustment {
519                util::DateAdjustment::Previous => const_try_opt!(date.previous_day()),
520                util::DateAdjustment::Next => const_try_opt!(date.next_day()),
521                util::DateAdjustment::None => date,
522            },
523            time,
524        })
525    }
526
527    /// Computes `self - duration`, returning `None` if an overflow occurred.
528    ///
529    /// ```
530    /// # use time::{Date, ext::NumericalDuration};
531    /// # use time_macros::datetime;
532    /// let datetime = Date::MIN.midnight();
533    /// assert_eq!(datetime.checked_sub(2.days()), None);
534    ///
535    /// let datetime = Date::MAX.midnight();
536    /// assert_eq!(datetime.checked_sub((-1).days()), None);
537    ///
538    /// assert_eq!(
539    ///     datetime!(2019-11-25 15:30).checked_sub(27.hours()),
540    ///     Some(datetime!(2019-11-24 12:30))
541    /// );
542    /// ```
543    pub const fn checked_sub(self, duration: Duration) -> Option<Self> {
544        let (date_adjustment, time) = self.time.adjusting_sub(duration);
545        let date = const_try_opt!(self.date.checked_sub(duration));
546
547        Some(Self {
548            date: match date_adjustment {
549                util::DateAdjustment::Previous => const_try_opt!(date.previous_day()),
550                util::DateAdjustment::Next => const_try_opt!(date.next_day()),
551                util::DateAdjustment::None => date,
552            },
553            time,
554        })
555    }
556    // endregion: checked arithmetic
557
558    // region: saturating arithmetic
559    /// Computes `self + duration`, saturating value on overflow.
560    ///
561    /// ```
562    /// # use time::{PrimitiveDateTime, ext::NumericalDuration};
563    /// # use time_macros::datetime;
564    /// assert_eq!(
565    ///     PrimitiveDateTime::MIN.saturating_add((-2).days()),
566    ///     PrimitiveDateTime::MIN
567    /// );
568    ///
569    /// assert_eq!(
570    ///     PrimitiveDateTime::MAX.saturating_add(2.days()),
571    ///     PrimitiveDateTime::MAX
572    /// );
573    ///
574    /// assert_eq!(
575    ///     datetime!(2019-11-25 15:30).saturating_add(27.hours()),
576    ///     datetime!(2019-11-26 18:30)
577    /// );
578    /// ```
579    pub const fn saturating_add(self, duration: Duration) -> Self {
580        if let Some(datetime) = self.checked_add(duration) {
581            datetime
582        } else if duration.is_negative() {
583            Self::MIN
584        } else {
585            Self::MAX
586        }
587    }
588
589    /// Computes `self - duration`, saturating value on overflow.
590    ///
591    /// ```
592    /// # use time::{PrimitiveDateTime, ext::NumericalDuration};
593    /// # use time_macros::datetime;
594    /// assert_eq!(
595    ///     PrimitiveDateTime::MIN.saturating_sub(2.days()),
596    ///     PrimitiveDateTime::MIN
597    /// );
598    ///
599    /// assert_eq!(
600    ///     PrimitiveDateTime::MAX.saturating_sub((-2).days()),
601    ///     PrimitiveDateTime::MAX
602    /// );
603    ///
604    /// assert_eq!(
605    ///     datetime!(2019-11-25 15:30).saturating_sub(27.hours()),
606    ///     datetime!(2019-11-24 12:30)
607    /// );
608    /// ```
609    pub const fn saturating_sub(self, duration: Duration) -> Self {
610        if let Some(datetime) = self.checked_sub(duration) {
611            datetime
612        } else if duration.is_negative() {
613            Self::MAX
614        } else {
615            Self::MIN
616        }
617    }
618    // endregion: saturating arithmetic
619}
620
621// region: replacement
622/// Methods that replace part of the `PrimitiveDateTime`.
623impl PrimitiveDateTime {
624    /// Replace the time, preserving the date.
625    ///
626    /// ```rust
627    /// # use time_macros::{datetime, time};
628    /// assert_eq!(
629    ///     datetime!(2020-01-01 17:00).replace_time(time!(5:00)),
630    ///     datetime!(2020-01-01 5:00)
631    /// );
632    /// ```
633    #[must_use = "This method does not mutate the original `PrimitiveDateTime`."]
634    pub const fn replace_time(self, time: Time) -> Self {
635        Self {
636            date: self.date,
637            time,
638        }
639    }
640
641    /// Replace the date, preserving the time.
642    ///
643    /// ```rust
644    /// # use time_macros::{datetime, date};
645    /// assert_eq!(
646    ///     datetime!(2020-01-01 12:00).replace_date(date!(2020-01-30)),
647    ///     datetime!(2020-01-30 12:00)
648    /// );
649    /// ```
650    #[must_use = "This method does not mutate the original `PrimitiveDateTime`."]
651    pub const fn replace_date(self, date: Date) -> Self {
652        Self {
653            date,
654            time: self.time,
655        }
656    }
657
658    /// Replace the year. The month and day will be unchanged.
659    ///
660    /// ```rust
661    /// # use time_macros::datetime;
662    /// assert_eq!(
663    ///     datetime!(2022-02-18 12:00).replace_year(2019),
664    ///     Ok(datetime!(2019-02-18 12:00))
665    /// );
666    /// assert!(datetime!(2022-02-18 12:00).replace_year(-1_000_000_000).is_err()); // -1_000_000_000 isn't a valid year
667    /// assert!(datetime!(2022-02-18 12:00).replace_year(1_000_000_000).is_err()); // 1_000_000_000 isn't a valid year
668    /// ```
669    #[must_use = "This method does not mutate the original `PrimitiveDateTime`."]
670    pub const fn replace_year(self, year: i32) -> Result<Self, error::ComponentRange> {
671        Ok(Self {
672            date: const_try!(self.date.replace_year(year)),
673            time: self.time,
674        })
675    }
676
677    /// Replace the month of the year.
678    ///
679    /// ```rust
680    /// # use time_macros::datetime;
681    /// # use time::Month;
682    /// assert_eq!(
683    ///     datetime!(2022-02-18 12:00).replace_month(Month::January),
684    ///     Ok(datetime!(2022-01-18 12:00))
685    /// );
686    /// assert!(datetime!(2022-01-30 12:00).replace_month(Month::February).is_err()); // 30 isn't a valid day in February
687    /// ```
688    #[must_use = "This method does not mutate the original `PrimitiveDateTime`."]
689    pub const fn replace_month(self, month: Month) -> Result<Self, error::ComponentRange> {
690        Ok(Self {
691            date: const_try!(self.date.replace_month(month)),
692            time: self.time,
693        })
694    }
695
696    /// Replace the day of the month.
697    ///
698    /// ```rust
699    /// # use time_macros::datetime;
700    /// assert_eq!(
701    ///     datetime!(2022-02-18 12:00).replace_day(1),
702    ///     Ok(datetime!(2022-02-01 12:00))
703    /// );
704    /// assert!(datetime!(2022-02-18 12:00).replace_day(0).is_err()); // 00 isn't a valid day
705    /// assert!(datetime!(2022-02-18 12:00).replace_day(30).is_err()); // 30 isn't a valid day in February
706    /// ```
707    #[must_use = "This method does not mutate the original `PrimitiveDateTime`."]
708    pub const fn replace_day(self, day: u8) -> Result<Self, error::ComponentRange> {
709        Ok(Self {
710            date: const_try!(self.date.replace_day(day)),
711            time: self.time,
712        })
713    }
714
715    /// Replace the day of the year.
716    ///
717    /// ```rust
718    /// # use time_macros::datetime;
719    /// assert_eq!(datetime!(2022-049 12:00).replace_ordinal(1), Ok(datetime!(2022-001 12:00)));
720    /// assert!(datetime!(2022-049 12:00).replace_ordinal(0).is_err()); // 0 isn't a valid ordinal
721    /// assert!(datetime!(2022-049 12:00).replace_ordinal(366).is_err()); // 2022 isn't a leap year
722    /// ````
723    #[must_use = "This method does not mutate the original `PrimitiveDateTime`."]
724    pub const fn replace_ordinal(self, ordinal: u16) -> Result<Self, error::ComponentRange> {
725        Ok(Self {
726            date: const_try!(self.date.replace_ordinal(ordinal)),
727            time: self.time,
728        })
729    }
730
731    /// Replace the clock hour.
732    ///
733    /// ```rust
734    /// # use time_macros::datetime;
735    /// assert_eq!(
736    ///     datetime!(2022-02-18 01:02:03.004_005_006).replace_hour(7),
737    ///     Ok(datetime!(2022-02-18 07:02:03.004_005_006))
738    /// );
739    /// assert!(datetime!(2022-02-18 01:02:03.004_005_006).replace_hour(24).is_err()); // 24 isn't a valid hour
740    /// ```
741    #[must_use = "This method does not mutate the original `PrimitiveDateTime`."]
742    pub const fn replace_hour(self, hour: u8) -> Result<Self, error::ComponentRange> {
743        Ok(Self {
744            date: self.date,
745            time: const_try!(self.time.replace_hour(hour)),
746        })
747    }
748
749    /// Replace the minutes within the hour.
750    ///
751    /// ```rust
752    /// # use time_macros::datetime;
753    /// assert_eq!(
754    ///     datetime!(2022-02-18 01:02:03.004_005_006).replace_minute(7),
755    ///     Ok(datetime!(2022-02-18 01:07:03.004_005_006))
756    /// );
757    /// assert!(datetime!(2022-02-18 01:02:03.004_005_006).replace_minute(60).is_err()); // 60 isn't a valid minute
758    /// ```
759    #[must_use = "This method does not mutate the original `PrimitiveDateTime`."]
760    pub const fn replace_minute(self, minute: u8) -> Result<Self, error::ComponentRange> {
761        Ok(Self {
762            date: self.date,
763            time: const_try!(self.time.replace_minute(minute)),
764        })
765    }
766
767    /// Replace the seconds within the minute.
768    ///
769    /// ```rust
770    /// # use time_macros::datetime;
771    /// assert_eq!(
772    ///     datetime!(2022-02-18 01:02:03.004_005_006).replace_second(7),
773    ///     Ok(datetime!(2022-02-18 01:02:07.004_005_006))
774    /// );
775    /// assert!(datetime!(2022-02-18 01:02:03.004_005_006).replace_second(60).is_err()); // 60 isn't a valid second
776    /// ```
777    #[must_use = "This method does not mutate the original `PrimitiveDateTime`."]
778    pub const fn replace_second(self, second: u8) -> Result<Self, error::ComponentRange> {
779        Ok(Self {
780            date: self.date,
781            time: const_try!(self.time.replace_second(second)),
782        })
783    }
784
785    /// Replace the milliseconds within the second.
786    ///
787    /// ```rust
788    /// # use time_macros::datetime;
789    /// assert_eq!(
790    ///     datetime!(2022-02-18 01:02:03.004_005_006).replace_millisecond(7),
791    ///     Ok(datetime!(2022-02-18 01:02:03.007))
792    /// );
793    /// assert!(datetime!(2022-02-18 01:02:03.004_005_006).replace_millisecond(1_000).is_err()); // 1_000 isn't a valid millisecond
794    /// ```
795    #[must_use = "This method does not mutate the original `PrimitiveDateTime`."]
796    pub const fn replace_millisecond(
797        self,
798        millisecond: u16,
799    ) -> Result<Self, error::ComponentRange> {
800        Ok(Self {
801            date: self.date,
802            time: const_try!(self.time.replace_millisecond(millisecond)),
803        })
804    }
805
806    /// Replace the microseconds within the second.
807    ///
808    /// ```rust
809    /// # use time_macros::datetime;
810    /// assert_eq!(
811    ///     datetime!(2022-02-18 01:02:03.004_005_006).replace_microsecond(7_008),
812    ///     Ok(datetime!(2022-02-18 01:02:03.007_008))
813    /// );
814    /// assert!(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
815    /// ```
816    #[must_use = "This method does not mutate the original `PrimitiveDateTime`."]
817    pub const fn replace_microsecond(
818        self,
819        microsecond: u32,
820    ) -> Result<Self, error::ComponentRange> {
821        Ok(Self {
822            date: self.date,
823            time: const_try!(self.time.replace_microsecond(microsecond)),
824        })
825    }
826
827    /// Replace the nanoseconds within the second.
828    ///
829    /// ```rust
830    /// # use time_macros::datetime;
831    /// assert_eq!(
832    ///     datetime!(2022-02-18 01:02:03.004_005_006).replace_nanosecond(7_008_009),
833    ///     Ok(datetime!(2022-02-18 01:02:03.007_008_009))
834    /// );
835    /// assert!(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
836    /// ```
837    #[must_use = "This method does not mutate the original `PrimitiveDateTime`."]
838    pub const fn replace_nanosecond(self, nanosecond: u32) -> Result<Self, error::ComponentRange> {
839        Ok(Self {
840            date: self.date,
841            time: const_try!(self.time.replace_nanosecond(nanosecond)),
842        })
843    }
844}
845// endregion replacement
846
847// region: formatting & parsing
848#[cfg(feature = "formatting")]
849impl PrimitiveDateTime {
850    /// Format the `PrimitiveDateTime` using the provided [format
851    /// description](crate::format_description).
852    pub fn format_into(
853        self,
854        output: &mut impl io::Write,
855        format: &(impl Formattable + ?Sized),
856    ) -> Result<usize, error::Format> {
857        format.format_into(output, Some(self.date), Some(self.time), None)
858    }
859
860    /// Format the `PrimitiveDateTime` using the provided [format
861    /// description](crate::format_description).
862    ///
863    /// ```rust
864    /// # use time::format_description;
865    /// # use time_macros::datetime;
866    /// let format = format_description::parse("[year]-[month]-[day] [hour]:[minute]:[second]")?;
867    /// assert_eq!(
868    ///     datetime!(2020-01-02 03:04:05).format(&format)?,
869    ///     "2020-01-02 03:04:05"
870    /// );
871    /// # Ok::<_, time::Error>(())
872    /// ```
873    pub fn format(self, format: &(impl Formattable + ?Sized)) -> Result<String, error::Format> {
874        format.format(Some(self.date), Some(self.time), None)
875    }
876}
877
878#[cfg(feature = "parsing")]
879impl PrimitiveDateTime {
880    /// Parse a `PrimitiveDateTime` from the input using the provided [format
881    /// description](crate::format_description).
882    ///
883    /// ```rust
884    /// # use time::PrimitiveDateTime;
885    /// # use time_macros::{datetime, format_description};
886    /// let format = format_description!("[year]-[month]-[day] [hour]:[minute]:[second]");
887    /// assert_eq!(
888    ///     PrimitiveDateTime::parse("2020-01-02 03:04:05", &format)?,
889    ///     datetime!(2020-01-02 03:04:05)
890    /// );
891    /// # Ok::<_, time::Error>(())
892    /// ```
893    pub fn parse(
894        input: &str,
895        description: &(impl Parsable + ?Sized),
896    ) -> Result<Self, error::Parse> {
897        description.parse_primitive_date_time(input.as_bytes())
898    }
899}
900
901impl SmartDisplay for PrimitiveDateTime {
902    type Metadata = ();
903
904    fn metadata(&self, _: FormatterOptions) -> Metadata<Self> {
905        let width = smart_display::padded_width_of!(self.date, " ", self.time);
906        Metadata::new(width, self, ())
907    }
908
909    fn fmt_with_metadata(
910        &self,
911        f: &mut fmt::Formatter<'_>,
912        metadata: Metadata<Self>,
913    ) -> fmt::Result {
914        f.pad_with_width(
915            metadata.unpadded_width(),
916            format_args!("{} {}", self.date, self.time),
917        )
918    }
919}
920
921impl fmt::Display for PrimitiveDateTime {
922    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
923        SmartDisplay::fmt(self, f)
924    }
925}
926
927impl fmt::Debug for PrimitiveDateTime {
928    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
929        fmt::Display::fmt(self, f)
930    }
931}
932// endregion formatting & parsing
933
934// region: trait impls
935impl Add<Duration> for PrimitiveDateTime {
936    type Output = Self;
937
938    /// # Panics
939    ///
940    /// This may panic if an overflow occurs.
941    fn add(self, duration: Duration) -> Self::Output {
942        self.checked_add(duration)
943            .expect("resulting value is out of range")
944    }
945}
946
947impl Add<StdDuration> for PrimitiveDateTime {
948    type Output = Self;
949
950    /// # Panics
951    ///
952    /// This may panic if an overflow occurs.
953    fn add(self, duration: StdDuration) -> Self::Output {
954        let (is_next_day, time) = self.time.adjusting_add_std(duration);
955
956        Self {
957            date: if is_next_day {
958                (self.date + duration)
959                    .next_day()
960                    .expect("resulting value is out of range")
961            } else {
962                self.date + duration
963            },
964            time,
965        }
966    }
967}
968
969impl AddAssign<Duration> for PrimitiveDateTime {
970    /// # Panics
971    ///
972    /// This may panic if an overflow occurs.
973    fn add_assign(&mut self, duration: Duration) {
974        *self = *self + duration;
975    }
976}
977
978impl AddAssign<StdDuration> for PrimitiveDateTime {
979    /// # Panics
980    ///
981    /// This may panic if an overflow occurs.
982    fn add_assign(&mut self, duration: StdDuration) {
983        *self = *self + duration;
984    }
985}
986
987impl Sub<Duration> for PrimitiveDateTime {
988    type Output = Self;
989
990    /// # Panics
991    ///
992    /// This may panic if an overflow occurs.
993    fn sub(self, duration: Duration) -> Self::Output {
994        self.checked_sub(duration)
995            .expect("resulting value is out of range")
996    }
997}
998
999impl Sub<StdDuration> for PrimitiveDateTime {
1000    type Output = Self;
1001
1002    /// # Panics
1003    ///
1004    /// This may panic if an overflow occurs.
1005    fn sub(self, duration: StdDuration) -> Self::Output {
1006        let (is_previous_day, time) = self.time.adjusting_sub_std(duration);
1007
1008        Self {
1009            date: if is_previous_day {
1010                (self.date - duration)
1011                    .previous_day()
1012                    .expect("resulting value is out of range")
1013            } else {
1014                self.date - duration
1015            },
1016            time,
1017        }
1018    }
1019}
1020
1021impl SubAssign<Duration> for PrimitiveDateTime {
1022    /// # Panics
1023    ///
1024    /// This may panic if an overflow occurs.
1025    fn sub_assign(&mut self, duration: Duration) {
1026        *self = *self - duration;
1027    }
1028}
1029
1030impl SubAssign<StdDuration> for PrimitiveDateTime {
1031    /// # Panics
1032    ///
1033    /// This may panic if an overflow occurs.
1034    fn sub_assign(&mut self, duration: StdDuration) {
1035        *self = *self - duration;
1036    }
1037}
1038
1039impl Sub for PrimitiveDateTime {
1040    type Output = Duration;
1041
1042    /// # Panics
1043    ///
1044    /// This may panic if an overflow occurs.
1045    fn sub(self, rhs: Self) -> Self::Output {
1046        (self.date - rhs.date) + (self.time - rhs.time)
1047    }
1048}
1049// endregion trait impls