1// This is a part of Chrono.
2// See README.md and LICENSE.txt for details.
3
4//! The UTC (Coordinated Universal Time) time zone.
5
6use core::fmt;
7#[cfg(all(
8 feature = "clock",
9 not(all(
10 target_arch = "wasm32",
11 feature = "wasmbind",
12 not(any(target_os = "emscripten", target_os = "wasi"))
13 ))
14))]
15use std::time::{SystemTime, UNIX_EPOCH};
16
17#[cfg(feature = "rkyv")]
18use rkyv::{Archive, Deserialize, Serialize};
19
20use super::{FixedOffset, LocalResult, Offset, TimeZone};
21use crate::naive::{NaiveDate, NaiveDateTime};
22#[cfg(feature = "clock")]
23#[allow(deprecated)]
24use crate::{Date, DateTime};
25
26/// The UTC time zone. This is the most efficient time zone when you don't need the local time.
27/// It is also used as an offset (which is also a dummy type).
28///
29/// Using the [`TimeZone`](./trait.TimeZone.html) methods
30/// on the UTC struct is the preferred way to construct `DateTime<Utc>`
31/// instances.
32///
33/// # Example
34///
35/// ```
36/// use chrono::{DateTime, TimeZone, NaiveDateTime, Utc};
37///
38/// let dt = DateTime::<Utc>::from_utc(NaiveDateTime::from_timestamp_opt(61, 0).unwrap(), Utc);
39///
40/// assert_eq!(Utc.timestamp_opt(61, 0).unwrap(), dt);
41/// assert_eq!(Utc.with_ymd_and_hms(1970, 1, 1, 0, 1, 1).unwrap(), dt);
42/// ```
43#[derive(Copy, Clone, PartialEq, Eq, Hash)]
44#[cfg_attr(feature = "rkyv", derive(Archive, Deserialize, Serialize))]
45#[cfg_attr(feature = "arbitrary", derive(arbitrary::Arbitrary))]
46pub struct Utc;
47
48#[cfg(feature = "clock")]
49#[cfg_attr(docsrs, doc(cfg(feature = "clock")))]
50impl Utc {
51 /// Returns a `Date` which corresponds to the current date.
52 #[deprecated(
53 since = "0.4.23",
54 note = "use `Utc::now()` instead, potentially with `.date_naive()`"
55 )]
56 #[allow(deprecated)]
57 #[must_use]
58 pub fn today() -> Date<Utc> {
59 Utc::now().date()
60 }
61
62 /// Returns a `DateTime` which corresponds to the current date and time.
63 #[cfg(not(all(
64 target_arch = "wasm32",
65 feature = "wasmbind",
66 not(any(target_os = "emscripten", target_os = "wasi"))
67 )))]
68 #[must_use]
69 pub fn now() -> DateTime<Utc> {
70 let now =
71 SystemTime::now().duration_since(UNIX_EPOCH).expect("system time before Unix epoch");
72 let naive =
73 NaiveDateTime::from_timestamp_opt(now.as_secs() as i64, now.subsec_nanos()).unwrap();
74 DateTime::from_utc(naive, Utc)
75 }
76
77 /// Returns a `DateTime` which corresponds to the current date and time.
78 #[cfg(all(
79 target_arch = "wasm32",
80 feature = "wasmbind",
81 not(any(target_os = "emscripten", target_os = "wasi"))
82 ))]
83 #[must_use]
84 pub fn now() -> DateTime<Utc> {
85 let now = js_sys::Date::new_0();
86 DateTime::<Utc>::from(now)
87 }
88}
89
90impl TimeZone for Utc {
91 type Offset = Utc;
92
93 fn from_offset(_state: &Utc) -> Utc {
94 Utc
95 }
96
97 fn offset_from_local_date(&self, _local: &NaiveDate) -> LocalResult<Utc> {
98 LocalResult::Single(Utc)
99 }
100 fn offset_from_local_datetime(&self, _local: &NaiveDateTime) -> LocalResult<Utc> {
101 LocalResult::Single(Utc)
102 }
103
104 fn offset_from_utc_date(&self, _utc: &NaiveDate) -> Utc {
105 Utc
106 }
107 fn offset_from_utc_datetime(&self, _utc: &NaiveDateTime) -> Utc {
108 Utc
109 }
110}
111
112impl Offset for Utc {
113 fn fix(&self) -> FixedOffset {
114 FixedOffset::east_opt(secs:0).unwrap()
115 }
116}
117
118impl fmt::Debug for Utc {
119 fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
120 write!(f, "Z")
121 }
122}
123
124impl fmt::Display for Utc {
125 fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
126 write!(f, "UTC")
127 }
128}
129