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
29mod fixed;
30pub use self::fixed::FixedOffset;
31
32#[cfg(feature = "clock")]
33mod local;
34#[cfg(feature = "clock")]
35pub use self::local::Local;
36
37mod utc;
38pub use self::utc::Utc;
39
40/// The conversion result from the local time to the timezone-aware datetime types.
41#[derive(Clone, PartialEq, Debug, Copy, Eq, Hash)]
42pub enum LocalResult<T> {
43 /// Given local time representation is invalid.
44 /// This can occur when, for example, the positive timezone transition.
45 None,
46 /// Given local time representation has a single unique result.
47 Single(T),
48 /// Given local time representation has multiple results and thus ambiguous.
49 /// This can occur when, for example, the negative timezone transition.
50 Ambiguous(T /*min*/, T /*max*/),
51}
52
53impl<T> LocalResult<T> {
54 /// Returns `Some` only when the conversion result is unique, or `None` otherwise.
55 #[must_use]
56 pub fn single(self) -> Option<T> {
57 match self {
58 LocalResult::Single(t) => Some(t),
59 _ => None,
60 }
61 }
62
63 /// Returns `Some` for the earliest possible conversion result, or `None` if none.
64 #[must_use]
65 pub fn earliest(self) -> Option<T> {
66 match self {
67 LocalResult::Single(t) | LocalResult::Ambiguous(t, _) => Some(t),
68 _ => None,
69 }
70 }
71
72 /// Returns `Some` for the latest possible conversion result, or `None` if none.
73 #[must_use]
74 pub fn latest(self) -> Option<T> {
75 match self {
76 LocalResult::Single(t) | LocalResult::Ambiguous(_, t) => Some(t),
77 _ => None,
78 }
79 }
80
81 /// Maps a `LocalResult<T>` into `LocalResult<U>` with given function.
82 #[must_use]
83 pub fn map<U, F: FnMut(T) -> U>(self, mut f: F) -> LocalResult<U> {
84 match self {
85 LocalResult::None => LocalResult::None,
86 LocalResult::Single(v) => LocalResult::Single(f(v)),
87 LocalResult::Ambiguous(min, max) => LocalResult::Ambiguous(f(min), f(max)),
88 }
89 }
90}
91
92#[allow(deprecated)]
93impl<Tz: TimeZone> LocalResult<Date<Tz>> {
94 /// Makes a new `DateTime` from the current date and given `NaiveTime`.
95 /// The offset in the current date is preserved.
96 ///
97 /// Propagates any error. Ambiguous result would be discarded.
98 #[inline]
99 #[must_use]
100 pub fn and_time(self, time: NaiveTime) -> LocalResult<DateTime<Tz>> {
101 match self {
102 LocalResult::Single(d) => {
103 d.and_time(time).map_or(LocalResult::None, LocalResult::Single)
104 }
105 _ => LocalResult::None,
106 }
107 }
108
109 /// Makes a new `DateTime` from the current date, hour, minute and second.
110 /// The offset in the current date is preserved.
111 ///
112 /// Propagates any error. Ambiguous result would be discarded.
113 #[inline]
114 #[must_use]
115 pub fn and_hms_opt(self, hour: u32, min: u32, sec: u32) -> LocalResult<DateTime<Tz>> {
116 match self {
117 LocalResult::Single(d) => {
118 d.and_hms_opt(hour, min, sec).map_or(LocalResult::None, LocalResult::Single)
119 }
120 _ => LocalResult::None,
121 }
122 }
123
124 /// Makes a new `DateTime` from the current date, hour, minute, second and millisecond.
125 /// The millisecond part can exceed 1,000 in order to represent the leap second.
126 /// The offset in the current date is preserved.
127 ///
128 /// Propagates any error. Ambiguous result would be discarded.
129 #[inline]
130 #[must_use]
131 pub fn and_hms_milli_opt(
132 self,
133 hour: u32,
134 min: u32,
135 sec: u32,
136 milli: u32,
137 ) -> LocalResult<DateTime<Tz>> {
138 match self {
139 LocalResult::Single(d) => d
140 .and_hms_milli_opt(hour, min, sec, milli)
141 .map_or(LocalResult::None, LocalResult::Single),
142 _ => LocalResult::None,
143 }
144 }
145
146 /// Makes a new `DateTime` from the current date, hour, minute, second and microsecond.
147 /// The microsecond part can exceed 1,000,000 in order to represent the leap second.
148 /// The offset in the current date is preserved.
149 ///
150 /// Propagates any error. Ambiguous result would be discarded.
151 #[inline]
152 #[must_use]
153 pub fn and_hms_micro_opt(
154 self,
155 hour: u32,
156 min: u32,
157 sec: u32,
158 micro: u32,
159 ) -> LocalResult<DateTime<Tz>> {
160 match self {
161 LocalResult::Single(d) => d
162 .and_hms_micro_opt(hour, min, sec, micro)
163 .map_or(LocalResult::None, LocalResult::Single),
164 _ => LocalResult::None,
165 }
166 }
167
168 /// Makes a new `DateTime` from the current date, hour, minute, second and nanosecond.
169 /// The nanosecond part can exceed 1,000,000,000 in order to represent the leap second.
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_hms_nano_opt(
176 self,
177 hour: u32,
178 min: u32,
179 sec: u32,
180 nano: u32,
181 ) -> LocalResult<DateTime<Tz>> {
182 match self {
183 LocalResult::Single(d) => d
184 .and_hms_nano_opt(hour, min, sec, nano)
185 .map_or(LocalResult::None, LocalResult::Single),
186 _ => LocalResult::None,
187 }
188 }
189}
190
191impl<T: fmt::Debug> LocalResult<T> {
192 /// Returns the single unique conversion result, or panics accordingly.
193 #[must_use]
194 #[track_caller]
195 pub fn unwrap(self) -> T {
196 match self {
197 LocalResult::None => panic!("No such local time"),
198 LocalResult::Single(t: T) => t,
199 LocalResult::Ambiguous(t1: T, t2: T) => {
200 panic!("Ambiguous local time, ranging from {:?} to {:?}", t1, t2)
201 }
202 }
203 }
204}
205
206/// The offset from the local time to UTC.
207pub trait Offset: Sized + Clone + fmt::Debug {
208 /// Returns the fixed offset from UTC to the local time stored.
209 fn fix(&self) -> FixedOffset;
210}
211
212/// The time zone.
213///
214/// The methods here are the primarily constructors for [`Date`](../struct.Date.html) and
215/// [`DateTime`](../struct.DateTime.html) types.
216pub trait TimeZone: Sized + Clone {
217 /// An associated offset type.
218 /// This type is used to store the actual offset in date and time types.
219 /// The original `TimeZone` value can be recovered via `TimeZone::from_offset`.
220 type Offset: Offset;
221
222 /// Make a new `DateTime` from year, month, day, time components and current time zone.
223 ///
224 /// This assumes the proleptic Gregorian calendar, with the year 0 being 1 BCE.
225 ///
226 /// Returns `LocalResult::None` on invalid input data.
227 fn with_ymd_and_hms(
228 &self,
229 year: i32,
230 month: u32,
231 day: u32,
232 hour: u32,
233 min: u32,
234 sec: u32,
235 ) -> LocalResult<DateTime<Self>> {
236 match NaiveDate::from_ymd_opt(year, month, day).and_then(|d| d.and_hms_opt(hour, min, sec))
237 {
238 Some(dt) => self.from_local_datetime(&dt),
239 None => LocalResult::None,
240 }
241 }
242
243 /// Makes a new `Date` from year, month, day and the current time zone.
244 /// This assumes the proleptic Gregorian calendar, with the year 0 being 1 BCE.
245 ///
246 /// The time zone normally does not affect the date (unless it is between UTC-24 and UTC+24),
247 /// but it will propagate to the `DateTime` values constructed via this date.
248 ///
249 /// Panics on the out-of-range date, invalid month and/or day.
250 #[deprecated(since = "0.4.23", note = "use `with_ymd_and_hms()` instead")]
251 #[allow(deprecated)]
252 fn ymd(&self, year: i32, month: u32, day: u32) -> Date<Self> {
253 self.ymd_opt(year, month, day).unwrap()
254 }
255
256 /// Makes a new `Date` from year, month, day and the current time zone.
257 /// This assumes the proleptic Gregorian calendar, with the year 0 being 1 BCE.
258 ///
259 /// The time zone normally does not affect the date (unless it is between UTC-24 and UTC+24),
260 /// but it will propagate to the `DateTime` values constructed via this date.
261 ///
262 /// Returns `None` on the out-of-range date, invalid month and/or day.
263 #[deprecated(since = "0.4.23", note = "use `with_ymd_and_hms()` instead")]
264 #[allow(deprecated)]
265 fn ymd_opt(&self, year: i32, month: u32, day: u32) -> LocalResult<Date<Self>> {
266 match NaiveDate::from_ymd_opt(year, month, day) {
267 Some(d) => self.from_local_date(&d),
268 None => LocalResult::None,
269 }
270 }
271
272 /// Makes a new `Date` from year, day of year (DOY or "ordinal") and the current time zone.
273 /// This assumes the proleptic Gregorian calendar, with the year 0 being 1 BCE.
274 ///
275 /// The time zone normally does not affect the date (unless it is between UTC-24 and UTC+24),
276 /// but it will propagate to the `DateTime` values constructed via this date.
277 ///
278 /// Panics on the out-of-range date and/or invalid DOY.
279 #[deprecated(
280 since = "0.4.23",
281 note = "use `from_local_datetime()` with a `NaiveDateTime` instead"
282 )]
283 #[allow(deprecated)]
284 fn yo(&self, year: i32, ordinal: u32) -> Date<Self> {
285 self.yo_opt(year, ordinal).unwrap()
286 }
287
288 /// Makes a new `Date` from year, day of year (DOY or "ordinal") and the current time zone.
289 /// This assumes the proleptic Gregorian calendar, with the year 0 being 1 BCE.
290 ///
291 /// The time zone normally does not affect the date (unless it is between UTC-24 and UTC+24),
292 /// but it will propagate to the `DateTime` values constructed via this date.
293 ///
294 /// Returns `None` on the out-of-range date and/or invalid DOY.
295 #[deprecated(
296 since = "0.4.23",
297 note = "use `from_local_datetime()` with a `NaiveDateTime` instead"
298 )]
299 #[allow(deprecated)]
300 fn yo_opt(&self, year: i32, ordinal: u32) -> LocalResult<Date<Self>> {
301 match NaiveDate::from_yo_opt(year, ordinal) {
302 Some(d) => self.from_local_date(&d),
303 None => LocalResult::None,
304 }
305 }
306
307 /// Makes a new `Date` from ISO week date (year and week number), day of the week (DOW) and
308 /// the current time zone.
309 /// This assumes the proleptic Gregorian calendar, with the year 0 being 1 BCE.
310 /// The resulting `Date` may have a different year from the input year.
311 ///
312 /// The time zone normally does not affect the date (unless it is between UTC-24 and UTC+24),
313 /// but it will propagate to the `DateTime` values constructed via this date.
314 ///
315 /// Panics on the out-of-range date and/or invalid week number.
316 #[deprecated(
317 since = "0.4.23",
318 note = "use `from_local_datetime()` with a `NaiveDateTime` instead"
319 )]
320 #[allow(deprecated)]
321 fn isoywd(&self, year: i32, week: u32, weekday: Weekday) -> Date<Self> {
322 self.isoywd_opt(year, week, weekday).unwrap()
323 }
324
325 /// Makes a new `Date` from ISO week date (year and week number), day of the week (DOW) and
326 /// the current time zone.
327 /// This assumes the proleptic Gregorian calendar, with the year 0 being 1 BCE.
328 /// The resulting `Date` may have a different year from the input year.
329 ///
330 /// The time zone normally does not affect the date (unless it is between UTC-24 and UTC+24),
331 /// but it will propagate to the `DateTime` values constructed via this date.
332 ///
333 /// Returns `None` on the out-of-range date and/or invalid week number.
334 #[deprecated(
335 since = "0.4.23",
336 note = "use `from_local_datetime()` with a `NaiveDateTime` instead"
337 )]
338 #[allow(deprecated)]
339 fn isoywd_opt(&self, year: i32, week: u32, weekday: Weekday) -> LocalResult<Date<Self>> {
340 match NaiveDate::from_isoywd_opt(year, week, weekday) {
341 Some(d) => self.from_local_date(&d),
342 None => LocalResult::None,
343 }
344 }
345
346 /// Makes a new `DateTime` from the number of non-leap seconds
347 /// since January 1, 1970 0:00:00 UTC (aka "UNIX timestamp")
348 /// and the number of nanoseconds since the last whole non-leap second.
349 ///
350 /// Panics on the out-of-range number of seconds and/or invalid nanosecond,
351 /// for a non-panicking version see [`timestamp_opt`](#method.timestamp_opt).
352 #[deprecated(since = "0.4.23", note = "use `timestamp_opt()` instead")]
353 fn timestamp(&self, secs: i64, nsecs: u32) -> DateTime<Self> {
354 self.timestamp_opt(secs, nsecs).unwrap()
355 }
356
357 /// Makes a new `DateTime` from the number of non-leap seconds
358 /// since January 1, 1970 0:00:00 UTC (aka "UNIX timestamp")
359 /// and the number of nanoseconds since the last whole non-leap second.
360 ///
361 /// Returns `LocalResult::None` on out-of-range number of seconds and/or
362 /// invalid nanosecond, otherwise always returns `LocalResult::Single`.
363 ///
364 /// # Example
365 ///
366 /// ```
367 /// use chrono::{Utc, TimeZone};
368 ///
369 /// assert_eq!(Utc.timestamp_opt(1431648000, 0).unwrap().to_string(), "2015-05-15 00:00:00 UTC");
370 /// ```
371 fn timestamp_opt(&self, secs: i64, nsecs: u32) -> LocalResult<DateTime<Self>> {
372 match NaiveDateTime::from_timestamp_opt(secs, nsecs) {
373 Some(dt) => LocalResult::Single(self.from_utc_datetime(&dt)),
374 None => LocalResult::None,
375 }
376 }
377
378 /// Makes a new `DateTime` from the number of non-leap milliseconds
379 /// since January 1, 1970 0:00:00 UTC (aka "UNIX timestamp").
380 ///
381 /// Panics on out-of-range number of milliseconds for a non-panicking
382 /// version see [`timestamp_millis_opt`](#method.timestamp_millis_opt).
383 #[deprecated(since = "0.4.23", note = "use `timestamp_millis_opt()` instead")]
384 fn timestamp_millis(&self, millis: i64) -> DateTime<Self> {
385 self.timestamp_millis_opt(millis).unwrap()
386 }
387
388 /// Makes a new `DateTime` from the number of non-leap milliseconds
389 /// since January 1, 1970 0:00:00 UTC (aka "UNIX timestamp").
390 ///
391 ///
392 /// Returns `LocalResult::None` on out-of-range number of milliseconds
393 /// and/or invalid nanosecond, otherwise always returns
394 /// `LocalResult::Single`.
395 ///
396 /// # Example
397 ///
398 /// ```
399 /// use chrono::{Utc, TimeZone, LocalResult};
400 /// match Utc.timestamp_millis_opt(1431648000) {
401 /// LocalResult::Single(dt) => assert_eq!(dt.timestamp(), 1431648),
402 /// _ => panic!("Incorrect timestamp_millis"),
403 /// };
404 /// ```
405 fn timestamp_millis_opt(&self, millis: i64) -> LocalResult<DateTime<Self>> {
406 let (mut secs, mut millis) = (millis / 1000, millis % 1000);
407 if millis < 0 {
408 secs -= 1;
409 millis += 1000;
410 }
411 self.timestamp_opt(secs, millis as u32 * 1_000_000)
412 }
413
414 /// Makes a new `DateTime` from the number of non-leap nanoseconds
415 /// since January 1, 1970 0:00:00 UTC (aka "UNIX timestamp").
416 ///
417 /// Unlike [`timestamp_millis`](#method.timestamp_millis), this never
418 /// panics.
419 ///
420 /// # Example
421 ///
422 /// ```
423 /// use chrono::{Utc, TimeZone};
424 ///
425 /// assert_eq!(Utc.timestamp_nanos(1431648000000000).timestamp(), 1431648);
426 /// ```
427 fn timestamp_nanos(&self, nanos: i64) -> DateTime<Self> {
428 let (mut secs, mut nanos) = (nanos / 1_000_000_000, nanos % 1_000_000_000);
429 if nanos < 0 {
430 secs -= 1;
431 nanos += 1_000_000_000;
432 }
433 self.timestamp_opt(secs, nanos as u32).unwrap()
434 }
435
436 /// Parses a string with the specified format string and returns a
437 /// `DateTime` with the current offset.
438 ///
439 /// See the [`crate::format::strftime`] module on the
440 /// supported escape sequences.
441 ///
442 /// If the to-be-parsed string includes an offset, it *must* match the
443 /// offset of the TimeZone, otherwise an error will be returned.
444 ///
445 /// See also [`DateTime::parse_from_str`] which gives a [`DateTime`] with
446 /// parsed [`FixedOffset`].
447 fn datetime_from_str(&self, s: &str, fmt: &str) -> ParseResult<DateTime<Self>> {
448 let mut parsed = Parsed::new();
449 parse(&mut parsed, s, StrftimeItems::new(fmt))?;
450 parsed.to_datetime_with_timezone(self)
451 }
452
453 /// Reconstructs the time zone from the offset.
454 fn from_offset(offset: &Self::Offset) -> Self;
455
456 /// Creates the offset(s) for given local `NaiveDate` if possible.
457 fn offset_from_local_date(&self, local: &NaiveDate) -> LocalResult<Self::Offset>;
458
459 /// Creates the offset(s) for given local `NaiveDateTime` if possible.
460 fn offset_from_local_datetime(&self, local: &NaiveDateTime) -> LocalResult<Self::Offset>;
461
462 /// Converts the local `NaiveDate` to the timezone-aware `Date` if possible.
463 #[allow(clippy::wrong_self_convention)]
464 #[deprecated(since = "0.4.23", note = "use `from_local_datetime()` instead")]
465 #[allow(deprecated)]
466 fn from_local_date(&self, local: &NaiveDate) -> LocalResult<Date<Self>> {
467 self.offset_from_local_date(local).map(|offset| {
468 // since FixedOffset is within +/- 1 day, the date is never affected
469 Date::from_utc(*local, offset)
470 })
471 }
472
473 /// Converts the local `NaiveDateTime` to the timezone-aware `DateTime` if possible.
474 #[allow(clippy::wrong_self_convention)]
475 fn from_local_datetime(&self, local: &NaiveDateTime) -> LocalResult<DateTime<Self>> {
476 self.offset_from_local_datetime(local)
477 .map(|offset| DateTime::from_utc(*local - offset.fix(), offset))
478 }
479
480 /// Creates the offset for given UTC `NaiveDate`. This cannot fail.
481 fn offset_from_utc_date(&self, utc: &NaiveDate) -> Self::Offset;
482
483 /// Creates the offset for given UTC `NaiveDateTime`. This cannot fail.
484 fn offset_from_utc_datetime(&self, utc: &NaiveDateTime) -> Self::Offset;
485
486 /// Converts the UTC `NaiveDate` to the local time.
487 /// The UTC is continuous and thus this cannot fail (but can give the duplicate local time).
488 #[allow(clippy::wrong_self_convention)]
489 #[deprecated(since = "0.4.23", note = "use `from_utc_datetime()` instead")]
490 #[allow(deprecated)]
491 fn from_utc_date(&self, utc: &NaiveDate) -> Date<Self> {
492 Date::from_utc(*utc, self.offset_from_utc_date(utc))
493 }
494
495 /// Converts the UTC `NaiveDateTime` to the local time.
496 /// The UTC is continuous and thus this cannot fail (but can give the duplicate local time).
497 #[allow(clippy::wrong_self_convention)]
498 fn from_utc_datetime(&self, utc: &NaiveDateTime) -> DateTime<Self> {
499 DateTime::from_utc(*utc, self.offset_from_utc_datetime(utc))
500 }
501}
502
503#[cfg(test)]
504mod tests {
505 use super::*;
506
507 #[test]
508 fn test_negative_millis() {
509 let dt = Utc.timestamp_millis_opt(-1000).unwrap();
510 assert_eq!(dt.to_string(), "1969-12-31 23:59:59 UTC");
511 let dt = Utc.timestamp_millis_opt(-7000).unwrap();
512 assert_eq!(dt.to_string(), "1969-12-31 23:59:53 UTC");
513 let dt = Utc.timestamp_millis_opt(-7001).unwrap();
514 assert_eq!(dt.to_string(), "1969-12-31 23:59:52.999 UTC");
515 let dt = Utc.timestamp_millis_opt(-7003).unwrap();
516 assert_eq!(dt.to_string(), "1969-12-31 23:59:52.997 UTC");
517 let dt = Utc.timestamp_millis_opt(-999).unwrap();
518 assert_eq!(dt.to_string(), "1969-12-31 23:59:59.001 UTC");
519 let dt = Utc.timestamp_millis_opt(-1).unwrap();
520 assert_eq!(dt.to_string(), "1969-12-31 23:59:59.999 UTC");
521 let dt = Utc.timestamp_millis_opt(-60000).unwrap();
522 assert_eq!(dt.to_string(), "1969-12-31 23:59:00 UTC");
523 let dt = Utc.timestamp_millis_opt(-3600000).unwrap();
524 assert_eq!(dt.to_string(), "1969-12-31 23:00:00 UTC");
525
526 for (millis, expected) in &[
527 (-7000, "1969-12-31 23:59:53 UTC"),
528 (-7001, "1969-12-31 23:59:52.999 UTC"),
529 (-7003, "1969-12-31 23:59:52.997 UTC"),
530 ] {
531 match Utc.timestamp_millis_opt(*millis) {
532 LocalResult::Single(dt) => {
533 assert_eq!(dt.to_string(), *expected);
534 }
535 e => panic!("Got {:?} instead of an okay answer", e),
536 }
537 }
538 }
539
540 #[test]
541 fn test_negative_nanos() {
542 let dt = Utc.timestamp_nanos(-1_000_000_000);
543 assert_eq!(dt.to_string(), "1969-12-31 23:59:59 UTC");
544 let dt = Utc.timestamp_nanos(-999_999_999);
545 assert_eq!(dt.to_string(), "1969-12-31 23:59:59.000000001 UTC");
546 let dt = Utc.timestamp_nanos(-1);
547 assert_eq!(dt.to_string(), "1969-12-31 23:59:59.999999999 UTC");
548 let dt = Utc.timestamp_nanos(-60_000_000_000);
549 assert_eq!(dt.to_string(), "1969-12-31 23:59:00 UTC");
550 let dt = Utc.timestamp_nanos(-3_600_000_000_000);
551 assert_eq!(dt.to_string(), "1969-12-31 23:00:00 UTC");
552 }
553
554 #[test]
555 fn test_nanos_never_panics() {
556 Utc.timestamp_nanos(i64::max_value());
557 Utc.timestamp_nanos(i64::default());
558 Utc.timestamp_nanos(i64::min_value());
559 }
560}
561