chrono/offset/
fixed.rs

1// This is a part of Chrono.
2// See README.md and LICENSE.txt for details.
3
4//! The time zone which has a fixed offset from UTC.
5
6use core::fmt;
7use core::str::FromStr;
8
9#[cfg(any(feature = "rkyv", feature = "rkyv-16", feature = "rkyv-32", feature = "rkyv-64"))]
10use rkyv::{Archive, Deserialize, Serialize};
11
12use super::{MappedLocalTime, Offset, TimeZone};
13use crate::format::{OUT_OF_RANGE, ParseError, scan};
14use crate::naive::{NaiveDate, NaiveDateTime};
15
16/// The time zone with fixed offset, from UTC-23:59:59 to UTC+23:59:59.
17///
18/// Using the [`TimeZone`](./trait.TimeZone.html) methods
19/// on a `FixedOffset` struct is the preferred way to construct
20/// `DateTime<FixedOffset>` instances. See the [`east_opt`](#method.east_opt) and
21/// [`west_opt`](#method.west_opt) methods for examples.
22#[derive(PartialEq, Eq, Hash, Copy, Clone)]
23#[cfg_attr(
24    any(feature = "rkyv", feature = "rkyv-16", feature = "rkyv-32", feature = "rkyv-64"),
25    derive(Archive, Deserialize, Serialize),
26    archive(compare(PartialEq)),
27    archive_attr(derive(Clone, Copy, PartialEq, Eq, Hash, Debug))
28)]
29#[cfg_attr(feature = "rkyv-validation", archive(check_bytes))]
30pub struct FixedOffset {
31    local_minus_utc: i32,
32}
33
34impl FixedOffset {
35    /// Makes a new `FixedOffset` for the Eastern Hemisphere with given timezone difference.
36    /// The negative `secs` means the Western Hemisphere.
37    ///
38    /// Panics on the out-of-bound `secs`.
39    #[deprecated(since = "0.4.23", note = "use `east_opt()` instead")]
40    #[must_use]
41    pub fn east(secs: i32) -> FixedOffset {
42        FixedOffset::east_opt(secs).expect("FixedOffset::east out of bounds")
43    }
44
45    /// Makes a new `FixedOffset` for the Eastern Hemisphere with given timezone difference.
46    /// The negative `secs` means the Western Hemisphere.
47    ///
48    /// Returns `None` on the out-of-bound `secs`.
49    ///
50    /// # Example
51    ///
52    /// ```
53    /// # #[cfg(feature = "alloc")] {
54    /// use chrono::{FixedOffset, TimeZone};
55    /// let hour = 3600;
56    /// let datetime =
57    ///     FixedOffset::east_opt(5 * hour).unwrap().with_ymd_and_hms(2016, 11, 08, 0, 0, 0).unwrap();
58    /// assert_eq!(&datetime.to_rfc3339(), "2016-11-08T00:00:00+05:00")
59    /// # }
60    /// ```
61    #[must_use]
62    pub const fn east_opt(secs: i32) -> Option<FixedOffset> {
63        if -86_400 < secs && secs < 86_400 {
64            Some(FixedOffset { local_minus_utc: secs })
65        } else {
66            None
67        }
68    }
69
70    /// Makes a new `FixedOffset` for the Western Hemisphere with given timezone difference.
71    /// The negative `secs` means the Eastern Hemisphere.
72    ///
73    /// Panics on the out-of-bound `secs`.
74    #[deprecated(since = "0.4.23", note = "use `west_opt()` instead")]
75    #[must_use]
76    pub fn west(secs: i32) -> FixedOffset {
77        FixedOffset::west_opt(secs).expect("FixedOffset::west out of bounds")
78    }
79
80    /// Makes a new `FixedOffset` for the Western Hemisphere with given timezone difference.
81    /// The negative `secs` means the Eastern Hemisphere.
82    ///
83    /// Returns `None` on the out-of-bound `secs`.
84    ///
85    /// # Example
86    ///
87    /// ```
88    /// # #[cfg(feature = "alloc")] {
89    /// use chrono::{FixedOffset, TimeZone};
90    /// let hour = 3600;
91    /// let datetime =
92    ///     FixedOffset::west_opt(5 * hour).unwrap().with_ymd_and_hms(2016, 11, 08, 0, 0, 0).unwrap();
93    /// assert_eq!(&datetime.to_rfc3339(), "2016-11-08T00:00:00-05:00")
94    /// # }
95    /// ```
96    #[must_use]
97    pub const fn west_opt(secs: i32) -> Option<FixedOffset> {
98        if -86_400 < secs && secs < 86_400 {
99            Some(FixedOffset { local_minus_utc: -secs })
100        } else {
101            None
102        }
103    }
104
105    /// Returns the number of seconds to add to convert from UTC to the local time.
106    #[inline]
107    pub const fn local_minus_utc(&self) -> i32 {
108        self.local_minus_utc
109    }
110
111    /// Returns the number of seconds to add to convert from the local time to UTC.
112    #[inline]
113    pub const fn utc_minus_local(&self) -> i32 {
114        -self.local_minus_utc
115    }
116}
117
118/// Parsing a `str` into a `FixedOffset` uses the format [`%z`](crate::format::strftime).
119impl FromStr for FixedOffset {
120    type Err = ParseError;
121    fn from_str(s: &str) -> Result<Self, Self::Err> {
122        let (_, offset) = scan::timezone_offset(s, scan::colon_or_space, false, false, true)?;
123        Self::east_opt(offset).ok_or(OUT_OF_RANGE)
124    }
125}
126
127impl TimeZone for FixedOffset {
128    type Offset = FixedOffset;
129
130    fn from_offset(offset: &FixedOffset) -> FixedOffset {
131        *offset
132    }
133
134    fn offset_from_local_date(&self, _local: &NaiveDate) -> MappedLocalTime<FixedOffset> {
135        MappedLocalTime::Single(*self)
136    }
137    fn offset_from_local_datetime(&self, _local: &NaiveDateTime) -> MappedLocalTime<FixedOffset> {
138        MappedLocalTime::Single(*self)
139    }
140
141    fn offset_from_utc_date(&self, _utc: &NaiveDate) -> FixedOffset {
142        *self
143    }
144    fn offset_from_utc_datetime(&self, _utc: &NaiveDateTime) -> FixedOffset {
145        *self
146    }
147}
148
149impl Offset for FixedOffset {
150    fn fix(&self) -> FixedOffset {
151        *self
152    }
153}
154
155impl fmt::Debug for FixedOffset {
156    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
157        let offset = self.local_minus_utc;
158        let (sign, offset) = if offset < 0 { ('-', -offset) } else { ('+', offset) };
159        let sec = offset.rem_euclid(60);
160        let mins = offset.div_euclid(60);
161        let min = mins.rem_euclid(60);
162        let hour = mins.div_euclid(60);
163        if sec == 0 {
164            write!(f, "{sign}{hour:02}:{min:02}")
165        } else {
166            write!(f, "{sign}{hour:02}:{min:02}:{sec:02}")
167        }
168    }
169}
170
171impl fmt::Display for FixedOffset {
172    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
173        fmt::Debug::fmt(self, f)
174    }
175}
176
177#[cfg(feature = "defmt")]
178impl defmt::Format for FixedOffset {
179    fn format(&self, f: defmt::Formatter) {
180        let offset = self.local_minus_utc;
181        let (sign, offset) = if offset < 0 { ('-', -offset) } else { ('+', offset) };
182        let sec = offset.rem_euclid(60);
183        let mins = offset.div_euclid(60);
184        let min = mins.rem_euclid(60);
185        let hour = mins.div_euclid(60);
186        if sec == 0 {
187            defmt::write!(f, "{}{:02}:{:02}", sign, hour, min)
188        } else {
189            defmt::write!(f, "{}{:02}:{:02}:{:02}", sign, hour, min, sec)
190        }
191    }
192}
193
194#[cfg(all(feature = "arbitrary", feature = "std"))]
195impl arbitrary::Arbitrary<'_> for FixedOffset {
196    fn arbitrary(u: &mut arbitrary::Unstructured) -> arbitrary::Result<FixedOffset> {
197        let secs = u.int_in_range(-86_399..=86_399)?;
198        let fixed_offset = FixedOffset::east_opt(secs)
199            .expect("Could not generate a valid chrono::FixedOffset. It looks like implementation of Arbitrary for FixedOffset is erroneous.");
200        Ok(fixed_offset)
201    }
202}
203
204#[cfg(test)]
205mod tests {
206    use super::FixedOffset;
207    use crate::offset::TimeZone;
208    use std::str::FromStr;
209
210    #[test]
211    fn test_date_extreme_offset() {
212        // starting from 0.3 we don't have an offset exceeding one day.
213        // this makes everything easier!
214        let offset = FixedOffset::east_opt(86399).unwrap();
215        assert_eq!(
216            format!("{:?}", offset.with_ymd_and_hms(2012, 2, 29, 5, 6, 7).unwrap()),
217            "2012-02-29T05:06:07+23:59:59"
218        );
219        let offset = FixedOffset::east_opt(-86399).unwrap();
220        assert_eq!(
221            format!("{:?}", offset.with_ymd_and_hms(2012, 2, 29, 5, 6, 7).unwrap()),
222            "2012-02-29T05:06:07-23:59:59"
223        );
224        let offset = FixedOffset::west_opt(86399).unwrap();
225        assert_eq!(
226            format!("{:?}", offset.with_ymd_and_hms(2012, 3, 4, 5, 6, 7).unwrap()),
227            "2012-03-04T05:06:07-23:59:59"
228        );
229        let offset = FixedOffset::west_opt(-86399).unwrap();
230        assert_eq!(
231            format!("{:?}", offset.with_ymd_and_hms(2012, 3, 4, 5, 6, 7).unwrap()),
232            "2012-03-04T05:06:07+23:59:59"
233        );
234    }
235
236    #[test]
237    fn test_parse_offset() {
238        let offset = FixedOffset::from_str("-0500").unwrap();
239        assert_eq!(offset.local_minus_utc, -5 * 3600);
240        let offset = FixedOffset::from_str("-08:00").unwrap();
241        assert_eq!(offset.local_minus_utc, -8 * 3600);
242        let offset = FixedOffset::from_str("+06:30").unwrap();
243        assert_eq!(offset.local_minus_utc, (6 * 3600) + 1800);
244    }
245
246    #[test]
247    #[cfg(feature = "rkyv-validation")]
248    fn test_rkyv_validation() {
249        let offset = FixedOffset::from_str("-0500").unwrap();
250        let bytes = rkyv::to_bytes::<_, 4>(&offset).unwrap();
251        assert_eq!(rkyv::from_bytes::<FixedOffset>(&bytes).unwrap(), offset);
252    }
253}
chrono/offset/fixed.rs

chrono/offset/
fixed.rs
