1// This is a part of Chrono.
2// See README.md and LICENSE.txt for details.
3
4//! The time zone, which calculates offsets from the local time to UTC.
5//!
6//! There are four operations provided by the `TimeZone` trait:
7//!
8//! 1. Converting the local `NaiveDateTime` to `DateTime<Tz>`
9//! 2. Converting the UTC `NaiveDateTime` to `DateTime<Tz>`
10//! 3. Converting `DateTime<Tz>` to the local `NaiveDateTime`
11//! 4. Constructing `DateTime<Tz>` objects from various offsets
12//!
13//! 1 is used for constructors. 2 is used for the `with_timezone` method of date and time types.
14//! 3 is used for other methods, e.g. `year()` or `format()`, and provided by an associated type
15//! which implements `Offset` (which then passed to `TimeZone` for actual implementations).
16//! Technically speaking `TimeZone` has a total knowledge about given timescale,
17//! but `Offset` is used as a cache to avoid the repeated conversion
18//! and provides implementations for 1 and 3.
19//! An `TimeZone` instance can be reconstructed from the corresponding `Offset` instance.
20
21use core::fmt;
22
23use crate::format::{parse, ParseResult, Parsed, StrftimeItems};
24use crate::naive::{NaiveDate, NaiveDateTime, NaiveTime};
25use crate::Weekday;
26#[allow(deprecated)]
27use crate::{Date, DateTime};
28
29pub(crate) mod fixed;
30pub use self::fixed::FixedOffset;
31
32#[cfg(feature = "clock")]
33pub(crate) mod local;
34#[cfg(feature = "clock")]
35pub use self::local::Local;
36
37pub(crate) mod utc;
38pub use self::utc::Utc;
39
40/// The result of mapping a local time to a concrete instant in a given time zone.
41///
42/// The calculation to go from a local time (wall clock time) to an instant in UTC can end up in
43/// three cases:
44/// * A single, simple result.
45/// * An ambiguous result when the clock is turned backwards during a transition due to for example
46/// DST.
47/// * No result when the clock is turned forwards during a transition due to for example DST.
48///
49/// When the clock is turned backwards it creates a _fold_ in local time, during which the local
50/// time is _ambiguous_. When the clock is turned forwards it creates a _gap_ in local time, during
51/// which the local time is _missing_, or does not exist.
52///
53/// Chrono does not return a default choice or invalid data during time zone transitions, but has
54/// the `MappedLocalTime` type to help deal with the result correctly.
55///
56/// The type of `T` is usually a [`DateTime`] but may also be only an offset.
57pub type MappedLocalTime<T> = LocalResult<T>;
58#[derive(Clone, PartialEq, Debug, Copy, Eq, Hash)]
59
60/// Old name of [`MappedLocalTime`]. See that type for more documentation.
61pub enum LocalResult<T> {
62 /// The local time maps to a single unique result.
63 Single(T),
64
65 /// The local time is _ambiguous_ because there is a _fold_ in the local time.
66 ///
67 /// This variant contains the two possible results, in the order `(earliest, latest)`.
68 Ambiguous(T, T),
69
70 /// The local time does not exist because there is a _gap_ in the local time.
71 ///
72 /// This variant may also be returned if there was an error while resolving the local time,
73 /// caused by for example missing time zone data files, an error in an OS API, or overflow.
74 None,
75}
76
77impl<T> MappedLocalTime<T> {
78 /// Returns `Some` if the time zone mapping has a single result.
79 ///
80 /// # Errors
81 ///
82 /// Returns `None` if local time falls in a _fold_ or _gap_ in the local time, or if there was
83 /// an error.
84 #[must_use]
85 pub fn single(self) -> Option<T> {
86 match self {
87 MappedLocalTime::Single(t) => Some(t),
88 _ => None,
89 }
90 }
91
92 /// Returns the earliest possible result of the time zone mapping.
93 ///
94 /// # Errors
95 ///
96 /// Returns `None` if local time falls in a _gap_ in the local time, or if there was an error.
97 #[must_use]
98 pub fn earliest(self) -> Option<T> {
99 match self {
100 MappedLocalTime::Single(t) | MappedLocalTime::Ambiguous(t, _) => Some(t),
101 _ => None,
102 }
103 }
104
105 /// Returns the latest possible result of the time zone mapping.
106 ///
107 /// # Errors
108 ///
109 /// Returns `None` if local time falls in a _gap_ in the local time, or if there was an error.
110 #[must_use]
111 pub fn latest(self) -> Option<T> {
112 match self {
113 MappedLocalTime::Single(t) | MappedLocalTime::Ambiguous(_, t) => Some(t),
114 _ => None,
115 }
116 }
117
118 /// Maps a `MappedLocalTime<T>` into `MappedLocalTime<U>` with given function.
119 #[must_use]
120 pub fn map<U, F: FnMut(T) -> U>(self, mut f: F) -> MappedLocalTime<U> {
121 match self {
122 MappedLocalTime::None => MappedLocalTime::None,
123 MappedLocalTime::Single(v) => MappedLocalTime::Single(f(v)),
124 MappedLocalTime::Ambiguous(min, max) => MappedLocalTime::Ambiguous(f(min), f(max)),
125 }
126 }
127
128 /// Maps a `MappedLocalTime<T>` into `MappedLocalTime<U>` with given function.
129 ///
130 /// Returns `MappedLocalTime::None` if the function returns `None`.
131 #[must_use]
132 pub(crate) fn and_then<U, F: FnMut(T) -> Option<U>>(self, mut f: F) -> MappedLocalTime<U> {
133 match self {
134 MappedLocalTime::None => MappedLocalTime::None,
135 MappedLocalTime::Single(v) => match f(v) {
136 Some(new) => MappedLocalTime::Single(new),
137 None => MappedLocalTime::None,
138 },
139 MappedLocalTime::Ambiguous(min, max) => match (f(min), f(max)) {
140 (Some(min), Some(max)) => MappedLocalTime::Ambiguous(min, max),
141 _ => MappedLocalTime::None,
142 },
143 }
144 }
145}
146
147#[allow(deprecated)]
148impl<Tz: TimeZone> MappedLocalTime<Date<Tz>> {
149 /// Makes a new `DateTime` from the current date and given `NaiveTime`.
150 /// The offset in the current date is preserved.
151 ///
152 /// Propagates any error. Ambiguous result would be discarded.
153 #[inline]
154 #[must_use]
155 pub fn and_time(self, time: NaiveTime) -> MappedLocalTime<DateTime<Tz>> {
156 match self {
157 MappedLocalTime::Single(d) => {
158 d.and_time(time).map_or(MappedLocalTime::None, MappedLocalTime::Single)
159 }
160 _ => MappedLocalTime::None,
161 }
162 }
163
164 /// Makes a new `DateTime` from the current date, hour, minute and second.
165 /// The offset in the current date is preserved.
166 ///
167 /// Propagates any error. Ambiguous result would be discarded.
168 #[inline]
169 #[must_use]
170 pub fn and_hms_opt(self, hour: u32, min: u32, sec: u32) -> MappedLocalTime<DateTime<Tz>> {
171 match self {
172 MappedLocalTime::Single(d) => {
173 d.and_hms_opt(hour, min, sec).map_or(MappedLocalTime::None, MappedLocalTime::Single)
174 }
175 _ => MappedLocalTime::None,
176 }
177 }
178
179 /// Makes a new `DateTime` from the current date, hour, minute, second and millisecond.
180 /// The millisecond part can exceed 1,000 in order to represent the leap second.
181 /// The offset in the current date is preserved.
182 ///
183 /// Propagates any error. Ambiguous result would be discarded.
184 #[inline]
185 #[must_use]
186 pub fn and_hms_milli_opt(
187 self,
188 hour: u32,
189 min: u32,
190 sec: u32,
191 milli: u32,
192 ) -> MappedLocalTime<DateTime<Tz>> {
193 match self {
194 MappedLocalTime::Single(d) => d
195 .and_hms_milli_opt(hour, min, sec, milli)
196 .map_or(MappedLocalTime::None, MappedLocalTime::Single),
197 _ => MappedLocalTime::None,
198 }
199 }
200
201 /// Makes a new `DateTime` from the current date, hour, minute, second and microsecond.
202 /// The microsecond part can exceed 1,000,000 in order to represent the leap second.
203 /// The offset in the current date is preserved.
204 ///
205 /// Propagates any error. Ambiguous result would be discarded.
206 #[inline]
207 #[must_use]
208 pub fn and_hms_micro_opt(
209 self,
210 hour: u32,
211 min: u32,
212 sec: u32,
213 micro: u32,
214 ) -> MappedLocalTime<DateTime<Tz>> {
215 match self {
216 MappedLocalTime::Single(d) => d
217 .and_hms_micro_opt(hour, min, sec, micro)
218 .map_or(MappedLocalTime::None, MappedLocalTime::Single),
219 _ => MappedLocalTime::None,
220 }
221 }
222
223 /// Makes a new `DateTime` from the current date, hour, minute, second and nanosecond.
224 /// The nanosecond part can exceed 1,000,000,000 in order to represent the leap second.
225 /// The offset in the current date is preserved.
226 ///
227 /// Propagates any error. Ambiguous result would be discarded.
228 #[inline]
229 #[must_use]
230 pub fn and_hms_nano_opt(
231 self,
232 hour: u32,
233 min: u32,
234 sec: u32,
235 nano: u32,
236 ) -> MappedLocalTime<DateTime<Tz>> {
237 match self {
238 MappedLocalTime::Single(d) => d
239 .and_hms_nano_opt(hour, min, sec, nano)
240 .map_or(MappedLocalTime::None, MappedLocalTime::Single),
241 _ => MappedLocalTime::None,
242 }
243 }
244}
245
246impl<T: fmt::Debug> MappedLocalTime<T> {
247 /// Returns a single unique conversion result or panics.
248 ///
249 /// `unwrap()` is best combined with time zone types where the mapping can never fail like
250 /// [`Utc`] and [`FixedOffset`]. Note that for [`FixedOffset`] there is a rare case where a
251 /// resulting [`DateTime`] can be out of range.
252 ///
253 /// # Panics
254 ///
255 /// Panics if the local time falls within a _fold_ or a _gap_ in the local time, and on any
256 /// error that may have been returned by the type implementing [`TimeZone`].
257 #[must_use]
258 #[track_caller]
259 pub fn unwrap(self) -> T {
260 match self {
261 MappedLocalTime::None => panic!("No such local time"),
262 MappedLocalTime::Single(t: T) => t,
263 MappedLocalTime::Ambiguous(t1: T, t2: T) => {
264 panic!("Ambiguous local time, ranging from {:?} to {:?}", t1, t2)
265 }
266 }
267 }
268}
269
270/// The offset from the local time to UTC.
271pub trait Offset: Sized + Clone + fmt::Debug {
272 /// Returns the fixed offset from UTC to the local time stored.
273 fn fix(&self) -> FixedOffset;
274}
275
276/// The time zone.
277///
278/// The methods here are the primary constructors for the [`DateTime`] type.
279pub trait TimeZone: Sized + Clone {
280 /// An associated offset type.
281 /// This type is used to store the actual offset in date and time types.
282 /// The original `TimeZone` value can be recovered via `TimeZone::from_offset`.
283 type Offset: Offset;
284
285 /// Make a new `DateTime` from year, month, day, time components and current time zone.
286 ///
287 /// This assumes the proleptic Gregorian calendar, with the year 0 being 1 BCE.
288 ///
289 /// Returns `MappedLocalTime::None` on invalid input data.
290 fn with_ymd_and_hms(
291 &self,
292 year: i32,
293 month: u32,
294 day: u32,
295 hour: u32,
296 min: u32,
297 sec: u32,
298 ) -> MappedLocalTime<DateTime<Self>> {
299 match NaiveDate::from_ymd_opt(year, month, day).and_then(|d| d.and_hms_opt(hour, min, sec))
300 {
301 Some(dt) => self.from_local_datetime(&dt),
302 None => MappedLocalTime::None,
303 }
304 }
305
306 /// Makes a new `Date` from year, month, day and the current time zone.
307 /// This assumes the proleptic Gregorian calendar, with the year 0 being 1 BCE.
308 ///
309 /// The time zone normally does not affect the date (unless it is between UTC-24 and UTC+24),
310 /// but it will propagate to the `DateTime` values constructed via this date.
311 ///
312 /// Panics on the out-of-range date, invalid month and/or day.
313 #[deprecated(since = "0.4.23", note = "use `with_ymd_and_hms()` instead")]
314 #[allow(deprecated)]
315 fn ymd(&self, year: i32, month: u32, day: u32) -> Date<Self> {
316 self.ymd_opt(year, month, day).unwrap()
317 }
318
319 /// Makes a new `Date` from year, month, day and the current time zone.
320 /// This assumes the proleptic Gregorian calendar, with the year 0 being 1 BCE.
321 ///
322 /// The time zone normally does not affect the date (unless it is between UTC-24 and UTC+24),
323 /// but it will propagate to the `DateTime` values constructed via this date.
324 ///
325 /// Returns `None` on the out-of-range date, invalid month and/or day.
326 #[deprecated(since = "0.4.23", note = "use `with_ymd_and_hms()` instead")]
327 #[allow(deprecated)]
328 fn ymd_opt(&self, year: i32, month: u32, day: u32) -> MappedLocalTime<Date<Self>> {
329 match NaiveDate::from_ymd_opt(year, month, day) {
330 Some(d) => self.from_local_date(&d),
331 None => MappedLocalTime::None,
332 }
333 }
334
335 /// Makes a new `Date` from year, day of year (DOY or "ordinal") and the current time zone.
336 /// This assumes the proleptic Gregorian calendar, with the year 0 being 1 BCE.
337 ///
338 /// The time zone normally does not affect the date (unless it is between UTC-24 and UTC+24),
339 /// but it will propagate to the `DateTime` values constructed via this date.
340 ///
341 /// Panics on the out-of-range date and/or invalid DOY.
342 #[deprecated(
343 since = "0.4.23",
344 note = "use `from_local_datetime()` with a `NaiveDateTime` instead"
345 )]
346 #[allow(deprecated)]
347 fn yo(&self, year: i32, ordinal: u32) -> Date<Self> {
348 self.yo_opt(year, ordinal).unwrap()
349 }
350
351 /// Makes a new `Date` from year, day of year (DOY or "ordinal") and the current time zone.
352 /// This assumes the proleptic Gregorian calendar, with the year 0 being 1 BCE.
353 ///
354 /// The time zone normally does not affect the date (unless it is between UTC-24 and UTC+24),
355 /// but it will propagate to the `DateTime` values constructed via this date.
356 ///
357 /// Returns `None` on the out-of-range date and/or invalid DOY.
358 #[deprecated(
359 since = "0.4.23",
360 note = "use `from_local_datetime()` with a `NaiveDateTime` instead"
361 )]
362 #[allow(deprecated)]
363 fn yo_opt(&self, year: i32, ordinal: u32) -> MappedLocalTime<Date<Self>> {
364 match NaiveDate::from_yo_opt(year, ordinal) {
365 Some(d) => self.from_local_date(&d),
366 None => MappedLocalTime::None,
367 }
368 }
369
370 /// Makes a new `Date` from ISO week date (year and week number), day of the week (DOW) and
371 /// the current time zone.
372 /// This assumes the proleptic Gregorian calendar, with the year 0 being 1 BCE.
373 /// The resulting `Date` may have a different year from the input year.
374 ///
375 /// The time zone normally does not affect the date (unless it is between UTC-24 and UTC+24),
376 /// but it will propagate to the `DateTime` values constructed via this date.
377 ///
378 /// Panics on the out-of-range date and/or invalid week number.
379 #[deprecated(
380 since = "0.4.23",
381 note = "use `from_local_datetime()` with a `NaiveDateTime` instead"
382 )]
383 #[allow(deprecated)]
384 fn isoywd(&self, year: i32, week: u32, weekday: Weekday) -> Date<Self> {
385 self.isoywd_opt(year, week, weekday).unwrap()
386 }
387
388 /// Makes a new `Date` from ISO week date (year and week number), day of the week (DOW) and
389 /// the current time zone.
390 /// This assumes the proleptic Gregorian calendar, with the year 0 being 1 BCE.
391 /// The resulting `Date` may have a different year from the input year.
392 ///
393 /// The time zone normally does not affect the date (unless it is between UTC-24 and UTC+24),
394 /// but it will propagate to the `DateTime` values constructed via this date.
395 ///
396 /// Returns `None` on the out-of-range date and/or invalid week number.
397 #[deprecated(
398 since = "0.4.23",
399 note = "use `from_local_datetime()` with a `NaiveDateTime` instead"
400 )]
401 #[allow(deprecated)]
402 fn isoywd_opt(&self, year: i32, week: u32, weekday: Weekday) -> MappedLocalTime<Date<Self>> {
403 match NaiveDate::from_isoywd_opt(year, week, weekday) {
404 Some(d) => self.from_local_date(&d),
405 None => MappedLocalTime::None,
406 }
407 }
408
409 /// Makes a new `DateTime` from the number of non-leap seconds
410 /// since January 1, 1970 0:00:00 UTC (aka "UNIX timestamp")
411 /// and the number of nanoseconds since the last whole non-leap second.
412 ///
413 /// The nanosecond part can exceed 1,000,000,000 in order to represent a
414 /// [leap second](crate::NaiveTime#leap-second-handling), but only when `secs % 60 == 59`.
415 /// (The true "UNIX timestamp" cannot represent a leap second unambiguously.)
416 ///
417 /// # Panics
418 ///
419 /// Panics on the out-of-range number of seconds and/or invalid nanosecond,
420 /// for a non-panicking version see [`timestamp_opt`](#method.timestamp_opt).
421 #[deprecated(since = "0.4.23", note = "use `timestamp_opt()` instead")]
422 fn timestamp(&self, secs: i64, nsecs: u32) -> DateTime<Self> {
423 self.timestamp_opt(secs, nsecs).unwrap()
424 }
425
426 /// Makes a new `DateTime` from the number of non-leap seconds
427 /// since January 1, 1970 0:00:00 UTC (aka "UNIX timestamp")
428 /// and the number of nanoseconds since the last whole non-leap second.
429 ///
430 /// The nanosecond part can exceed 1,000,000,000 in order to represent a
431 /// [leap second](crate::NaiveTime#leap-second-handling), but only when `secs % 60 == 59`.
432 /// (The true "UNIX timestamp" cannot represent a leap second unambiguously.)
433 ///
434 /// # Errors
435 ///
436 /// Returns `MappedLocalTime::None` on out-of-range number of seconds and/or
437 /// invalid nanosecond, otherwise always returns `MappedLocalTime::Single`.
438 ///
439 /// # Example
440 ///
441 /// ```
442 /// use chrono::{TimeZone, Utc};
443 ///
444 /// assert_eq!(Utc.timestamp_opt(1431648000, 0).unwrap().to_string(), "2015-05-15 00:00:00 UTC");
445 /// ```
446 fn timestamp_opt(&self, secs: i64, nsecs: u32) -> MappedLocalTime<DateTime<Self>> {
447 match DateTime::from_timestamp(secs, nsecs) {
448 Some(dt) => MappedLocalTime::Single(self.from_utc_datetime(&dt.naive_utc())),
449 None => MappedLocalTime::None,
450 }
451 }
452
453 /// Makes a new `DateTime` from the number of non-leap milliseconds
454 /// since January 1, 1970 0:00:00 UTC (aka "UNIX timestamp").
455 ///
456 /// Panics on out-of-range number of milliseconds for a non-panicking
457 /// version see [`timestamp_millis_opt`](#method.timestamp_millis_opt).
458 #[deprecated(since = "0.4.23", note = "use `timestamp_millis_opt()` instead")]
459 fn timestamp_millis(&self, millis: i64) -> DateTime<Self> {
460 self.timestamp_millis_opt(millis).unwrap()
461 }
462
463 /// Makes a new `DateTime` from the number of non-leap milliseconds
464 /// since January 1, 1970 0:00:00 UTC (aka "UNIX timestamp").
465 ///
466 ///
467 /// Returns `MappedLocalTime::None` on out-of-range number of milliseconds
468 /// and/or invalid nanosecond, otherwise always returns
469 /// `MappedLocalTime::Single`.
470 ///
471 /// # Example
472 ///
473 /// ```
474 /// use chrono::{MappedLocalTime, TimeZone, Utc};
475 /// match Utc.timestamp_millis_opt(1431648000) {
476 /// MappedLocalTime::Single(dt) => assert_eq!(dt.timestamp(), 1431648),
477 /// _ => panic!("Incorrect timestamp_millis"),
478 /// };
479 /// ```
480 fn timestamp_millis_opt(&self, millis: i64) -> MappedLocalTime<DateTime<Self>> {
481 match DateTime::from_timestamp_millis(millis) {
482 Some(dt) => MappedLocalTime::Single(self.from_utc_datetime(&dt.naive_utc())),
483 None => MappedLocalTime::None,
484 }
485 }
486
487 /// Makes a new `DateTime` from the number of non-leap nanoseconds
488 /// since January 1, 1970 0:00:00 UTC (aka "UNIX timestamp").
489 ///
490 /// Unlike [`timestamp_millis_opt`](#method.timestamp_millis_opt), this never fails.
491 ///
492 /// # Example
493 ///
494 /// ```
495 /// use chrono::{TimeZone, Utc};
496 ///
497 /// assert_eq!(Utc.timestamp_nanos(1431648000000000).timestamp(), 1431648);
498 /// ```
499 fn timestamp_nanos(&self, nanos: i64) -> DateTime<Self> {
500 self.from_utc_datetime(&DateTime::from_timestamp_nanos(nanos).naive_utc())
501 }
502
503 /// Makes a new `DateTime` from the number of non-leap microseconds
504 /// since January 1, 1970 0:00:00 UTC (aka "UNIX timestamp").
505 ///
506 /// # Example
507 ///
508 /// ```
509 /// use chrono::{TimeZone, Utc};
510 ///
511 /// assert_eq!(Utc.timestamp_micros(1431648000000).unwrap().timestamp(), 1431648);
512 /// ```
513 fn timestamp_micros(&self, micros: i64) -> MappedLocalTime<DateTime<Self>> {
514 match DateTime::from_timestamp_micros(micros) {
515 Some(dt) => MappedLocalTime::Single(self.from_utc_datetime(&dt.naive_utc())),
516 None => MappedLocalTime::None,
517 }
518 }
519
520 /// Parses a string with the specified format string and returns a
521 /// `DateTime` with the current offset.
522 ///
523 /// See the [`crate::format::strftime`] module on the
524 /// supported escape sequences.
525 ///
526 /// If the to-be-parsed string includes an offset, it *must* match the
527 /// offset of the TimeZone, otherwise an error will be returned.
528 ///
529 /// See also [`DateTime::parse_from_str`] which gives a [`DateTime`] with
530 /// parsed [`FixedOffset`].
531 ///
532 /// See also [`NaiveDateTime::parse_from_str`] which gives a [`NaiveDateTime`] without
533 /// an offset, but can be converted to a [`DateTime`] with [`NaiveDateTime::and_utc`] or
534 /// [`NaiveDateTime::and_local_timezone`].
535 #[deprecated(
536 since = "0.4.29",
537 note = "use `DateTime::parse_from_str` or `NaiveDateTime::parse_from_str` with `and_utc()` or `and_local_timezone()` instead"
538 )]
539 fn datetime_from_str(&self, s: &str, fmt: &str) -> ParseResult<DateTime<Self>> {
540 let mut parsed = Parsed::new();
541 parse(&mut parsed, s, StrftimeItems::new(fmt))?;
542 parsed.to_datetime_with_timezone(self)
543 }
544
545 /// Reconstructs the time zone from the offset.
546 fn from_offset(offset: &Self::Offset) -> Self;
547
548 /// Creates the offset(s) for given local `NaiveDate` if possible.
549 fn offset_from_local_date(&self, local: &NaiveDate) -> MappedLocalTime<Self::Offset>;
550
551 /// Creates the offset(s) for given local `NaiveDateTime` if possible.
552 fn offset_from_local_datetime(&self, local: &NaiveDateTime) -> MappedLocalTime<Self::Offset>;
553
554 /// Converts the local `NaiveDate` to the timezone-aware `Date` if possible.
555 #[allow(clippy::wrong_self_convention)]
556 #[deprecated(since = "0.4.23", note = "use `from_local_datetime()` instead")]
557 #[allow(deprecated)]
558 fn from_local_date(&self, local: &NaiveDate) -> MappedLocalTime<Date<Self>> {
559 self.offset_from_local_date(local).map(|offset| {
560 // since FixedOffset is within +/- 1 day, the date is never affected
561 Date::from_utc(*local, offset)
562 })
563 }
564
565 /// Converts the local `NaiveDateTime` to the timezone-aware `DateTime` if possible.
566 #[allow(clippy::wrong_self_convention)]
567 fn from_local_datetime(&self, local: &NaiveDateTime) -> MappedLocalTime<DateTime<Self>> {
568 self.offset_from_local_datetime(local).and_then(|off| {
569 local
570 .checked_sub_offset(off.fix())
571 .map(|dt| DateTime::from_naive_utc_and_offset(dt, off))
572 })
573 }
574
575 /// Creates the offset for given UTC `NaiveDate`. This cannot fail.
576 fn offset_from_utc_date(&self, utc: &NaiveDate) -> Self::Offset;
577
578 /// Creates the offset for given UTC `NaiveDateTime`. This cannot fail.
579 fn offset_from_utc_datetime(&self, utc: &NaiveDateTime) -> Self::Offset;
580
581 /// Converts the UTC `NaiveDate` to the local time.
582 /// The UTC is continuous and thus this cannot fail (but can give the duplicate local time).
583 #[allow(clippy::wrong_self_convention)]
584 #[deprecated(since = "0.4.23", note = "use `from_utc_datetime()` instead")]
585 #[allow(deprecated)]
586 fn from_utc_date(&self, utc: &NaiveDate) -> Date<Self> {
587 Date::from_utc(*utc, self.offset_from_utc_date(utc))
588 }
589
590 /// Converts the UTC `NaiveDateTime` to the local time.
591 /// The UTC is continuous and thus this cannot fail (but can give the duplicate local time).
592 #[allow(clippy::wrong_self_convention)]
593 fn from_utc_datetime(&self, utc: &NaiveDateTime) -> DateTime<Self> {
594 DateTime::from_naive_utc_and_offset(*utc, self.offset_from_utc_datetime(utc))
595 }
596}
597
598#[cfg(test)]
599mod tests {
600 use super::*;
601
602 #[test]
603 fn test_fixed_offset_min_max_dates() {
604 for offset_hour in -23..=23 {
605 dbg!(offset_hour);
606 let offset = FixedOffset::east_opt(offset_hour * 60 * 60).unwrap();
607
608 let local_max = offset.from_utc_datetime(&NaiveDateTime::MAX);
609 assert_eq!(local_max.naive_utc(), NaiveDateTime::MAX);
610 let local_min = offset.from_utc_datetime(&NaiveDateTime::MIN);
611 assert_eq!(local_min.naive_utc(), NaiveDateTime::MIN);
612
613 let local_max = offset.from_local_datetime(&NaiveDateTime::MAX);
614 if offset_hour >= 0 {
615 assert_eq!(local_max.unwrap().naive_local(), NaiveDateTime::MAX);
616 } else {
617 assert_eq!(local_max, MappedLocalTime::None);
618 }
619 let local_min = offset.from_local_datetime(&NaiveDateTime::MIN);
620 if offset_hour <= 0 {
621 assert_eq!(local_min.unwrap().naive_local(), NaiveDateTime::MIN);
622 } else {
623 assert_eq!(local_min, MappedLocalTime::None);
624 }
625 }
626 }
627
628 #[test]
629 fn test_negative_millis() {
630 let dt = Utc.timestamp_millis_opt(-1000).unwrap();
631 assert_eq!(dt.to_string(), "1969-12-31 23:59:59 UTC");
632 let dt = Utc.timestamp_millis_opt(-7000).unwrap();
633 assert_eq!(dt.to_string(), "1969-12-31 23:59:53 UTC");
634 let dt = Utc.timestamp_millis_opt(-7001).unwrap();
635 assert_eq!(dt.to_string(), "1969-12-31 23:59:52.999 UTC");
636 let dt = Utc.timestamp_millis_opt(-7003).unwrap();
637 assert_eq!(dt.to_string(), "1969-12-31 23:59:52.997 UTC");
638 let dt = Utc.timestamp_millis_opt(-999).unwrap();
639 assert_eq!(dt.to_string(), "1969-12-31 23:59:59.001 UTC");
640 let dt = Utc.timestamp_millis_opt(-1).unwrap();
641 assert_eq!(dt.to_string(), "1969-12-31 23:59:59.999 UTC");
642 let dt = Utc.timestamp_millis_opt(-60000).unwrap();
643 assert_eq!(dt.to_string(), "1969-12-31 23:59:00 UTC");
644 let dt = Utc.timestamp_millis_opt(-3600000).unwrap();
645 assert_eq!(dt.to_string(), "1969-12-31 23:00:00 UTC");
646
647 for (millis, expected) in &[
648 (-7000, "1969-12-31 23:59:53 UTC"),
649 (-7001, "1969-12-31 23:59:52.999 UTC"),
650 (-7003, "1969-12-31 23:59:52.997 UTC"),
651 ] {
652 match Utc.timestamp_millis_opt(*millis) {
653 MappedLocalTime::Single(dt) => {
654 assert_eq!(dt.to_string(), *expected);
655 }
656 e => panic!("Got {:?} instead of an okay answer", e),
657 }
658 }
659 }
660
661 #[test]
662 fn test_negative_nanos() {
663 let dt = Utc.timestamp_nanos(-1_000_000_000);
664 assert_eq!(dt.to_string(), "1969-12-31 23:59:59 UTC");
665 let dt = Utc.timestamp_nanos(-999_999_999);
666 assert_eq!(dt.to_string(), "1969-12-31 23:59:59.000000001 UTC");
667 let dt = Utc.timestamp_nanos(-1);
668 assert_eq!(dt.to_string(), "1969-12-31 23:59:59.999999999 UTC");
669 let dt = Utc.timestamp_nanos(-60_000_000_000);
670 assert_eq!(dt.to_string(), "1969-12-31 23:59:00 UTC");
671 let dt = Utc.timestamp_nanos(-3_600_000_000_000);
672 assert_eq!(dt.to_string(), "1969-12-31 23:00:00 UTC");
673 }
674
675 #[test]
676 fn test_nanos_never_panics() {
677 Utc.timestamp_nanos(i64::MAX);
678 Utc.timestamp_nanos(i64::default());
679 Utc.timestamp_nanos(i64::MIN);
680 }
681
682 #[test]
683 fn test_negative_micros() {
684 let dt = Utc.timestamp_micros(-1_000_000).unwrap();
685 assert_eq!(dt.to_string(), "1969-12-31 23:59:59 UTC");
686 let dt = Utc.timestamp_micros(-999_999).unwrap();
687 assert_eq!(dt.to_string(), "1969-12-31 23:59:59.000001 UTC");
688 let dt = Utc.timestamp_micros(-1).unwrap();
689 assert_eq!(dt.to_string(), "1969-12-31 23:59:59.999999 UTC");
690 let dt = Utc.timestamp_micros(-60_000_000).unwrap();
691 assert_eq!(dt.to_string(), "1969-12-31 23:59:00 UTC");
692 let dt = Utc.timestamp_micros(-3_600_000_000).unwrap();
693 assert_eq!(dt.to_string(), "1969-12-31 23:00:00 UTC");
694 }
695}
696