gregor/
time_zones.rs

1use core::fmt;
2use super::{NaiveDateTime, DateTime, UnixTimestamp, Month, DayOfTheWeek};
3use num::{div_floor, positive_rem};
4
5pub trait TimeZone {
6    fn from_timestamp(&self, t: UnixTimestamp) -> NaiveDateTime;
7    fn to_timestamp(&self, d: &NaiveDateTime) -> Result<UnixTimestamp, LocalTimeConversionError>;
8}
9
10/// When a time zone makes clock jump forward or back at any instant in time
11/// (for example twice a year with daylight-saving time, a.k.a. summer-time period)
12/// This error is returned when either:
13///
14/// * Clocks went back and this local time occurred at multiple instants in time,
15///   making its interpretation or conversion ambiguous.
16///
17/// * Clocks jumped forward and this local time did not occur.
18///   It does not represent any real instant in time.
19///   It could be argued that a range of local times all represent the same instant,
20///   but this library does not implement the conversion that way.
21#[derive(Eq, PartialEq)]
22pub struct LocalTimeConversionError {
23    /// Make the type opaque to allow for future extensions
24    _private: (),
25}
26
27impl fmt::Debug for LocalTimeConversionError {
28    fn fmt(&self, formatter: &mut fmt::Formatter) -> fmt::Result {
29        write!(formatter, "LocalTimeConversionError")
30    }
31}
32
33/// Implemented for time zones where `LocalTimeConversionError` never occurs,
34/// namely for `Utc` and `FixedOffsetFromUtc`.
35///
36/// Any UTC-offset change in a time zone creates local times that either don’t occur or occur twice.
37/// `TimeZone::to_timestamp` returns `Err(LocalTimeConversionError)` for such local times.
38pub trait UnambiguousTimeZone: TimeZone {
39    fn to_unambiguous_timestamp(&self, d: &NaiveDateTime) -> UnixTimestamp {
40        self.to_timestamp(d).unwrap()
41    }
42}
43
44/// The *Coordinated Universal Time* time time zone.
45#[derive(Debug, Eq, PartialEq, Copy, Clone, Default)]
46pub struct Utc;
47
48impl UnambiguousTimeZone for Utc {}
49
50impl TimeZone for Utc {
51    fn from_timestamp(&self, u: UnixTimestamp) -> NaiveDateTime {
52        let days_since_unix = div_floor(u.0, SECONDS_PER_DAY) as i32;
53        let days = days_since_unix + days_since_d0(1970);
54        let year = div_floor(days * 400, DAYS_PER_400YEARS) as i32;
55        let day_of_the_year = days - days_since_d0(year);
56        let (month, day) = Month::from_day_of_the_year(day_of_the_year, year.into());
57        let hour = positive_rem(div_floor(u.0, SECONDS_PER_HOUR), 24) as u8;
58        let minute = positive_rem(div_floor(u.0, SECONDS_PER_MINUTE), 60) as u8;
59        let second = positive_rem(u.0, 60) as u8;
60        NaiveDateTime::new(year, month, day, hour, minute, second)
61    }
62
63    fn to_timestamp(&self, d: &NaiveDateTime) -> Result<UnixTimestamp, LocalTimeConversionError> {
64        Ok(UnixTimestamp(
65            i64::from(days_since_unix(d)) * SECONDS_PER_DAY
66            + i64::from(d.hour) * SECONDS_PER_HOUR
67            + i64::from(d.minute) * SECONDS_PER_MINUTE
68            + i64::from(d.second)
69        ))
70    }
71}
72
73/// The offset is typically positive east of Greenwich (longitude 0°), negative west.
74///
75/// For example, Japan Standard Time is UTC+09:00:
76///
77/// ```rust
78/// use gregor::FixedOffsetFromUtc;
79/// let jst = FixedOffsetFromUtc::from_hours_and_minutes(9, 0);
80/// ```
81#[derive(Debug, Eq, PartialEq, Copy, Clone, Default)]
82pub struct FixedOffsetFromUtc {
83    seconds_ahead_of_utc: i32,
84}
85
86impl FixedOffsetFromUtc {
87    pub fn from_hours_and_minutes(hours: i32, minutes: i32) -> Self {
88        FixedOffsetFromUtc {
89            seconds_ahead_of_utc: (hours * 60 + minutes) * 60,
90        }
91    }
92}
93
94impl UnambiguousTimeZone for FixedOffsetFromUtc {}
95
96impl TimeZone for FixedOffsetFromUtc {
97    fn from_timestamp(&self, u: UnixTimestamp) -> NaiveDateTime {
98        // When local time is ahead of UTC (positive offset)
99        // that instant happened before midnight UTC
100        // so there are more seconds since then.
101        // (Add the offset rather than subtract it.)
102
103        // Seconds since *this time zone*’s midnight of 1970-01-01.
104        let seconds = u.0 + i64::from(self.seconds_ahead_of_utc);
105
106        // This is not really a Unix timestamp or a UTC date-time,
107        // but the two errors compensate to give a date-time in this time zone.
108        Utc.from_timestamp(UnixTimestamp(seconds))
109    }
110
111    fn to_timestamp(&self, d: &NaiveDateTime) -> Result<UnixTimestamp, LocalTimeConversionError> {
112        // Pretend this is UTC to obtain seconds since *this time zone*’s midnight of 1970-01-01.
113        let seconds = Utc.to_unambiguous_timestamp(d).0;
114
115        // For positives offsets (ahead of UTC) this is earlier in time than UTC midnight
116        // (with more seconds), so *subtract* the offset to make a Unix timestamp.
117        Ok(UnixTimestamp(seconds - i64::from(self.seconds_ahead_of_utc)))
118    }
119}
120
121pub trait DaylightSaving {
122    fn offset_outside_dst(&self) -> FixedOffsetFromUtc;
123    fn offset_during_dst(&self) -> FixedOffsetFromUtc;
124    fn is_in_dst(&self, t: UnixTimestamp) -> bool;
125}
126
127impl<Tz: DaylightSaving> TimeZone for Tz {
128    fn from_timestamp(&self, u: UnixTimestamp) -> NaiveDateTime {
129        let offset = if self.is_in_dst(u) {
130            self.offset_during_dst()
131        } else {
132            self.offset_outside_dst()
133        };
134        offset.from_timestamp(u)
135    }
136
137    fn to_timestamp(&self, d: &NaiveDateTime) -> Result<UnixTimestamp, LocalTimeConversionError> {
138        // The actual timestamp/instant is one of these two:
139        let assuming_outside = self.offset_outside_dst().to_unambiguous_timestamp(d);
140        let assuming_during = self.offset_during_dst().to_unambiguous_timestamp(d);
141
142        // Let’s take Central Europe for example.
143        // When converted to UTC, `assuming_outside` and `assuming_during` respectively
144        // represent date-times one hour and two hours before `d`.
145        // They are one hour apart.
146        //
147        // If both timestamps are in the same DST period (during DST or outside)
148        // then we know for sure which of `assuming_outside` or `assuming_during` is correct.
149        //
150        // If they disagree, that means their one hour span contains a DST change:
151        //
152        // * 1 am UTC is between `d - 2 hours` and `d - 1 hour`
153        // * `d - 2 hours` < 1am UTC, and 1am UTC <= `d - 1 hour`
154        // * `d` < 3 am local time, and 2 am local time <= `d`
155        // * `d` is between 2 am and 3 am local time.
156        //
157        // * In October when clocks go "back", this kind of local time happens twice the same day:
158        //   it’s ambiguous.
159        // * In March when clocks go "forward", that hour is skipped entirely.
160        //   This kind of local time does not exist. This `d` value might come from buggy code.
161        match (self.is_in_dst(assuming_outside), self.is_in_dst(assuming_during)) {
162            (true, true) => Ok(assuming_during),
163            (false, false) => Ok(assuming_outside),
164            _ => Err(LocalTimeConversionError { _private: () }),
165        }
166    }
167}
168
169/// CET (Central European Time) / CEST (Central European Summer Time)
170#[derive(Debug, Eq, PartialEq, Copy, Clone, Default)]
171pub struct CentralEurope;
172
173impl DaylightSaving for CentralEurope {
174    fn offset_outside_dst(&self) -> FixedOffsetFromUtc {
175        FixedOffsetFromUtc::from_hours_and_minutes(1, 0)
176    }
177
178    fn offset_during_dst(&self) -> FixedOffsetFromUtc {
179        FixedOffsetFromUtc::from_hours_and_minutes(2, 0)
180    }
181
182    fn is_in_dst(&self, t: UnixTimestamp) -> bool {
183        use Month::*;
184
185        let d = DateTime::from_timestamp(t, Utc);
186
187        // Directive 2000/84/EC of the European Parliament and of the Council
188        // of 19 January 2001 on summer-time arrangements
189        // http://eur-lex.europa.eu/legal-content/EN/ALL/?uri=CELEX:32000L0084
190        //
191        // > Article 1
192        //
193        // > For the purposes of this Directive "summer-time period"
194        // > shall mean the period of the year
195        // > during which clocks are put forward by 60 minutes compared with the rest of the year.
196        // >
197        // > Article 2
198        // >
199        // > From 2002 onwards, the summer-time period shall begin, in every Member State,
200        // > at 1.00 a.m., Greenwich Mean Time, on the last Sunday in March.
201        // >
202        // > Article 3
203        // >
204        // > From 2002 onwards, the summer-time period shall end, in every Member State,
205        // > at 1.00 a.m., Greenwich Mean Time, on the last Sunday in October.
206        if d.month() < March || d.month() > October {
207            false
208        } else if d.month() > March && d.month() < October {
209            true
210        } else if d.month() == March {
211            !before_last_sunday_1_am(&d)
212        } else if d.month() == October {
213            before_last_sunday_1_am(&d)
214        } else {
215            unreachable!()
216        }
217    }
218}
219
220fn before_last_sunday_1_am(d: &DateTime<Utc>) -> bool {
221    let last_sunday = last_of_the_month(d, DayOfTheWeek::Sunday);
222    d.day() < last_sunday || (
223        d.day() == last_sunday &&
224        (d.hour(), d.minute(), d.second()) < (1, 0, 0)
225    )
226}
227
228fn last_of_the_month(d: &DateTime<Utc>, requested_dow: DayOfTheWeek) -> u8 {
229    let last_day = d.month().length(d.year().into());
230    let last_dow = NaiveDateTime::new(d.year(), d.month(), last_day, 0, 0, 0).day_of_the_week();
231    let difference = i32::from(last_dow.to_iso_number()) - i32::from(requested_dow.to_iso_number());
232    last_day - (positive_rem(difference, 7) as u8)
233}
234
235pub fn days_since_unix(d: &NaiveDateTime) -> i32 {
236    (d.year - 1970) * DAYS_PER_COMMON_YEAR
237    + leap_days_since_y0(d.year) - leap_days_since_y0(1970)
238    + d.month.days_since_january_1st(d.year.into())
239    + i32::from(d.day - 1)
240}
241
242/// How many leap days occurred between January of year 0 and January of the given year
243/// (in Gregorian calendar).
244pub fn leap_days_since_y0(year: i32) -> i32 {
245    if year > 0 {
246        let year = year - 1;  // Don’t include Feb 29 of the given year, if any.
247        // +1 because year 0 is a leap year.
248        ((year / 4) - (year / 100) + (year / 400)) + 1
249    } else {
250        let year = -year;
251        -((year / 4) - (year / 100) + (year / 400))
252    }
253}
254
255/// Days between January 1st of year 0 and January 1st of the given year.
256fn days_since_d0(year: i32) -> i32 {
257    year * DAYS_PER_COMMON_YEAR + leap_days_since_y0(year)
258}
259
260const SECONDS_PER_MINUTE: i64 = 60;
261const SECONDS_PER_HOUR: i64 = SECONDS_PER_MINUTE * 60;
262const SECONDS_PER_DAY: i64 = SECONDS_PER_HOUR * 24;
263
264/// The leap year schedule of the Gregorian calendar cycles every 400 years.
265/// In one cycle, there are:
266///
267/// * 100 years multiple of 4
268/// * 4 years multiple of 100
269/// * 1 year multiple of 400
270const LEAP_DAYS_PER_400YEARS: i32 = 100 - 4 + 1;
271
272const DAYS_PER_COMMON_YEAR: i32 = 365;
273const DAYS_PER_400YEARS: i32 = DAYS_PER_COMMON_YEAR * 400 + LEAP_DAYS_PER_400YEARS;
gregor/time_zones.rs

gregor/
time_zones.rs
