1// This is a part of Chrono.
2// See README.md and LICENSE.txt for details.
3
4//! ISO 8601 date and time with time zone.
5
6#[cfg(all(feature = "alloc", not(feature = "std"), not(test)))]
7use alloc::string::String;
8use core::borrow::Borrow;
9use core::cmp::Ordering;
10use core::fmt::Write;
11use core::ops::{Add, AddAssign, Sub, SubAssign};
12use core::time::Duration;
13use core::{fmt, hash, str};
14#[cfg(feature = "std")]
15use std::time::{SystemTime, UNIX_EPOCH};
16
17#[allow(deprecated)]
18use crate::Date;
19#[cfg(all(feature = "unstable-locales", feature = "alloc"))]
20use crate::format::Locale;
21#[cfg(feature = "alloc")]
22use crate::format::{DelayedFormat, SecondsFormat, write_rfc2822, write_rfc3339};
23use crate::format::{
24 Fixed, Item, ParseError, ParseResult, Parsed, StrftimeItems, TOO_LONG, parse,
25 parse_and_remainder, parse_rfc3339,
26};
27use crate::naive::{Days, IsoWeek, NaiveDate, NaiveDateTime, NaiveTime};
28#[cfg(feature = "clock")]
29use crate::offset::Local;
30use crate::offset::{FixedOffset, LocalResult, Offset, TimeZone, Utc};
31use crate::{Datelike, Months, TimeDelta, Timelike, Weekday};
32use crate::{expect, try_opt};
33
34#[cfg(any(feature = "rkyv", feature = "rkyv-16", feature = "rkyv-32", feature = "rkyv-64"))]
35use rkyv::{Archive, Deserialize, Serialize};
36
37/// documented at re-export site
38#[cfg(feature = "serde")]
39pub(super) mod serde;
40
41#[cfg(test)]
42mod tests;
43
44/// ISO 8601 combined date and time with time zone.
45///
46/// There are some constructors implemented here (the `from_*` methods), but
47/// the general-purpose constructors are all via the methods on the
48/// [`TimeZone`](./offset/trait.TimeZone.html) implementations.
49#[derive(Clone)]
50#[cfg_attr(
51 any(feature = "rkyv", feature = "rkyv-16", feature = "rkyv-32", feature = "rkyv-64"),
52 derive(Archive, Deserialize, Serialize),
53 archive(compare(PartialEq, PartialOrd))
54)]
55#[cfg_attr(feature = "rkyv-validation", archive(check_bytes))]
56pub struct DateTime<Tz: TimeZone> {
57 datetime: NaiveDateTime,
58 offset: Tz::Offset,
59}
60
61/// The minimum possible `DateTime<Utc>`.
62#[deprecated(since = "0.4.20", note = "Use DateTime::MIN_UTC instead")]
63pub const MIN_DATETIME: DateTime<Utc> = DateTime::<Utc>::MIN_UTC;
64/// The maximum possible `DateTime<Utc>`.
65#[deprecated(since = "0.4.20", note = "Use DateTime::MAX_UTC instead")]
66pub const MAX_DATETIME: DateTime<Utc> = DateTime::<Utc>::MAX_UTC;
67
68impl<Tz: TimeZone> DateTime<Tz> {
69 /// Makes a new `DateTime` from its components: a `NaiveDateTime` in UTC and an `Offset`.
70 ///
71 /// This is a low-level method, intended for use cases such as deserializing a `DateTime` or
72 /// passing it through FFI.
73 ///
74 /// For regular use you will probably want to use a method such as
75 /// [`TimeZone::from_local_datetime`] or [`NaiveDateTime::and_local_timezone`] instead.
76 ///
77 /// # Example
78 ///
79 /// ```
80 /// # #[cfg(feature = "clock")] {
81 /// use chrono::{DateTime, Local};
82 ///
83 /// let dt = Local::now();
84 /// // Get components
85 /// let naive_utc = dt.naive_utc();
86 /// let offset = dt.offset().clone();
87 /// // Serialize, pass through FFI... and recreate the `DateTime`:
88 /// let dt_new = DateTime::<Local>::from_naive_utc_and_offset(naive_utc, offset);
89 /// assert_eq!(dt, dt_new);
90 /// # }
91 /// ```
92 #[inline]
93 #[must_use]
94 pub const fn from_naive_utc_and_offset(
95 datetime: NaiveDateTime,
96 offset: Tz::Offset,
97 ) -> DateTime<Tz> {
98 DateTime { datetime, offset }
99 }
100
101 /// Makes a new `DateTime` from its components: a `NaiveDateTime` in UTC and an `Offset`.
102 #[inline]
103 #[must_use]
104 #[deprecated(
105 since = "0.4.27",
106 note = "Use TimeZone::from_utc_datetime() or DateTime::from_naive_utc_and_offset instead"
107 )]
108 pub fn from_utc(datetime: NaiveDateTime, offset: Tz::Offset) -> DateTime<Tz> {
109 DateTime { datetime, offset }
110 }
111
112 /// Makes a new `DateTime` from a `NaiveDateTime` in *local* time and an `Offset`.
113 ///
114 /// # Panics
115 ///
116 /// Panics if the local datetime can't be converted to UTC because it would be out of range.
117 ///
118 /// This can happen if `datetime` is near the end of the representable range of `NaiveDateTime`,
119 /// and the offset from UTC pushes it beyond that.
120 #[inline]
121 #[must_use]
122 #[deprecated(
123 since = "0.4.27",
124 note = "Use TimeZone::from_local_datetime() or NaiveDateTime::and_local_timezone instead"
125 )]
126 pub fn from_local(datetime: NaiveDateTime, offset: Tz::Offset) -> DateTime<Tz> {
127 let datetime_utc = datetime - offset.fix();
128
129 DateTime { datetime: datetime_utc, offset }
130 }
131
132 /// Retrieves the date component with an associated timezone.
133 ///
134 /// Unless you are immediately planning on turning this into a `DateTime`
135 /// with the same timezone you should use the [`date_naive`](DateTime::date_naive) method.
136 ///
137 /// [`NaiveDate`] is a more well-defined type, and has more traits implemented on it,
138 /// so should be preferred to [`Date`] any time you truly want to operate on dates.
139 ///
140 /// # Panics
141 ///
142 /// [`DateTime`] internally stores the date and time in UTC with a [`NaiveDateTime`]. This
143 /// method will panic if the offset from UTC would push the local date outside of the
144 /// representable range of a [`Date`].
145 #[inline]
146 #[deprecated(since = "0.4.23", note = "Use `date_naive()` instead")]
147 #[allow(deprecated)]
148 #[must_use]
149 pub fn date(&self) -> Date<Tz> {
150 Date::from_utc(self.naive_local().date(), self.offset.clone())
151 }
152
153 /// Retrieves the date component.
154 ///
155 /// # Panics
156 ///
157 /// [`DateTime`] internally stores the date and time in UTC with a [`NaiveDateTime`]. This
158 /// method will panic if the offset from UTC would push the local date outside of the
159 /// representable range of a [`NaiveDate`].
160 ///
161 /// # Example
162 ///
163 /// ```
164 /// use chrono::prelude::*;
165 ///
166 /// let date: DateTime<Utc> = Utc.with_ymd_and_hms(2020, 1, 1, 0, 0, 0).unwrap();
167 /// let other: DateTime<FixedOffset> =
168 /// FixedOffset::east_opt(23).unwrap().with_ymd_and_hms(2020, 1, 1, 0, 0, 0).unwrap();
169 /// assert_eq!(date.date_naive(), other.date_naive());
170 /// ```
171 #[inline]
172 #[must_use]
173 pub fn date_naive(&self) -> NaiveDate {
174 self.naive_local().date()
175 }
176
177 /// Retrieves the time component.
178 #[inline]
179 #[must_use]
180 pub fn time(&self) -> NaiveTime {
181 self.datetime.time() + self.offset.fix()
182 }
183
184 /// Returns the number of non-leap seconds since January 1, 1970 0:00:00 UTC
185 /// (aka "UNIX timestamp").
186 ///
187 /// The reverse operation of creating a [`DateTime`] from a timestamp can be performed
188 /// using [`from_timestamp`](DateTime::from_timestamp) or [`TimeZone::timestamp_opt`].
189 ///
190 /// ```
191 /// use chrono::{DateTime, TimeZone, Utc};
192 ///
193 /// let dt: DateTime<Utc> = Utc.with_ymd_and_hms(2015, 5, 15, 0, 0, 0).unwrap();
194 /// assert_eq!(dt.timestamp(), 1431648000);
195 ///
196 /// assert_eq!(DateTime::from_timestamp(dt.timestamp(), dt.timestamp_subsec_nanos()).unwrap(), dt);
197 /// ```
198 #[inline]
199 #[must_use]
200 pub const fn timestamp(&self) -> i64 {
201 let gregorian_day = self.datetime.date().num_days_from_ce() as i64;
202 let seconds_from_midnight = self.datetime.time().num_seconds_from_midnight() as i64;
203 (gregorian_day - UNIX_EPOCH_DAY) * 86_400 + seconds_from_midnight
204 }
205
206 /// Returns the number of non-leap-milliseconds since January 1, 1970 UTC.
207 ///
208 /// # Example
209 ///
210 /// ```
211 /// use chrono::{NaiveDate, Utc};
212 ///
213 /// let dt = NaiveDate::from_ymd_opt(1970, 1, 1)
214 /// .unwrap()
215 /// .and_hms_milli_opt(0, 0, 1, 444)
216 /// .unwrap()
217 /// .and_local_timezone(Utc)
218 /// .unwrap();
219 /// assert_eq!(dt.timestamp_millis(), 1_444);
220 ///
221 /// let dt = NaiveDate::from_ymd_opt(2001, 9, 9)
222 /// .unwrap()
223 /// .and_hms_milli_opt(1, 46, 40, 555)
224 /// .unwrap()
225 /// .and_local_timezone(Utc)
226 /// .unwrap();
227 /// assert_eq!(dt.timestamp_millis(), 1_000_000_000_555);
228 /// ```
229 #[inline]
230 #[must_use]
231 pub const fn timestamp_millis(&self) -> i64 {
232 let as_ms = self.timestamp() * 1000;
233 as_ms + self.timestamp_subsec_millis() as i64
234 }
235
236 /// Returns the number of non-leap-microseconds since January 1, 1970 UTC.
237 ///
238 /// # Example
239 ///
240 /// ```
241 /// use chrono::{NaiveDate, Utc};
242 ///
243 /// let dt = NaiveDate::from_ymd_opt(1970, 1, 1)
244 /// .unwrap()
245 /// .and_hms_micro_opt(0, 0, 1, 444)
246 /// .unwrap()
247 /// .and_local_timezone(Utc)
248 /// .unwrap();
249 /// assert_eq!(dt.timestamp_micros(), 1_000_444);
250 ///
251 /// let dt = NaiveDate::from_ymd_opt(2001, 9, 9)
252 /// .unwrap()
253 /// .and_hms_micro_opt(1, 46, 40, 555)
254 /// .unwrap()
255 /// .and_local_timezone(Utc)
256 /// .unwrap();
257 /// assert_eq!(dt.timestamp_micros(), 1_000_000_000_000_555);
258 /// ```
259 #[inline]
260 #[must_use]
261 pub const fn timestamp_micros(&self) -> i64 {
262 let as_us = self.timestamp() * 1_000_000;
263 as_us + self.timestamp_subsec_micros() as i64
264 }
265
266 /// Returns the number of non-leap-nanoseconds since January 1, 1970 UTC.
267 ///
268 /// # Panics
269 ///
270 /// An `i64` with nanosecond precision can span a range of ~584 years. This function panics on
271 /// an out of range `DateTime`.
272 ///
273 /// The dates that can be represented as nanoseconds are between 1677-09-21T00:12:43.145224192
274 /// and 2262-04-11T23:47:16.854775807.
275 #[deprecated(since = "0.4.31", note = "use `timestamp_nanos_opt()` instead")]
276 #[inline]
277 #[must_use]
278 pub const fn timestamp_nanos(&self) -> i64 {
279 expect(
280 self.timestamp_nanos_opt(),
281 "value can not be represented in a timestamp with nanosecond precision.",
282 )
283 }
284
285 /// Returns the number of non-leap-nanoseconds since January 1, 1970 UTC.
286 ///
287 /// # Errors
288 ///
289 /// An `i64` with nanosecond precision can span a range of ~584 years. This function returns
290 /// `None` on an out of range `DateTime`.
291 ///
292 /// The dates that can be represented as nanoseconds are between 1677-09-21T00:12:43.145224192
293 /// and 2262-04-11T23:47:16.854775807.
294 ///
295 /// # Example
296 ///
297 /// ```
298 /// use chrono::{NaiveDate, Utc};
299 ///
300 /// let dt = NaiveDate::from_ymd_opt(1970, 1, 1)
301 /// .unwrap()
302 /// .and_hms_nano_opt(0, 0, 1, 444)
303 /// .unwrap()
304 /// .and_local_timezone(Utc)
305 /// .unwrap();
306 /// assert_eq!(dt.timestamp_nanos_opt(), Some(1_000_000_444));
307 ///
308 /// let dt = NaiveDate::from_ymd_opt(2001, 9, 9)
309 /// .unwrap()
310 /// .and_hms_nano_opt(1, 46, 40, 555)
311 /// .unwrap()
312 /// .and_local_timezone(Utc)
313 /// .unwrap();
314 /// assert_eq!(dt.timestamp_nanos_opt(), Some(1_000_000_000_000_000_555));
315 ///
316 /// let dt = NaiveDate::from_ymd_opt(1677, 9, 21)
317 /// .unwrap()
318 /// .and_hms_nano_opt(0, 12, 43, 145_224_192)
319 /// .unwrap()
320 /// .and_local_timezone(Utc)
321 /// .unwrap();
322 /// assert_eq!(dt.timestamp_nanos_opt(), Some(-9_223_372_036_854_775_808));
323 ///
324 /// let dt = NaiveDate::from_ymd_opt(2262, 4, 11)
325 /// .unwrap()
326 /// .and_hms_nano_opt(23, 47, 16, 854_775_807)
327 /// .unwrap()
328 /// .and_local_timezone(Utc)
329 /// .unwrap();
330 /// assert_eq!(dt.timestamp_nanos_opt(), Some(9_223_372_036_854_775_807));
331 ///
332 /// let dt = NaiveDate::from_ymd_opt(1677, 9, 21)
333 /// .unwrap()
334 /// .and_hms_nano_opt(0, 12, 43, 145_224_191)
335 /// .unwrap()
336 /// .and_local_timezone(Utc)
337 /// .unwrap();
338 /// assert_eq!(dt.timestamp_nanos_opt(), None);
339 ///
340 /// let dt = NaiveDate::from_ymd_opt(2262, 4, 11)
341 /// .unwrap()
342 /// .and_hms_nano_opt(23, 47, 16, 854_775_808)
343 /// .unwrap()
344 /// .and_local_timezone(Utc)
345 /// .unwrap();
346 /// assert_eq!(dt.timestamp_nanos_opt(), None);
347 /// ```
348 #[inline]
349 #[must_use]
350 pub const fn timestamp_nanos_opt(&self) -> Option<i64> {
351 let mut timestamp = self.timestamp();
352 let mut subsec_nanos = self.timestamp_subsec_nanos() as i64;
353 // `(timestamp * 1_000_000_000) + subsec_nanos` may create a temporary that underflows while
354 // the final value can be represented as an `i64`.
355 // As workaround we converting the negative case to:
356 // `((timestamp + 1) * 1_000_000_000) + (ns - 1_000_000_000)``
357 //
358 // Also see <https://github.com/chronotope/chrono/issues/1289>.
359 if timestamp < 0 {
360 subsec_nanos -= 1_000_000_000;
361 timestamp += 1;
362 }
363 try_opt!(timestamp.checked_mul(1_000_000_000)).checked_add(subsec_nanos)
364 }
365
366 /// Returns the number of milliseconds since the last second boundary.
367 ///
368 /// In event of a leap second this may exceed 999.
369 #[inline]
370 #[must_use]
371 pub const fn timestamp_subsec_millis(&self) -> u32 {
372 self.timestamp_subsec_nanos() / 1_000_000
373 }
374
375 /// Returns the number of microseconds since the last second boundary.
376 ///
377 /// In event of a leap second this may exceed 999,999.
378 #[inline]
379 #[must_use]
380 pub const fn timestamp_subsec_micros(&self) -> u32 {
381 self.timestamp_subsec_nanos() / 1_000
382 }
383
384 /// Returns the number of nanoseconds since the last second boundary
385 ///
386 /// In event of a leap second this may exceed 999,999,999.
387 #[inline]
388 #[must_use]
389 pub const fn timestamp_subsec_nanos(&self) -> u32 {
390 self.datetime.time().nanosecond()
391 }
392
393 /// Retrieves an associated offset from UTC.
394 #[inline]
395 #[must_use]
396 pub const fn offset(&self) -> &Tz::Offset {
397 &self.offset
398 }
399
400 /// Retrieves an associated time zone.
401 #[inline]
402 #[must_use]
403 pub fn timezone(&self) -> Tz {
404 TimeZone::from_offset(&self.offset)
405 }
406
407 /// Changes the associated time zone.
408 /// The returned `DateTime` references the same instant of time from the perspective of the
409 /// provided time zone.
410 #[inline]
411 #[must_use]
412 pub fn with_timezone<Tz2: TimeZone>(&self, tz: &Tz2) -> DateTime<Tz2> {
413 tz.from_utc_datetime(&self.datetime)
414 }
415
416 /// Fix the offset from UTC to its current value, dropping the associated timezone information.
417 /// This it useful for converting a generic `DateTime<Tz: Timezone>` to `DateTime<FixedOffset>`.
418 #[inline]
419 #[must_use]
420 pub fn fixed_offset(&self) -> DateTime<FixedOffset> {
421 self.with_timezone(&self.offset().fix())
422 }
423
424 /// Turn this `DateTime` into a `DateTime<Utc>`, dropping the offset and associated timezone
425 /// information.
426 #[inline]
427 #[must_use]
428 pub const fn to_utc(&self) -> DateTime<Utc> {
429 DateTime { datetime: self.datetime, offset: Utc }
430 }
431
432 /// Adds given `TimeDelta` to the current date and time.
433 ///
434 /// # Errors
435 ///
436 /// Returns `None` if the resulting date would be out of range.
437 #[inline]
438 #[must_use]
439 pub fn checked_add_signed(self, rhs: TimeDelta) -> Option<DateTime<Tz>> {
440 let datetime = self.datetime.checked_add_signed(rhs)?;
441 let tz = self.timezone();
442 Some(tz.from_utc_datetime(&datetime))
443 }
444
445 /// Adds given `Months` to the current date and time.
446 ///
447 /// Uses the last day of the month if the day does not exist in the resulting month.
448 ///
449 /// See [`NaiveDate::checked_add_months`] for more details on behavior.
450 ///
451 /// # Errors
452 ///
453 /// Returns `None` if:
454 /// - The local time at the resulting date does not exist or is ambiguous, for example during a
455 /// daylight saving time transition.
456 /// - The resulting UTC datetime would be out of range.
457 /// - The resulting local datetime would be out of range (unless `months` is zero).
458 #[must_use]
459 pub fn checked_add_months(self, months: Months) -> Option<DateTime<Tz>> {
460 // `NaiveDate::checked_add_months` has a fast path for `Months(0)` that does not validate
461 // the resulting date, with which we can return `Some` even for an out of range local
462 // datetime.
463 self.overflowing_naive_local()
464 .checked_add_months(months)?
465 .and_local_timezone(Tz::from_offset(&self.offset))
466 .single()
467 }
468
469 /// Subtracts given `TimeDelta` from the current date and time.
470 ///
471 /// # Errors
472 ///
473 /// Returns `None` if the resulting date would be out of range.
474 #[inline]
475 #[must_use]
476 pub fn checked_sub_signed(self, rhs: TimeDelta) -> Option<DateTime<Tz>> {
477 let datetime = self.datetime.checked_sub_signed(rhs)?;
478 let tz = self.timezone();
479 Some(tz.from_utc_datetime(&datetime))
480 }
481
482 /// Subtracts given `Months` from the current date and time.
483 ///
484 /// Uses the last day of the month if the day does not exist in the resulting month.
485 ///
486 /// See [`NaiveDate::checked_sub_months`] for more details on behavior.
487 ///
488 /// # Errors
489 ///
490 /// Returns `None` if:
491 /// - The local time at the resulting date does not exist or is ambiguous, for example during a
492 /// daylight saving time transition.
493 /// - The resulting UTC datetime would be out of range.
494 /// - The resulting local datetime would be out of range (unless `months` is zero).
495 #[must_use]
496 pub fn checked_sub_months(self, months: Months) -> Option<DateTime<Tz>> {
497 // `NaiveDate::checked_sub_months` has a fast path for `Months(0)` that does not validate
498 // the resulting date, with which we can return `Some` even for an out of range local
499 // datetime.
500 self.overflowing_naive_local()
501 .checked_sub_months(months)?
502 .and_local_timezone(Tz::from_offset(&self.offset))
503 .single()
504 }
505
506 /// Add a duration in [`Days`] to the date part of the `DateTime`.
507 ///
508 /// # Errors
509 ///
510 /// Returns `None` if:
511 /// - The local time at the resulting date does not exist or is ambiguous, for example during a
512 /// daylight saving time transition.
513 /// - The resulting UTC datetime would be out of range.
514 /// - The resulting local datetime would be out of range (unless `days` is zero).
515 #[must_use]
516 pub fn checked_add_days(self, days: Days) -> Option<Self> {
517 if days == Days::new(0) {
518 return Some(self);
519 }
520 // `NaiveDate::add_days` has a fast path if the result remains within the same year, that
521 // does not validate the resulting date. This allows us to return `Some` even for an out of
522 // range local datetime when adding `Days(0)`.
523 self.overflowing_naive_local()
524 .checked_add_days(days)
525 .and_then(|dt| self.timezone().from_local_datetime(&dt).single())
526 .filter(|dt| dt <= &DateTime::<Utc>::MAX_UTC)
527 }
528
529 /// Subtract a duration in [`Days`] from the date part of the `DateTime`.
530 ///
531 /// # Errors
532 ///
533 /// Returns `None` if:
534 /// - The local time at the resulting date does not exist or is ambiguous, for example during a
535 /// daylight saving time transition.
536 /// - The resulting UTC datetime would be out of range.
537 /// - The resulting local datetime would be out of range (unless `days` is zero).
538 #[must_use]
539 pub fn checked_sub_days(self, days: Days) -> Option<Self> {
540 // `NaiveDate::add_days` has a fast path if the result remains within the same year, that
541 // does not validate the resulting date. This allows us to return `Some` even for an out of
542 // range local datetime when adding `Days(0)`.
543 self.overflowing_naive_local()
544 .checked_sub_days(days)
545 .and_then(|dt| self.timezone().from_local_datetime(&dt).single())
546 .filter(|dt| dt >= &DateTime::<Utc>::MIN_UTC)
547 }
548
549 /// Subtracts another `DateTime` from the current date and time.
550 /// This does not overflow or underflow at all.
551 #[inline]
552 #[must_use]
553 pub fn signed_duration_since<Tz2: TimeZone>(
554 self,
555 rhs: impl Borrow<DateTime<Tz2>>,
556 ) -> TimeDelta {
557 self.datetime.signed_duration_since(rhs.borrow().datetime)
558 }
559
560 /// Returns a view to the naive UTC datetime.
561 #[inline]
562 #[must_use]
563 pub const fn naive_utc(&self) -> NaiveDateTime {
564 self.datetime
565 }
566
567 /// Returns a view to the naive local datetime.
568 ///
569 /// # Panics
570 ///
571 /// [`DateTime`] internally stores the date and time in UTC with a [`NaiveDateTime`]. This
572 /// method will panic if the offset from UTC would push the local datetime outside of the
573 /// representable range of a [`NaiveDateTime`].
574 #[inline]
575 #[must_use]
576 pub fn naive_local(&self) -> NaiveDateTime {
577 self.datetime
578 .checked_add_offset(self.offset.fix())
579 .expect("Local time out of range for `NaiveDateTime`")
580 }
581
582 /// Returns the naive local datetime.
583 ///
584 /// This makes use of the buffer space outside of the representable range of values of
585 /// `NaiveDateTime`. The result can be used as intermediate value, but should never be exposed
586 /// outside chrono.
587 #[inline]
588 #[must_use]
589 pub(crate) fn overflowing_naive_local(&self) -> NaiveDateTime {
590 self.datetime.overflowing_add_offset(self.offset.fix())
591 }
592
593 /// Retrieve the elapsed years from now to the given [`DateTime`].
594 ///
595 /// # Errors
596 ///
597 /// Returns `None` if `base > self`.
598 #[must_use]
599 pub fn years_since(&self, base: Self) -> Option<u32> {
600 let mut years = self.year() - base.year();
601 let earlier_time =
602 (self.month(), self.day(), self.time()) < (base.month(), base.day(), base.time());
603
604 years -= match earlier_time {
605 true => 1,
606 false => 0,
607 };
608
609 match years >= 0 {
610 true => Some(years as u32),
611 false => None,
612 }
613 }
614
615 /// Returns an RFC 2822 date and time string such as `Tue, 1 Jul 2003 10:52:37 +0200`.
616 ///
617 /// # Panics
618 ///
619 /// Panics if the date can not be represented in this format: the year may not be negative and
620 /// can not have more than 4 digits.
621 #[cfg(feature = "alloc")]
622 #[must_use]
623 pub fn to_rfc2822(&self) -> String {
624 let mut result = String::with_capacity(32);
625 write_rfc2822(&mut result, self.overflowing_naive_local(), self.offset.fix())
626 .expect("writing rfc2822 datetime to string should never fail");
627 result
628 }
629
630 /// Returns an RFC 3339 and ISO 8601 date and time string such as `1996-12-19T16:39:57-08:00`.
631 #[cfg(feature = "alloc")]
632 #[must_use]
633 pub fn to_rfc3339(&self) -> String {
634 // For some reason a string with a capacity less than 32 is ca 20% slower when benchmarking.
635 let mut result = String::with_capacity(32);
636 let naive = self.overflowing_naive_local();
637 let offset = self.offset.fix();
638 write_rfc3339(&mut result, naive, offset, SecondsFormat::AutoSi, false)
639 .expect("writing rfc3339 datetime to string should never fail");
640 result
641 }
642
643 /// Return an RFC 3339 and ISO 8601 date and time string with subseconds
644 /// formatted as per `SecondsFormat`.
645 ///
646 /// If `use_z` is true and the timezone is UTC (offset 0), uses `Z` as
647 /// per [`Fixed::TimezoneOffsetColonZ`]. If `use_z` is false, uses
648 /// [`Fixed::TimezoneOffsetColon`]
649 ///
650 /// # Examples
651 ///
652 /// ```rust
653 /// # use chrono::{FixedOffset, SecondsFormat, TimeZone, NaiveDate};
654 /// let dt = NaiveDate::from_ymd_opt(2018, 1, 26)
655 /// .unwrap()
656 /// .and_hms_micro_opt(18, 30, 9, 453_829)
657 /// .unwrap()
658 /// .and_utc();
659 /// assert_eq!(dt.to_rfc3339_opts(SecondsFormat::Millis, false), "2018-01-26T18:30:09.453+00:00");
660 /// assert_eq!(dt.to_rfc3339_opts(SecondsFormat::Millis, true), "2018-01-26T18:30:09.453Z");
661 /// assert_eq!(dt.to_rfc3339_opts(SecondsFormat::Secs, true), "2018-01-26T18:30:09Z");
662 ///
663 /// let pst = FixedOffset::east_opt(8 * 60 * 60).unwrap();
664 /// let dt = pst
665 /// .from_local_datetime(
666 /// &NaiveDate::from_ymd_opt(2018, 1, 26)
667 /// .unwrap()
668 /// .and_hms_micro_opt(10, 30, 9, 453_829)
669 /// .unwrap(),
670 /// )
671 /// .unwrap();
672 /// assert_eq!(dt.to_rfc3339_opts(SecondsFormat::Secs, true), "2018-01-26T10:30:09+08:00");
673 /// ```
674 #[cfg(feature = "alloc")]
675 #[must_use]
676 pub fn to_rfc3339_opts(&self, secform: SecondsFormat, use_z: bool) -> String {
677 let mut result = String::with_capacity(38);
678 write_rfc3339(&mut result, self.naive_local(), self.offset.fix(), secform, use_z)
679 .expect("writing rfc3339 datetime to string should never fail");
680 result
681 }
682
683 /// Set the time to a new fixed time on the existing date.
684 ///
685 /// # Errors
686 ///
687 /// Returns `LocalResult::None` if the datetime is at the edge of the representable range for a
688 /// `DateTime`, and `with_time` would push the value in UTC out of range.
689 ///
690 /// # Example
691 ///
692 /// ```
693 /// # #[cfg(feature = "clock")] {
694 /// use chrono::{Local, NaiveTime};
695 ///
696 /// let noon = NaiveTime::from_hms_opt(12, 0, 0).unwrap();
697 /// let today_noon = Local::now().with_time(noon);
698 /// let today_midnight = Local::now().with_time(NaiveTime::MIN);
699 ///
700 /// assert_eq!(today_noon.single().unwrap().time(), noon);
701 /// assert_eq!(today_midnight.single().unwrap().time(), NaiveTime::MIN);
702 /// # }
703 /// ```
704 #[must_use]
705 pub fn with_time(&self, time: NaiveTime) -> LocalResult<Self> {
706 self.timezone().from_local_datetime(&self.overflowing_naive_local().date().and_time(time))
707 }
708
709 /// The minimum possible `DateTime<Utc>`.
710 pub const MIN_UTC: DateTime<Utc> = DateTime { datetime: NaiveDateTime::MIN, offset: Utc };
711 /// The maximum possible `DateTime<Utc>`.
712 pub const MAX_UTC: DateTime<Utc> = DateTime { datetime: NaiveDateTime::MAX, offset: Utc };
713}
714
715impl DateTime<Utc> {
716 /// Makes a new `DateTime<Utc>` from the number of non-leap seconds
717 /// since January 1, 1970 0:00:00 UTC (aka "UNIX timestamp")
718 /// and the number of nanoseconds since the last whole non-leap second.
719 ///
720 /// This is guaranteed to round-trip with regard to [`timestamp`](DateTime::timestamp) and
721 /// [`timestamp_subsec_nanos`](DateTime::timestamp_subsec_nanos).
722 ///
723 /// If you need to create a `DateTime` with a [`TimeZone`] different from [`Utc`], use
724 /// [`TimeZone::timestamp_opt`] or [`DateTime::with_timezone`].
725 ///
726 /// The nanosecond part can exceed 1,000,000,000 in order to represent a
727 /// [leap second](NaiveTime#leap-second-handling), but only when `secs % 60 == 59`.
728 /// (The true "UNIX timestamp" cannot represent a leap second unambiguously.)
729 ///
730 /// # Errors
731 ///
732 /// Returns `None` on out-of-range number of seconds and/or
733 /// invalid nanosecond, otherwise returns `Some(DateTime {...})`.
734 ///
735 /// # Example
736 ///
737 /// ```
738 /// use chrono::DateTime;
739 ///
740 /// let dt = DateTime::from_timestamp(1431648000, 0).expect("invalid timestamp");
741 ///
742 /// assert_eq!(dt.to_string(), "2015-05-15 00:00:00 UTC");
743 /// assert_eq!(DateTime::from_timestamp(dt.timestamp(), dt.timestamp_subsec_nanos()).unwrap(), dt);
744 /// ```
745 #[inline]
746 #[must_use]
747 pub const fn from_timestamp(secs: i64, nsecs: u32) -> Option<Self> {
748 let days = secs.div_euclid(86_400) + UNIX_EPOCH_DAY;
749 let secs = secs.rem_euclid(86_400);
750 if days < i32::MIN as i64 || days > i32::MAX as i64 {
751 return None;
752 }
753 let date = try_opt!(NaiveDate::from_num_days_from_ce_opt(days as i32));
754 let time = try_opt!(NaiveTime::from_num_seconds_from_midnight_opt(secs as u32, nsecs));
755 Some(date.and_time(time).and_utc())
756 }
757
758 /// Makes a new `DateTime<Utc>` from the number of non-leap milliseconds
759 /// since January 1, 1970 0:00:00.000 UTC (aka "UNIX timestamp").
760 ///
761 /// This is guaranteed to round-trip with [`timestamp_millis`](DateTime::timestamp_millis).
762 ///
763 /// If you need to create a `DateTime` with a [`TimeZone`] different from [`Utc`], use
764 /// [`TimeZone::timestamp_millis_opt`] or [`DateTime::with_timezone`].
765 ///
766 /// # Errors
767 ///
768 /// Returns `None` on out-of-range number of milliseconds, otherwise returns `Some(DateTime {...})`.
769 ///
770 /// # Example
771 ///
772 /// ```
773 /// use chrono::DateTime;
774 ///
775 /// let dt = DateTime::from_timestamp_millis(947638923004).expect("invalid timestamp");
776 ///
777 /// assert_eq!(dt.to_string(), "2000-01-12 01:02:03.004 UTC");
778 /// assert_eq!(DateTime::from_timestamp_millis(dt.timestamp_millis()).unwrap(), dt);
779 /// ```
780 #[inline]
781 #[must_use]
782 pub const fn from_timestamp_millis(millis: i64) -> Option<Self> {
783 let secs = millis.div_euclid(1000);
784 let nsecs = millis.rem_euclid(1000) as u32 * 1_000_000;
785 Self::from_timestamp(secs, nsecs)
786 }
787
788 /// Creates a new `DateTime<Utc>` from the number of non-leap microseconds
789 /// since January 1, 1970 0:00:00.000 UTC (aka "UNIX timestamp").
790 ///
791 /// This is guaranteed to round-trip with [`timestamp_micros`](DateTime::timestamp_micros).
792 ///
793 /// If you need to create a `DateTime` with a [`TimeZone`] different from [`Utc`], use
794 /// [`TimeZone::timestamp_micros`] or [`DateTime::with_timezone`].
795 ///
796 /// # Errors
797 ///
798 /// Returns `None` if the number of microseconds would be out of range for a `NaiveDateTime`
799 /// (more than ca. 262,000 years away from common era)
800 ///
801 /// # Example
802 ///
803 /// ```
804 /// use chrono::DateTime;
805 ///
806 /// let timestamp_micros: i64 = 1662921288000000; // Sun, 11 Sep 2022 18:34:48 UTC
807 /// let dt = DateTime::from_timestamp_micros(timestamp_micros);
808 /// assert!(dt.is_some());
809 /// assert_eq!(timestamp_micros, dt.expect("invalid timestamp").timestamp_micros());
810 ///
811 /// // Negative timestamps (before the UNIX epoch) are supported as well.
812 /// let timestamp_micros: i64 = -2208936075000000; // Mon, 1 Jan 1900 14:38:45 UTC
813 /// let dt = DateTime::from_timestamp_micros(timestamp_micros);
814 /// assert!(dt.is_some());
815 /// assert_eq!(timestamp_micros, dt.expect("invalid timestamp").timestamp_micros());
816 /// ```
817 #[inline]
818 #[must_use]
819 pub const fn from_timestamp_micros(micros: i64) -> Option<Self> {
820 let secs = micros.div_euclid(1_000_000);
821 let nsecs = micros.rem_euclid(1_000_000) as u32 * 1000;
822 Self::from_timestamp(secs, nsecs)
823 }
824
825 /// Creates a new [`DateTime<Utc>`] from the number of non-leap nanoseconds
826 /// since January 1, 1970 0:00:00.000 UTC (aka "UNIX timestamp").
827 ///
828 /// This is guaranteed to round-trip with [`timestamp_nanos`](DateTime::timestamp_nanos).
829 ///
830 /// If you need to create a `DateTime` with a [`TimeZone`] different from [`Utc`], use
831 /// [`TimeZone::timestamp_nanos`] or [`DateTime::with_timezone`].
832 ///
833 /// The UNIX epoch starts on midnight, January 1, 1970, UTC.
834 ///
835 /// An `i64` with nanosecond precision can span a range of ~584 years. Because all values can
836 /// be represented as a `DateTime` this method never fails.
837 ///
838 /// # Example
839 ///
840 /// ```
841 /// use chrono::DateTime;
842 ///
843 /// let timestamp_nanos: i64 = 1662921288_000_000_000; // Sun, 11 Sep 2022 18:34:48 UTC
844 /// let dt = DateTime::from_timestamp_nanos(timestamp_nanos);
845 /// assert_eq!(timestamp_nanos, dt.timestamp_nanos_opt().unwrap());
846 ///
847 /// // Negative timestamps (before the UNIX epoch) are supported as well.
848 /// let timestamp_nanos: i64 = -2208936075_000_000_000; // Mon, 1 Jan 1900 14:38:45 UTC
849 /// let dt = DateTime::from_timestamp_nanos(timestamp_nanos);
850 /// assert_eq!(timestamp_nanos, dt.timestamp_nanos_opt().unwrap());
851 /// ```
852 #[inline]
853 #[must_use]
854 pub const fn from_timestamp_nanos(nanos: i64) -> Self {
855 let secs = nanos.div_euclid(1_000_000_000);
856 let nsecs = nanos.rem_euclid(1_000_000_000) as u32;
857 expect(Self::from_timestamp(secs, nsecs), "timestamp in nanos is always in range")
858 }
859
860 /// The Unix Epoch, 1970-01-01 00:00:00 UTC.
861 pub const UNIX_EPOCH: Self = Self { datetime: NaiveDateTime::UNIX_EPOCH, offset: Utc };
862}
863
864impl Default for DateTime<Utc> {
865 fn default() -> Self {
866 Utc.from_utc_datetime(&NaiveDateTime::default())
867 }
868}
869
870#[cfg(feature = "clock")]
871impl Default for DateTime<Local> {
872 fn default() -> Self {
873 Local.from_utc_datetime(&NaiveDateTime::default())
874 }
875}
876
877impl Default for DateTime<FixedOffset> {
878 fn default() -> Self {
879 FixedOffset::west_opt(0).unwrap().from_utc_datetime(&NaiveDateTime::default())
880 }
881}
882
883/// Convert a `DateTime<Utc>` instance into a `DateTime<FixedOffset>` instance.
884impl From<DateTime<Utc>> for DateTime<FixedOffset> {
885 /// Convert this `DateTime<Utc>` instance into a `DateTime<FixedOffset>` instance.
886 ///
887 /// Conversion is done via [`DateTime::with_timezone`]. Note that the converted value returned by
888 /// this will be created with a fixed timezone offset of 0.
889 fn from(src: DateTime<Utc>) -> Self {
890 src.with_timezone(&FixedOffset::east_opt(secs:0).unwrap())
891 }
892}
893
894/// Convert a `DateTime<Utc>` instance into a `DateTime<Local>` instance.
895#[cfg(feature = "clock")]
896impl From<DateTime<Utc>> for DateTime<Local> {
897 /// Convert this `DateTime<Utc>` instance into a `DateTime<Local>` instance.
898 ///
899 /// Conversion is performed via [`DateTime::with_timezone`], accounting for the difference in timezones.
900 fn from(src: DateTime<Utc>) -> Self {
901 src.with_timezone(&Local)
902 }
903}
904
905/// Convert a `DateTime<FixedOffset>` instance into a `DateTime<Utc>` instance.
906impl From<DateTime<FixedOffset>> for DateTime<Utc> {
907 /// Convert this `DateTime<FixedOffset>` instance into a `DateTime<Utc>` instance.
908 ///
909 /// Conversion is performed via [`DateTime::with_timezone`], accounting for the timezone
910 /// difference.
911 fn from(src: DateTime<FixedOffset>) -> Self {
912 src.with_timezone(&Utc)
913 }
914}
915
916/// Convert a `DateTime<FixedOffset>` instance into a `DateTime<Local>` instance.
917#[cfg(feature = "clock")]
918impl From<DateTime<FixedOffset>> for DateTime<Local> {
919 /// Convert this `DateTime<FixedOffset>` instance into a `DateTime<Local>` instance.
920 ///
921 /// Conversion is performed via [`DateTime::with_timezone`]. Returns the equivalent value in local
922 /// time.
923 fn from(src: DateTime<FixedOffset>) -> Self {
924 src.with_timezone(&Local)
925 }
926}
927
928/// Convert a `DateTime<Local>` instance into a `DateTime<Utc>` instance.
929#[cfg(feature = "clock")]
930impl From<DateTime<Local>> for DateTime<Utc> {
931 /// Convert this `DateTime<Local>` instance into a `DateTime<Utc>` instance.
932 ///
933 /// Conversion is performed via [`DateTime::with_timezone`], accounting for the difference in
934 /// timezones.
935 fn from(src: DateTime<Local>) -> Self {
936 src.with_timezone(&Utc)
937 }
938}
939
940/// Convert a `DateTime<Local>` instance into a `DateTime<FixedOffset>` instance.
941#[cfg(feature = "clock")]
942impl From<DateTime<Local>> for DateTime<FixedOffset> {
943 /// Convert this `DateTime<Local>` instance into a `DateTime<FixedOffset>` instance.
944 ///
945 /// Conversion is performed via [`DateTime::with_timezone`].
946 fn from(src: DateTime<Local>) -> Self {
947 src.with_timezone(&src.offset().fix())
948 }
949}
950
951/// Maps the local datetime to other datetime with given conversion function.
952fn map_local<Tz: TimeZone, F>(dt: &DateTime<Tz>, mut f: F) -> Option<DateTime<Tz>>
953where
954 F: FnMut(NaiveDateTime) -> Option<NaiveDateTime>,
955{
956 fOption>(dt.overflowing_naive_local())
957 .and_then(|datetime: NaiveDateTime| dt.timezone().from_local_datetime(&datetime).single())
958 .filter(|dt: &DateTime| dt >= &DateTime::<Utc>::MIN_UTC && dt <= &DateTime::<Utc>::MAX_UTC)
959}
960
961impl DateTime<FixedOffset> {
962 /// Parses an RFC 2822 date-and-time string into a `DateTime<FixedOffset>` value.
963 ///
964 /// This parses valid RFC 2822 datetime strings (such as `Tue, 1 Jul 2003 10:52:37 +0200`)
965 /// and returns a new [`DateTime`] instance with the parsed timezone as the [`FixedOffset`].
966 ///
967 /// RFC 2822 is the internet message standard that specifies the representation of times in HTTP
968 /// and email headers. It is the 2001 revision of RFC 822, and is itself revised as RFC 5322 in
969 /// 2008.
970 ///
971 /// # Support for the obsolete date format
972 ///
973 /// - A 2-digit year is interpreted to be a year in 1950-2049.
974 /// - The standard allows comments and whitespace between many of the tokens. See [4.3] and
975 /// [Appendix A.5]
976 /// - Single letter 'military' time zone names are parsed as a `-0000` offset.
977 /// They were defined with the wrong sign in RFC 822 and corrected in RFC 2822. But because
978 /// the meaning is now ambiguous, the standard says they should be be considered as `-0000`
979 /// unless there is out-of-band information confirming their meaning.
980 /// The exception is `Z`, which remains identical to `+0000`.
981 ///
982 /// [4.3]: https://www.rfc-editor.org/rfc/rfc2822#section-4.3
983 /// [Appendix A.5]: https://www.rfc-editor.org/rfc/rfc2822#appendix-A.5
984 ///
985 /// # Example
986 ///
987 /// ```
988 /// # use chrono::{DateTime, FixedOffset, TimeZone};
989 /// assert_eq!(
990 /// DateTime::parse_from_rfc2822("Wed, 18 Feb 2015 23:16:09 GMT").unwrap(),
991 /// FixedOffset::east_opt(0).unwrap().with_ymd_and_hms(2015, 2, 18, 23, 16, 9).unwrap()
992 /// );
993 /// ```
994 pub fn parse_from_rfc2822(s: &str) -> ParseResult<DateTime<FixedOffset>> {
995 const ITEMS: &[Item<'static>] = &[Item::Fixed(Fixed::RFC2822)];
996 let mut parsed = Parsed::new();
997 parse(&mut parsed, s, ITEMS.iter())?;
998 parsed.to_datetime()
999 }
1000
1001 /// Parses an RFC 3339 date-and-time string into a `DateTime<FixedOffset>` value.
1002 ///
1003 /// Parses all valid RFC 3339 values (as well as the subset of valid ISO 8601 values that are
1004 /// also valid RFC 3339 date-and-time values) and returns a new [`DateTime`] with a
1005 /// [`FixedOffset`] corresponding to the parsed timezone. While RFC 3339 values come in a wide
1006 /// variety of shapes and sizes, `1996-12-19T16:39:57-08:00` is an example of the most commonly
1007 /// encountered variety of RFC 3339 formats.
1008 ///
1009 /// Why isn't this named `parse_from_iso8601`? That's because ISO 8601 allows representing
1010 /// values in a wide range of formats, only some of which represent actual date-and-time
1011 /// instances (rather than periods, ranges, dates, or times). Some valid ISO 8601 values are
1012 /// also simultaneously valid RFC 3339 values, but not all RFC 3339 values are valid ISO 8601
1013 /// values (or the other way around).
1014 pub fn parse_from_rfc3339(s: &str) -> ParseResult<DateTime<FixedOffset>> {
1015 let mut parsed = Parsed::new();
1016 let (s, _) = parse_rfc3339(&mut parsed, s)?;
1017 if !s.is_empty() {
1018 return Err(TOO_LONG);
1019 }
1020 parsed.to_datetime()
1021 }
1022
1023 /// Parses a string from a user-specified format into a `DateTime<FixedOffset>` value.
1024 ///
1025 /// Note that this method *requires a timezone* in the input string. See
1026 /// [`NaiveDateTime::parse_from_str`](./naive/struct.NaiveDateTime.html#method.parse_from_str)
1027 /// for a version that does not require a timezone in the to-be-parsed str. The returned
1028 /// [`DateTime`] value will have a [`FixedOffset`] reflecting the parsed timezone.
1029 ///
1030 /// See the [`format::strftime` module](crate::format::strftime) for supported format
1031 /// sequences.
1032 ///
1033 /// # Example
1034 ///
1035 /// ```rust
1036 /// use chrono::{DateTime, FixedOffset, NaiveDate, TimeZone};
1037 ///
1038 /// let dt = DateTime::parse_from_str("1983 Apr 13 12:09:14.274 +0000", "%Y %b %d %H:%M:%S%.3f %z");
1039 /// assert_eq!(
1040 /// dt,
1041 /// Ok(FixedOffset::east_opt(0)
1042 /// .unwrap()
1043 /// .from_local_datetime(
1044 /// &NaiveDate::from_ymd_opt(1983, 4, 13)
1045 /// .unwrap()
1046 /// .and_hms_milli_opt(12, 9, 14, 274)
1047 /// .unwrap()
1048 /// )
1049 /// .unwrap())
1050 /// );
1051 /// ```
1052 pub fn parse_from_str(s: &str, fmt: &str) -> ParseResult<DateTime<FixedOffset>> {
1053 let mut parsed = Parsed::new();
1054 parse(&mut parsed, s, StrftimeItems::new(fmt))?;
1055 parsed.to_datetime()
1056 }
1057
1058 /// Parses a string from a user-specified format into a `DateTime<FixedOffset>` value, and a
1059 /// slice with the remaining portion of the string.
1060 ///
1061 /// Note that this method *requires a timezone* in the input string. See
1062 /// [`NaiveDateTime::parse_and_remainder`] for a version that does not
1063 /// require a timezone in `s`. The returned [`DateTime`] value will have a [`FixedOffset`]
1064 /// reflecting the parsed timezone.
1065 ///
1066 /// See the [`format::strftime` module](./format/strftime/index.html) for supported format
1067 /// sequences.
1068 ///
1069 /// Similar to [`parse_from_str`](#method.parse_from_str).
1070 ///
1071 /// # Example
1072 ///
1073 /// ```rust
1074 /// # use chrono::{DateTime, FixedOffset, TimeZone};
1075 /// let (datetime, remainder) = DateTime::parse_and_remainder(
1076 /// "2015-02-18 23:16:09 +0200 trailing text",
1077 /// "%Y-%m-%d %H:%M:%S %z",
1078 /// )
1079 /// .unwrap();
1080 /// assert_eq!(
1081 /// datetime,
1082 /// FixedOffset::east_opt(2 * 3600).unwrap().with_ymd_and_hms(2015, 2, 18, 23, 16, 9).unwrap()
1083 /// );
1084 /// assert_eq!(remainder, " trailing text");
1085 /// ```
1086 pub fn parse_and_remainder<'a>(
1087 s: &'a str,
1088 fmt: &str,
1089 ) -> ParseResult<(DateTime<FixedOffset>, &'a str)> {
1090 let mut parsed = Parsed::new();
1091 let remainder = parse_and_remainder(&mut parsed, s, StrftimeItems::new(fmt))?;
1092 parsed.to_datetime().map(|d| (d, remainder))
1093 }
1094}
1095
1096impl<Tz: TimeZone> DateTime<Tz>
1097where
1098 Tz::Offset: fmt::Display,
1099{
1100 /// Formats the combined date and time with the specified formatting items.
1101 #[cfg(feature = "alloc")]
1102 #[inline]
1103 #[must_use]
1104 pub fn format_with_items<'a, I, B>(&self, items: I) -> DelayedFormat<I>
1105 where
1106 I: Iterator<Item = B> + Clone,
1107 B: Borrow<Item<'a>>,
1108 {
1109 let local = self.overflowing_naive_local();
1110 DelayedFormat::new_with_offset(Some(local.date()), Some(local.time()), &self.offset, items)
1111 }
1112
1113 /// Formats the combined date and time per the specified format string.
1114 ///
1115 /// See the [`crate::format::strftime`] module for the supported escape sequences.
1116 ///
1117 /// # Example
1118 /// ```rust
1119 /// use chrono::prelude::*;
1120 ///
1121 /// let date_time: DateTime<Utc> = Utc.with_ymd_and_hms(2017, 04, 02, 12, 50, 32).unwrap();
1122 /// let formatted = format!("{}", date_time.format("%d/%m/%Y %H:%M"));
1123 /// assert_eq!(formatted, "02/04/2017 12:50");
1124 /// ```
1125 #[cfg(feature = "alloc")]
1126 #[inline]
1127 #[must_use]
1128 pub fn format<'a>(&self, fmt: &'a str) -> DelayedFormat<StrftimeItems<'a>> {
1129 self.format_with_items(StrftimeItems::new(fmt))
1130 }
1131
1132 /// Formats the combined date and time with the specified formatting items and locale.
1133 #[cfg(all(feature = "unstable-locales", feature = "alloc"))]
1134 #[inline]
1135 #[must_use]
1136 pub fn format_localized_with_items<'a, I, B>(
1137 &self,
1138 items: I,
1139 locale: Locale,
1140 ) -> DelayedFormat<I>
1141 where
1142 I: Iterator<Item = B> + Clone,
1143 B: Borrow<Item<'a>>,
1144 {
1145 let local = self.overflowing_naive_local();
1146 DelayedFormat::new_with_offset_and_locale(
1147 Some(local.date()),
1148 Some(local.time()),
1149 &self.offset,
1150 items,
1151 locale,
1152 )
1153 }
1154
1155 /// Formats the combined date and time per the specified format string and
1156 /// locale.
1157 ///
1158 /// See the [`crate::format::strftime`] module on the supported escape
1159 /// sequences.
1160 #[cfg(all(feature = "unstable-locales", feature = "alloc"))]
1161 #[inline]
1162 #[must_use]
1163 pub fn format_localized<'a>(
1164 &self,
1165 fmt: &'a str,
1166 locale: Locale,
1167 ) -> DelayedFormat<StrftimeItems<'a>> {
1168 self.format_localized_with_items(StrftimeItems::new_with_locale(fmt, locale), locale)
1169 }
1170}
1171
1172impl<Tz: TimeZone> Datelike for DateTime<Tz> {
1173 #[inline]
1174 fn year(&self) -> i32 {
1175 self.overflowing_naive_local().year()
1176 }
1177 #[inline]
1178 fn month(&self) -> u32 {
1179 self.overflowing_naive_local().month()
1180 }
1181 #[inline]
1182 fn month0(&self) -> u32 {
1183 self.overflowing_naive_local().month0()
1184 }
1185 #[inline]
1186 fn day(&self) -> u32 {
1187 self.overflowing_naive_local().day()
1188 }
1189 #[inline]
1190 fn day0(&self) -> u32 {
1191 self.overflowing_naive_local().day0()
1192 }
1193 #[inline]
1194 fn ordinal(&self) -> u32 {
1195 self.overflowing_naive_local().ordinal()
1196 }
1197 #[inline]
1198 fn ordinal0(&self) -> u32 {
1199 self.overflowing_naive_local().ordinal0()
1200 }
1201 #[inline]
1202 fn weekday(&self) -> Weekday {
1203 self.overflowing_naive_local().weekday()
1204 }
1205 #[inline]
1206 fn iso_week(&self) -> IsoWeek {
1207 self.overflowing_naive_local().iso_week()
1208 }
1209
1210 #[inline]
1211 /// Makes a new `DateTime` with the year number changed, while keeping the same month and day.
1212 ///
1213 /// See also the [`NaiveDate::with_year`] method.
1214 ///
1215 /// # Errors
1216 ///
1217 /// Returns `None` if:
1218 /// - The resulting date does not exist (February 29 in a non-leap year).
1219 /// - The local time at the resulting date does not exist or is ambiguous, for example during a
1220 /// daylight saving time transition.
1221 /// - The resulting UTC datetime would be out of range.
1222 /// - The resulting local datetime would be out of range (unless the year remains the same).
1223 fn with_year(&self, year: i32) -> Option<DateTime<Tz>> {
1224 map_local(self, |dt| match dt.year() == year {
1225 true => Some(dt),
1226 false => dt.with_year(year),
1227 })
1228 }
1229
1230 /// Makes a new `DateTime` with the month number (starting from 1) changed.
1231 ///
1232 /// Don't combine multiple `Datelike::with_*` methods. The intermediate value may not exist.
1233 ///
1234 /// See also the [`NaiveDate::with_month`] method.
1235 ///
1236 /// # Errors
1237 ///
1238 /// Returns `None` if:
1239 /// - The resulting date does not exist (for example `month(4)` when day of the month is 31).
1240 /// - The value for `month` is invalid.
1241 /// - The local time at the resulting date does not exist or is ambiguous, for example during a
1242 /// daylight saving time transition.
1243 #[inline]
1244 fn with_month(&self, month: u32) -> Option<DateTime<Tz>> {
1245 map_local(self, |datetime| datetime.with_month(month))
1246 }
1247
1248 /// Makes a new `DateTime` with the month number (starting from 0) changed.
1249 ///
1250 /// See also the [`NaiveDate::with_month0`] method.
1251 ///
1252 /// # Errors
1253 ///
1254 /// Returns `None` if:
1255 /// - The resulting date does not exist (for example `month0(3)` when day of the month is 31).
1256 /// - The value for `month0` is invalid.
1257 /// - The local time at the resulting date does not exist or is ambiguous, for example during a
1258 /// daylight saving time transition.
1259 #[inline]
1260 fn with_month0(&self, month0: u32) -> Option<DateTime<Tz>> {
1261 map_local(self, |datetime| datetime.with_month0(month0))
1262 }
1263
1264 /// Makes a new `DateTime` with the day of month (starting from 1) changed.
1265 ///
1266 /// See also the [`NaiveDate::with_day`] method.
1267 ///
1268 /// # Errors
1269 ///
1270 /// Returns `None` if:
1271 /// - The resulting date does not exist (for example `day(31)` in April).
1272 /// - The value for `day` is invalid.
1273 /// - The local time at the resulting date does not exist or is ambiguous, for example during a
1274 /// daylight saving time transition.
1275 #[inline]
1276 fn with_day(&self, day: u32) -> Option<DateTime<Tz>> {
1277 map_local(self, |datetime| datetime.with_day(day))
1278 }
1279
1280 /// Makes a new `DateTime` with the day of month (starting from 0) changed.
1281 ///
1282 /// See also the [`NaiveDate::with_day0`] method.
1283 ///
1284 /// # Errors
1285 ///
1286 /// Returns `None` if:
1287 /// - The resulting date does not exist (for example `day(30)` in April).
1288 /// - The value for `day0` is invalid.
1289 /// - The local time at the resulting date does not exist or is ambiguous, for example during a
1290 /// daylight saving time transition.
1291 #[inline]
1292 fn with_day0(&self, day0: u32) -> Option<DateTime<Tz>> {
1293 map_local(self, |datetime| datetime.with_day0(day0))
1294 }
1295
1296 /// Makes a new `DateTime` with the day of year (starting from 1) changed.
1297 ///
1298 /// See also the [`NaiveDate::with_ordinal`] method.
1299 ///
1300 /// # Errors
1301 ///
1302 /// Returns `None` if:
1303 /// - The resulting date does not exist (`with_ordinal(366)` in a non-leap year).
1304 /// - The value for `ordinal` is invalid.
1305 /// - The local time at the resulting date does not exist or is ambiguous, for example during a
1306 /// daylight saving time transition.
1307 #[inline]
1308 fn with_ordinal(&self, ordinal: u32) -> Option<DateTime<Tz>> {
1309 map_local(self, |datetime| datetime.with_ordinal(ordinal))
1310 }
1311
1312 /// Makes a new `DateTime` with the day of year (starting from 0) changed.
1313 ///
1314 /// See also the [`NaiveDate::with_ordinal0`] method.
1315 ///
1316 /// # Errors
1317 ///
1318 /// Returns `None` if:
1319 /// - The resulting date does not exist (`with_ordinal0(365)` in a non-leap year).
1320 /// - The value for `ordinal0` is invalid.
1321 /// - The local time at the resulting date does not exist or is ambiguous, for example during a
1322 /// daylight saving time transition.
1323 #[inline]
1324 fn with_ordinal0(&self, ordinal0: u32) -> Option<DateTime<Tz>> {
1325 map_local(self, |datetime| datetime.with_ordinal0(ordinal0))
1326 }
1327}
1328
1329impl<Tz: TimeZone> Timelike for DateTime<Tz> {
1330 #[inline]
1331 fn hour(&self) -> u32 {
1332 self.overflowing_naive_local().hour()
1333 }
1334 #[inline]
1335 fn minute(&self) -> u32 {
1336 self.overflowing_naive_local().minute()
1337 }
1338 #[inline]
1339 fn second(&self) -> u32 {
1340 self.overflowing_naive_local().second()
1341 }
1342 #[inline]
1343 fn nanosecond(&self) -> u32 {
1344 self.overflowing_naive_local().nanosecond()
1345 }
1346
1347 /// Makes a new `DateTime` with the hour number changed.
1348 ///
1349 /// See also the [`NaiveTime::with_hour`] method.
1350 ///
1351 /// # Errors
1352 ///
1353 /// Returns `None` if:
1354 /// - The value for `hour` is invalid.
1355 /// - The local time at the resulting date does not exist or is ambiguous, for example during a
1356 /// daylight saving time transition.
1357 #[inline]
1358 fn with_hour(&self, hour: u32) -> Option<DateTime<Tz>> {
1359 map_local(self, |datetime| datetime.with_hour(hour))
1360 }
1361
1362 /// Makes a new `DateTime` with the minute number changed.
1363 ///
1364 /// See also the [`NaiveTime::with_minute`] method.
1365 ///
1366 /// # Errors
1367 ///
1368 /// - The value for `minute` is invalid.
1369 /// - The local time at the resulting date does not exist or is ambiguous, for example during a
1370 /// daylight saving time transition.
1371 #[inline]
1372 fn with_minute(&self, min: u32) -> Option<DateTime<Tz>> {
1373 map_local(self, |datetime| datetime.with_minute(min))
1374 }
1375
1376 /// Makes a new `DateTime` with the second number changed.
1377 ///
1378 /// As with the [`second`](#method.second) method,
1379 /// the input range is restricted to 0 through 59.
1380 ///
1381 /// See also the [`NaiveTime::with_second`] method.
1382 ///
1383 /// # Errors
1384 ///
1385 /// Returns `None` if:
1386 /// - The value for `second` is invalid.
1387 /// - The local time at the resulting date does not exist or is ambiguous, for example during a
1388 /// daylight saving time transition.
1389 #[inline]
1390 fn with_second(&self, sec: u32) -> Option<DateTime<Tz>> {
1391 map_local(self, |datetime| datetime.with_second(sec))
1392 }
1393
1394 /// Makes a new `DateTime` with nanoseconds since the whole non-leap second changed.
1395 ///
1396 /// Returns `None` when the resulting `NaiveDateTime` would be invalid.
1397 /// As with the [`NaiveDateTime::nanosecond`] method,
1398 /// the input range can exceed 1,000,000,000 for leap seconds.
1399 ///
1400 /// See also the [`NaiveTime::with_nanosecond`] method.
1401 ///
1402 /// # Errors
1403 ///
1404 /// Returns `None` if `nanosecond >= 2,000,000,000`.
1405 #[inline]
1406 fn with_nanosecond(&self, nano: u32) -> Option<DateTime<Tz>> {
1407 map_local(self, |datetime| datetime.with_nanosecond(nano))
1408 }
1409}
1410
1411// We don't store a field with the `Tz` type, so it doesn't need to influence whether `DateTime` can
1412// be `Copy`. Implement it manually if the two types we do have are `Copy`.
1413impl<Tz: TimeZone> Copy for DateTime<Tz>
1414where
1415 <Tz as TimeZone>::Offset: Copy,
1416 NaiveDateTime: Copy,
1417{
1418}
1419
1420impl<Tz: TimeZone, Tz2: TimeZone> PartialEq<DateTime<Tz2>> for DateTime<Tz> {
1421 fn eq(&self, other: &DateTime<Tz2>) -> bool {
1422 self.datetime == other.datetime
1423 }
1424}
1425
1426impl<Tz: TimeZone> Eq for DateTime<Tz> {}
1427
1428impl<Tz: TimeZone, Tz2: TimeZone> PartialOrd<DateTime<Tz2>> for DateTime<Tz> {
1429 /// Compare two DateTimes based on their true time, ignoring time zones
1430 ///
1431 /// # Example
1432 ///
1433 /// ```
1434 /// use chrono::prelude::*;
1435 ///
1436 /// let earlier = Utc
1437 /// .with_ymd_and_hms(2015, 5, 15, 2, 0, 0)
1438 /// .unwrap()
1439 /// .with_timezone(&FixedOffset::west_opt(1 * 3600).unwrap());
1440 /// let later = Utc
1441 /// .with_ymd_and_hms(2015, 5, 15, 3, 0, 0)
1442 /// .unwrap()
1443 /// .with_timezone(&FixedOffset::west_opt(5 * 3600).unwrap());
1444 ///
1445 /// assert_eq!(earlier.to_string(), "2015-05-15 01:00:00 -01:00");
1446 /// assert_eq!(later.to_string(), "2015-05-14 22:00:00 -05:00");
1447 ///
1448 /// assert!(later > earlier);
1449 /// ```
1450 fn partial_cmp(&self, other: &DateTime<Tz2>) -> Option<Ordering> {
1451 self.datetime.partial_cmp(&other.datetime)
1452 }
1453}
1454
1455impl<Tz: TimeZone> Ord for DateTime<Tz> {
1456 fn cmp(&self, other: &DateTime<Tz>) -> Ordering {
1457 self.datetime.cmp(&other.datetime)
1458 }
1459}
1460
1461impl<Tz: TimeZone> hash::Hash for DateTime<Tz> {
1462 fn hash<H: hash::Hasher>(&self, state: &mut H) {
1463 self.datetime.hash(state)
1464 }
1465}
1466
1467/// Add `TimeDelta` to `DateTime`.
1468///
1469/// As a part of Chrono's [leap second handling], the addition assumes that **there is no leap
1470/// second ever**, except when the `NaiveDateTime` itself represents a leap second in which case
1471/// the assumption becomes that **there is exactly a single leap second ever**.
1472///
1473/// # Panics
1474///
1475/// Panics if the resulting date would be out of range.
1476/// Consider using [`DateTime<Tz>::checked_add_signed`] to get an `Option` instead.
1477impl<Tz: TimeZone> Add<TimeDelta> for DateTime<Tz> {
1478 type Output = DateTime<Tz>;
1479
1480 #[inline]
1481 fn add(self, rhs: TimeDelta) -> DateTime<Tz> {
1482 self.checked_add_signed(rhs).expect(msg:"`DateTime + TimeDelta` overflowed")
1483 }
1484}
1485
1486/// Add `std::time::Duration` to `DateTime`.
1487///
1488/// As a part of Chrono's [leap second handling], the addition assumes that **there is no leap
1489/// second ever**, except when the `NaiveDateTime` itself represents a leap second in which case
1490/// the assumption becomes that **there is exactly a single leap second ever**.
1491///
1492/// # Panics
1493///
1494/// Panics if the resulting date would be out of range.
1495/// Consider using [`DateTime<Tz>::checked_add_signed`] to get an `Option` instead.
1496impl<Tz: TimeZone> Add<Duration> for DateTime<Tz> {
1497 type Output = DateTime<Tz>;
1498
1499 #[inline]
1500 fn add(self, rhs: Duration) -> DateTime<Tz> {
1501 let rhs: TimeDelta = TimeDelta::from_std(rhs)
1502 .expect(msg:"overflow converting from core::time::Duration to TimeDelta");
1503 self.checked_add_signed(rhs).expect(msg:"`DateTime + TimeDelta` overflowed")
1504 }
1505}
1506
1507/// Add-assign `chrono::Duration` to `DateTime`.
1508///
1509/// As a part of Chrono's [leap second handling], the addition assumes that **there is no leap
1510/// second ever**, except when the `NaiveDateTime` itself represents a leap second in which case
1511/// the assumption becomes that **there is exactly a single leap second ever**.
1512///
1513/// # Panics
1514///
1515/// Panics if the resulting date would be out of range.
1516/// Consider using [`DateTime<Tz>::checked_add_signed`] to get an `Option` instead.
1517impl<Tz: TimeZone> AddAssign<TimeDelta> for DateTime<Tz> {
1518 #[inline]
1519 fn add_assign(&mut self, rhs: TimeDelta) {
1520 let datetime: NaiveDateTime =
1521 self.datetime.checked_add_signed(rhs).expect(msg:"`DateTime + TimeDelta` overflowed");
1522 let tz: Tz = self.timezone();
1523 *self = tz.from_utc_datetime(&datetime);
1524 }
1525}
1526
1527/// Add-assign `std::time::Duration` to `DateTime`.
1528///
1529/// As a part of Chrono's [leap second handling], the addition assumes that **there is no leap
1530/// second ever**, except when the `NaiveDateTime` itself represents a leap second in which case
1531/// the assumption becomes that **there is exactly a single leap second ever**.
1532///
1533/// # Panics
1534///
1535/// Panics if the resulting date would be out of range.
1536/// Consider using [`DateTime<Tz>::checked_add_signed`] to get an `Option` instead.
1537impl<Tz: TimeZone> AddAssign<Duration> for DateTime<Tz> {
1538 #[inline]
1539 fn add_assign(&mut self, rhs: Duration) {
1540 let rhs: TimeDelta = TimeDelta::from_std(rhs)
1541 .expect(msg:"overflow converting from core::time::Duration to TimeDelta");
1542 *self += rhs;
1543 }
1544}
1545
1546/// Add `FixedOffset` to the datetime value of `DateTime` (offset remains unchanged).
1547///
1548/// # Panics
1549///
1550/// Panics if the resulting date would be out of range.
1551impl<Tz: TimeZone> Add<FixedOffset> for DateTime<Tz> {
1552 type Output = DateTime<Tz>;
1553
1554 #[inline]
1555 fn add(mut self, rhs: FixedOffset) -> DateTime<Tz> {
1556 self.datetime =
1557 self.naive_utc().checked_add_offset(rhs).expect(msg:"`DateTime + FixedOffset` overflowed");
1558 self
1559 }
1560}
1561
1562/// Add `Months` to `DateTime`.
1563///
1564/// The result will be clamped to valid days in the resulting month, see `checked_add_months` for
1565/// details.
1566///
1567/// # Panics
1568///
1569/// Panics if:
1570/// - The resulting date would be out of range.
1571/// - The local time at the resulting date does not exist or is ambiguous, for example during a
1572/// daylight saving time transition.
1573///
1574/// Strongly consider using [`DateTime<Tz>::checked_add_months`] to get an `Option` instead.
1575impl<Tz: TimeZone> Add<Months> for DateTime<Tz> {
1576 type Output = DateTime<Tz>;
1577
1578 fn add(self, rhs: Months) -> Self::Output {
1579 self.checked_add_months(rhs).expect(msg:"`DateTime + Months` out of range")
1580 }
1581}
1582
1583/// Subtract `TimeDelta` from `DateTime`.
1584///
1585/// This is the same as the addition with a negated `TimeDelta`.
1586///
1587/// As a part of Chrono's [leap second handling] the subtraction assumes that **there is no leap
1588/// second ever**, except when the `DateTime` itself represents a leap second in which case
1589/// the assumption becomes that **there is exactly a single leap second ever**.
1590///
1591/// # Panics
1592///
1593/// Panics if the resulting date would be out of range.
1594/// Consider using [`DateTime<Tz>::checked_sub_signed`] to get an `Option` instead.
1595impl<Tz: TimeZone> Sub<TimeDelta> for DateTime<Tz> {
1596 type Output = DateTime<Tz>;
1597
1598 #[inline]
1599 fn sub(self, rhs: TimeDelta) -> DateTime<Tz> {
1600 self.checked_sub_signed(rhs).expect(msg:"`DateTime - TimeDelta` overflowed")
1601 }
1602}
1603
1604/// Subtract `std::time::Duration` from `DateTime`.
1605///
1606/// As a part of Chrono's [leap second handling] the subtraction assumes that **there is no leap
1607/// second ever**, except when the `DateTime` itself represents a leap second in which case
1608/// the assumption becomes that **there is exactly a single leap second ever**.
1609///
1610/// # Panics
1611///
1612/// Panics if the resulting date would be out of range.
1613/// Consider using [`DateTime<Tz>::checked_sub_signed`] to get an `Option` instead.
1614impl<Tz: TimeZone> Sub<Duration> for DateTime<Tz> {
1615 type Output = DateTime<Tz>;
1616
1617 #[inline]
1618 fn sub(self, rhs: Duration) -> DateTime<Tz> {
1619 let rhs: TimeDelta = TimeDelta::from_std(rhs)
1620 .expect(msg:"overflow converting from core::time::Duration to TimeDelta");
1621 self.checked_sub_signed(rhs).expect(msg:"`DateTime - TimeDelta` overflowed")
1622 }
1623}
1624
1625/// Subtract-assign `TimeDelta` from `DateTime`.
1626///
1627/// This is the same as the addition with a negated `TimeDelta`.
1628///
1629/// As a part of Chrono's [leap second handling], the addition assumes that **there is no leap
1630/// second ever**, except when the `DateTime` itself represents a leap second in which case
1631/// the assumption becomes that **there is exactly a single leap second ever**.
1632///
1633/// # Panics
1634///
1635/// Panics if the resulting date would be out of range.
1636/// Consider using [`DateTime<Tz>::checked_sub_signed`] to get an `Option` instead.
1637impl<Tz: TimeZone> SubAssign<TimeDelta> for DateTime<Tz> {
1638 #[inline]
1639 fn sub_assign(&mut self, rhs: TimeDelta) {
1640 let datetime: NaiveDateTime =
1641 self.datetime.checked_sub_signed(rhs).expect(msg:"`DateTime - TimeDelta` overflowed");
1642 let tz: Tz = self.timezone();
1643 *self = tz.from_utc_datetime(&datetime)
1644 }
1645}
1646
1647/// Subtract-assign `std::time::Duration` from `DateTime`.
1648///
1649/// As a part of Chrono's [leap second handling], the addition assumes that **there is no leap
1650/// second ever**, except when the `DateTime` itself represents a leap second in which case
1651/// the assumption becomes that **there is exactly a single leap second ever**.
1652///
1653/// # Panics
1654///
1655/// Panics if the resulting date would be out of range.
1656/// Consider using [`DateTime<Tz>::checked_sub_signed`] to get an `Option` instead.
1657impl<Tz: TimeZone> SubAssign<Duration> for DateTime<Tz> {
1658 #[inline]
1659 fn sub_assign(&mut self, rhs: Duration) {
1660 let rhs: TimeDelta = TimeDelta::from_std(rhs)
1661 .expect(msg:"overflow converting from core::time::Duration to TimeDelta");
1662 *self -= rhs;
1663 }
1664}
1665
1666/// Subtract `FixedOffset` from the datetime value of `DateTime` (offset remains unchanged).
1667///
1668/// # Panics
1669///
1670/// Panics if the resulting date would be out of range.
1671impl<Tz: TimeZone> Sub<FixedOffset> for DateTime<Tz> {
1672 type Output = DateTime<Tz>;
1673
1674 #[inline]
1675 fn sub(mut self, rhs: FixedOffset) -> DateTime<Tz> {
1676 self.datetime =
1677 self.naive_utc().checked_sub_offset(rhs).expect(msg:"`DateTime - FixedOffset` overflowed");
1678 self
1679 }
1680}
1681
1682/// Subtract `Months` from `DateTime`.
1683///
1684/// The result will be clamped to valid days in the resulting month, see
1685/// [`DateTime<Tz>::checked_sub_months`] for details.
1686///
1687/// # Panics
1688///
1689/// Panics if:
1690/// - The resulting date would be out of range.
1691/// - The local time at the resulting date does not exist or is ambiguous, for example during a
1692/// daylight saving time transition.
1693///
1694/// Strongly consider using [`DateTime<Tz>::checked_sub_months`] to get an `Option` instead.
1695impl<Tz: TimeZone> Sub<Months> for DateTime<Tz> {
1696 type Output = DateTime<Tz>;
1697
1698 fn sub(self, rhs: Months) -> Self::Output {
1699 self.checked_sub_months(rhs).expect(msg:"`DateTime - Months` out of range")
1700 }
1701}
1702
1703impl<Tz: TimeZone> Sub<DateTime<Tz>> for DateTime<Tz> {
1704 type Output = TimeDelta;
1705
1706 #[inline]
1707 fn sub(self, rhs: DateTime<Tz>) -> TimeDelta {
1708 self.signed_duration_since(rhs)
1709 }
1710}
1711
1712impl<Tz: TimeZone> Sub<&DateTime<Tz>> for DateTime<Tz> {
1713 type Output = TimeDelta;
1714
1715 #[inline]
1716 fn sub(self, rhs: &DateTime<Tz>) -> TimeDelta {
1717 self.signed_duration_since(rhs)
1718 }
1719}
1720
1721/// Add `Days` to `NaiveDateTime`.
1722///
1723/// # Panics
1724///
1725/// Panics if:
1726/// - The resulting date would be out of range.
1727/// - The local time at the resulting date does not exist or is ambiguous, for example during a
1728/// daylight saving time transition.
1729///
1730/// Strongly consider using `DateTime<Tz>::checked_add_days` to get an `Option` instead.
1731impl<Tz: TimeZone> Add<Days> for DateTime<Tz> {
1732 type Output = DateTime<Tz>;
1733
1734 fn add(self, days: Days) -> Self::Output {
1735 self.checked_add_days(days).expect(msg:"`DateTime + Days` out of range")
1736 }
1737}
1738
1739/// Subtract `Days` from `DateTime`.
1740///
1741/// # Panics
1742///
1743/// Panics if:
1744/// - The resulting date would be out of range.
1745/// - The local time at the resulting date does not exist or is ambiguous, for example during a
1746/// daylight saving time transition.
1747///
1748/// Strongly consider using `DateTime<Tz>::checked_sub_days` to get an `Option` instead.
1749impl<Tz: TimeZone> Sub<Days> for DateTime<Tz> {
1750 type Output = DateTime<Tz>;
1751
1752 fn sub(self, days: Days) -> Self::Output {
1753 self.checked_sub_days(days).expect(msg:"`DateTime - Days` out of range")
1754 }
1755}
1756
1757impl<Tz: TimeZone> fmt::Debug for DateTime<Tz> {
1758 fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
1759 self.overflowing_naive_local().fmt(f)?;
1760 self.offset.fmt(f)
1761 }
1762}
1763
1764// `fmt::Debug` is hand implemented for the `rkyv::Archive` variant of `DateTime` because
1765// deriving a trait recursively does not propagate trait defined associated types with their own
1766// constraints:
1767// In our case `<<Tz as offset::TimeZone>::Offset as Archive>::Archived`
1768// cannot be formatted using `{:?}` because it doesn't implement `Debug`.
1769// See below for further discussion:
1770// * https://github.com/rust-lang/rust/issues/26925
1771// * https://github.com/rkyv/rkyv/issues/333
1772// * https://github.com/dtolnay/syn/issues/370
1773#[cfg(feature = "rkyv-validation")]
1774impl<Tz: TimeZone> fmt::Debug for ArchivedDateTime<Tz>
1775where
1776 Tz: Archive,
1777 <Tz as Archive>::Archived: fmt::Debug,
1778 <<Tz as TimeZone>::Offset as Archive>::Archived: fmt::Debug,
1779 <Tz as TimeZone>::Offset: fmt::Debug + Archive,
1780{
1781 fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
1782 f.debug_struct("ArchivedDateTime")
1783 .field("datetime", &self.datetime)
1784 .field("offset", &self.offset)
1785 .finish()
1786 }
1787}
1788
1789impl<Tz: TimeZone> fmt::Display for DateTime<Tz>
1790where
1791 Tz::Offset: fmt::Display,
1792{
1793 fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
1794 self.overflowing_naive_local().fmt(f)?;
1795 f.write_char(' ')?;
1796 self.offset.fmt(f)
1797 }
1798}
1799
1800/// Accepts a relaxed form of RFC3339.
1801/// A space or a 'T' are accepted as the separator between the date and time
1802/// parts.
1803///
1804/// All of these examples are equivalent:
1805/// ```
1806/// # use chrono::{DateTime, Utc};
1807/// "2012-12-12T12:12:12Z".parse::<DateTime<Utc>>()?;
1808/// "2012-12-12 12:12:12Z".parse::<DateTime<Utc>>()?;
1809/// "2012-12-12 12:12:12+0000".parse::<DateTime<Utc>>()?;
1810/// "2012-12-12 12:12:12+00:00".parse::<DateTime<Utc>>()?;
1811/// # Ok::<(), chrono::ParseError>(())
1812/// ```
1813impl str::FromStr for DateTime<Utc> {
1814 type Err = ParseError;
1815
1816 fn from_str(s: &str) -> ParseResult<DateTime<Utc>> {
1817 s.parse::<DateTime<FixedOffset>>().map(|dt: DateTime| dt.with_timezone(&Utc))
1818 }
1819}
1820
1821/// Accepts a relaxed form of RFC3339.
1822/// A space or a 'T' are accepted as the separator between the date and time
1823/// parts.
1824///
1825/// All of these examples are equivalent:
1826/// ```
1827/// # use chrono::{DateTime, Local};
1828/// "2012-12-12T12:12:12Z".parse::<DateTime<Local>>()?;
1829/// "2012-12-12 12:12:12Z".parse::<DateTime<Local>>()?;
1830/// "2012-12-12 12:12:12+0000".parse::<DateTime<Local>>()?;
1831/// "2012-12-12 12:12:12+00:00".parse::<DateTime<Local>>()?;
1832/// # Ok::<(), chrono::ParseError>(())
1833/// ```
1834#[cfg(feature = "clock")]
1835impl str::FromStr for DateTime<Local> {
1836 type Err = ParseError;
1837
1838 fn from_str(s: &str) -> ParseResult<DateTime<Local>> {
1839 s.parse::<DateTime<FixedOffset>>().map(|dt: DateTime| dt.with_timezone(&Local))
1840 }
1841}
1842
1843#[cfg(feature = "std")]
1844impl From<SystemTime> for DateTime<Utc> {
1845 fn from(t: SystemTime) -> DateTime<Utc> {
1846 let (sec: i64, nsec: u32) = match t.duration_since(UNIX_EPOCH) {
1847 Ok(dur: Duration) => (dur.as_secs() as i64, dur.subsec_nanos()),
1848 Err(e: SystemTimeError) => {
1849 // unlikely but should be handled
1850 let dur: Duration = e.duration();
1851 let (sec: i64, nsec: u32) = (dur.as_secs() as i64, dur.subsec_nanos());
1852 if nsec == 0 { (-sec, 0) } else { (-sec - 1, 1_000_000_000 - nsec) }
1853 }
1854 };
1855 Utc.timestamp_opt(secs:sec, nsecs:nsec).unwrap()
1856 }
1857}
1858
1859#[cfg(feature = "clock")]
1860impl From<SystemTime> for DateTime<Local> {
1861 fn from(t: SystemTime) -> DateTime<Local> {
1862 DateTime::<Utc>::from(t).with_timezone(&Local)
1863 }
1864}
1865
1866#[cfg(feature = "std")]
1867impl<Tz: TimeZone> From<DateTime<Tz>> for SystemTime {
1868 fn from(dt: DateTime<Tz>) -> SystemTime {
1869 let sec: i64 = dt.timestamp();
1870 let nsec: u32 = dt.timestamp_subsec_nanos();
1871 if sec < 0 {
1872 // unlikely but should be handled
1873 UNIX_EPOCH - Duration::new(-sec as u64, nanos:0) + Duration::new(secs:0, nanos:nsec)
1874 } else {
1875 UNIX_EPOCH + Duration::new(secs:sec as u64, nanos:nsec)
1876 }
1877 }
1878}
1879
1880#[cfg(all(
1881 target_arch = "wasm32",
1882 feature = "wasmbind",
1883 not(any(target_os = "emscripten", target_os = "wasi"))
1884))]
1885impl From<js_sys::Date> for DateTime<Utc> {
1886 fn from(date: js_sys::Date) -> DateTime<Utc> {
1887 DateTime::<Utc>::from(&date)
1888 }
1889}
1890
1891#[cfg(all(
1892 target_arch = "wasm32",
1893 feature = "wasmbind",
1894 not(any(target_os = "emscripten", target_os = "wasi"))
1895))]
1896impl From<&js_sys::Date> for DateTime<Utc> {
1897 fn from(date: &js_sys::Date) -> DateTime<Utc> {
1898 Utc.timestamp_millis_opt(date.get_time() as i64).unwrap()
1899 }
1900}
1901
1902#[cfg(all(
1903 target_arch = "wasm32",
1904 feature = "wasmbind",
1905 not(any(target_os = "emscripten", target_os = "wasi"))
1906))]
1907impl From<DateTime<Utc>> for js_sys::Date {
1908 /// Converts a `DateTime<Utc>` to a JS `Date`. The resulting value may be lossy,
1909 /// any values that have a millisecond timestamp value greater/less than ±8,640,000,000,000,000
1910 /// (April 20, 271821 BCE ~ September 13, 275760 CE) will become invalid dates in JS.
1911 fn from(date: DateTime<Utc>) -> js_sys::Date {
1912 let js_millis = wasm_bindgen::JsValue::from_f64(date.timestamp_millis() as f64);
1913 js_sys::Date::new(&js_millis)
1914 }
1915}
1916
1917// Note that implementation of Arbitrary cannot be simply derived for DateTime<Tz>, due to
1918// the nontrivial bound <Tz as TimeZone>::Offset: Arbitrary.
1919#[cfg(all(feature = "arbitrary", feature = "std"))]
1920impl<'a, Tz> arbitrary::Arbitrary<'a> for DateTime<Tz>
1921where
1922 Tz: TimeZone,
1923 <Tz as TimeZone>::Offset: arbitrary::Arbitrary<'a>,
1924{
1925 fn arbitrary(u: &mut arbitrary::Unstructured<'a>) -> arbitrary::Result<DateTime<Tz>> {
1926 let datetime = NaiveDateTime::arbitrary(u)?;
1927 let offset = <Tz as TimeZone>::Offset::arbitrary(u)?;
1928 Ok(DateTime::from_naive_utc_and_offset(datetime, offset))
1929 }
1930}
1931
1932/// Number of days between Januari 1, 1970 and December 31, 1 BCE which we define to be day 0.
1933/// 4 full leap year cycles until December 31, 1600 4 * 146097 = 584388
1934/// 1 day until January 1, 1601 1
1935/// 369 years until Januari 1, 1970 369 * 365 = 134685
1936/// of which floor(369 / 4) are leap years floor(369 / 4) = 92
1937/// except for 1700, 1800 and 1900 -3 +
1938/// --------
1939/// 719163
1940const UNIX_EPOCH_DAY: i64 = 719_163;
1941