chrono/offset/
mod.rs

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