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: usize = 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 args: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(msg:"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: bool, time: 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(msg:"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(msg:"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: bool, time: 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(msg:"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
1050