| // This is a part of Chrono. |
| // See README.md and LICENSE.txt for details. |
| |
| //! The time zone, which calculates offsets from the local time to UTC. |
| //! |
| //! There are four operations provided by the `TimeZone` trait: |
| //! |
| //! 1. Converting the local `NaiveDateTime` to `DateTime<Tz>` |
| //! 2. Converting the UTC `NaiveDateTime` to `DateTime<Tz>` |
| //! 3. Converting `DateTime<Tz>` to the local `NaiveDateTime` |
| //! 4. Constructing `DateTime<Tz>` objects from various offsets |
| //! |
| //! 1 is used for constructors. 2 is used for the `with_timezone` method of date and time types. |
| //! 3 is used for other methods, e.g. `year()` or `format()`, and provided by an associated type |
| //! which implements `Offset` (which then passed to `TimeZone` for actual implementations). |
| //! Technically speaking `TimeZone` has a total knowledge about given timescale, |
| //! but `Offset` is used as a cache to avoid the repeated conversion |
| //! and provides implementations for 1 and 3. |
| //! An `TimeZone` instance can be reconstructed from the corresponding `Offset` instance. |
| |
| use std::fmt; |
| |
| use Weekday; |
| use naive::{NaiveDate, NaiveTime, NaiveDateTime}; |
| use {Date, DateTime}; |
| use format::{parse, Parsed, ParseResult, StrftimeItems}; |
| |
| /// The conversion result from the local time to the timezone-aware datetime types. |
| #[derive(Clone, PartialEq, Debug)] |
| pub enum LocalResult<T> { |
| /// Given local time representation is invalid. |
| /// This can occur when, for example, the positive timezone transition. |
| None, |
| /// Given local time representation has a single unique result. |
| Single(T), |
| /// Given local time representation has multiple results and thus ambiguous. |
| /// This can occur when, for example, the negative timezone transition. |
| Ambiguous(T /*min*/, T /*max*/), |
| } |
| |
| impl<T> LocalResult<T> { |
| /// Returns `Some` only when the conversion result is unique, or `None` otherwise. |
| pub fn single(self) -> Option<T> { |
| match self { LocalResult::Single(t) => Some(t), _ => None } |
| } |
| |
| /// Returns `Some` for the earliest possible conversion result, or `None` if none. |
| pub fn earliest(self) -> Option<T> { |
| match self { LocalResult::Single(t) | LocalResult::Ambiguous(t,_) => Some(t), _ => None } |
| } |
| |
| /// Returns `Some` for the latest possible conversion result, or `None` if none. |
| pub fn latest(self) -> Option<T> { |
| match self { LocalResult::Single(t) | LocalResult::Ambiguous(_,t) => Some(t), _ => None } |
| } |
| |
| /// Maps a `LocalResult<T>` into `LocalResult<U>` with given function. |
| pub fn map<U, F: FnMut(T) -> U>(self, mut f: F) -> LocalResult<U> { |
| match self { |
| LocalResult::None => LocalResult::None, |
| LocalResult::Single(v) => LocalResult::Single(f(v)), |
| LocalResult::Ambiguous(min, max) => LocalResult::Ambiguous(f(min), f(max)), |
| } |
| } |
| } |
| |
| impl<Tz: TimeZone> LocalResult<Date<Tz>> { |
| /// Makes a new `DateTime` from the current date and given `NaiveTime`. |
| /// The offset in the current date is preserved. |
| /// |
| /// Propagates any error. Ambiguous result would be discarded. |
| #[inline] |
| pub fn and_time(self, time: NaiveTime) -> LocalResult<DateTime<Tz>> { |
| match self { |
| LocalResult::Single(d) => d.and_time(time) |
| .map_or(LocalResult::None, LocalResult::Single), |
| _ => LocalResult::None, |
| } |
| } |
| |
| /// Makes a new `DateTime` from the current date, hour, minute and second. |
| /// The offset in the current date is preserved. |
| /// |
| /// Propagates any error. Ambiguous result would be discarded. |
| #[inline] |
| pub fn and_hms_opt(self, hour: u32, min: u32, sec: u32) -> LocalResult<DateTime<Tz>> { |
| match self { |
| LocalResult::Single(d) => d.and_hms_opt(hour, min, sec) |
| .map_or(LocalResult::None, LocalResult::Single), |
| _ => LocalResult::None, |
| } |
| } |
| |
| /// Makes a new `DateTime` from the current date, hour, minute, second and millisecond. |
| /// The millisecond part can exceed 1,000 in order to represent the leap second. |
| /// The offset in the current date is preserved. |
| /// |
| /// Propagates any error. Ambiguous result would be discarded. |
| #[inline] |
| pub fn and_hms_milli_opt(self, hour: u32, min: u32, sec: u32, |
| milli: u32) -> LocalResult<DateTime<Tz>> { |
| match self { |
| LocalResult::Single(d) => d.and_hms_milli_opt(hour, min, sec, milli) |
| .map_or(LocalResult::None, LocalResult::Single), |
| _ => LocalResult::None, |
| } |
| } |
| |
| /// Makes a new `DateTime` from the current date, hour, minute, second and microsecond. |
| /// The microsecond part can exceed 1,000,000 in order to represent the leap second. |
| /// The offset in the current date is preserved. |
| /// |
| /// Propagates any error. Ambiguous result would be discarded. |
| #[inline] |
| pub fn and_hms_micro_opt(self, hour: u32, min: u32, sec: u32, |
| micro: u32) -> LocalResult<DateTime<Tz>> { |
| match self { |
| LocalResult::Single(d) => d.and_hms_micro_opt(hour, min, sec, micro) |
| .map_or(LocalResult::None, LocalResult::Single), |
| _ => LocalResult::None, |
| } |
| } |
| |
| /// Makes a new `DateTime` from the current date, hour, minute, second and nanosecond. |
| /// The nanosecond part can exceed 1,000,000,000 in order to represent the leap second. |
| /// The offset in the current date is preserved. |
| /// |
| /// Propagates any error. Ambiguous result would be discarded. |
| #[inline] |
| pub fn and_hms_nano_opt(self, hour: u32, min: u32, sec: u32, |
| nano: u32) -> LocalResult<DateTime<Tz>> { |
| match self { |
| LocalResult::Single(d) => d.and_hms_nano_opt(hour, min, sec, nano) |
| .map_or(LocalResult::None, LocalResult::Single), |
| _ => LocalResult::None, |
| } |
| } |
| |
| } |
| |
| impl<T: fmt::Debug> LocalResult<T> { |
| /// Returns the single unique conversion result, or panics accordingly. |
| pub fn unwrap(self) -> T { |
| match self { |
| LocalResult::None => panic!("No such local time"), |
| LocalResult::Single(t) => t, |
| LocalResult::Ambiguous(t1,t2) => { |
| panic!("Ambiguous local time, ranging from {:?} to {:?}", t1, t2) |
| } |
| } |
| } |
| } |
| |
| /// The offset from the local time to UTC. |
| pub trait Offset: Sized + Clone + fmt::Debug { |
| /// Returns the fixed offset from UTC to the local time stored. |
| fn fix(&self) -> FixedOffset; |
| } |
| |
| /// The time zone. |
| /// |
| /// The methods here are the primarily constructors for [`Date`](../struct.Date.html) and |
| /// [`DateTime`](../struct.DateTime.html) types. |
| pub trait TimeZone: Sized + Clone { |
| /// An associated offset type. |
| /// This type is used to store the actual offset in date and time types. |
| /// The original `TimeZone` value can be recovered via `TimeZone::from_offset`. |
| type Offset: Offset; |
| |
| /// Makes a new `Date` from year, month, day and the current time zone. |
| /// This assumes the proleptic Gregorian calendar, with the year 0 being 1 BCE. |
| /// |
| /// The time zone normally does not affect the date (unless it is between UTC-24 and UTC+24), |
| /// but it will propagate to the `DateTime` values constructed via this date. |
| /// |
| /// Panics on the out-of-range date, invalid month and/or day. |
| /// |
| /// # Example |
| /// |
| /// ~~~~ |
| /// use chrono::{Utc, TimeZone}; |
| /// |
| /// assert_eq!(Utc.ymd(2015, 5, 15).to_string(), "2015-05-15UTC"); |
| /// ~~~~ |
| fn ymd(&self, year: i32, month: u32, day: u32) -> Date<Self> { |
| self.ymd_opt(year, month, day).unwrap() |
| } |
| |
| /// Makes a new `Date` from year, month, day and the current time zone. |
| /// This assumes the proleptic Gregorian calendar, with the year 0 being 1 BCE. |
| /// |
| /// The time zone normally does not affect the date (unless it is between UTC-24 and UTC+24), |
| /// but it will propagate to the `DateTime` values constructed via this date. |
| /// |
| /// Returns `None` on the out-of-range date, invalid month and/or day. |
| /// |
| /// # Example |
| /// |
| /// ~~~~ |
| /// use chrono::{Utc, LocalResult, TimeZone}; |
| /// |
| /// assert_eq!(Utc.ymd_opt(2015, 5, 15).unwrap().to_string(), "2015-05-15UTC"); |
| /// assert_eq!(Utc.ymd_opt(2000, 0, 0), LocalResult::None); |
| /// ~~~~ |
| fn ymd_opt(&self, year: i32, month: u32, day: u32) -> LocalResult<Date<Self>> { |
| match NaiveDate::from_ymd_opt(year, month, day) { |
| Some(d) => self.from_local_date(&d), |
| None => LocalResult::None, |
| } |
| } |
| |
| /// Makes a new `Date` from year, day of year (DOY or "ordinal") and the current time zone. |
| /// This assumes the proleptic Gregorian calendar, with the year 0 being 1 BCE. |
| /// |
| /// The time zone normally does not affect the date (unless it is between UTC-24 and UTC+24), |
| /// but it will propagate to the `DateTime` values constructed via this date. |
| /// |
| /// Panics on the out-of-range date and/or invalid DOY. |
| /// |
| /// # Example |
| /// |
| /// ~~~~ |
| /// use chrono::{Utc, TimeZone}; |
| /// |
| /// assert_eq!(Utc.yo(2015, 135).to_string(), "2015-05-15UTC"); |
| /// ~~~~ |
| fn yo(&self, year: i32, ordinal: u32) -> Date<Self> { |
| self.yo_opt(year, ordinal).unwrap() |
| } |
| |
| /// Makes a new `Date` from year, day of year (DOY or "ordinal") and the current time zone. |
| /// This assumes the proleptic Gregorian calendar, with the year 0 being 1 BCE. |
| /// |
| /// The time zone normally does not affect the date (unless it is between UTC-24 and UTC+24), |
| /// but it will propagate to the `DateTime` values constructed via this date. |
| /// |
| /// Returns `None` on the out-of-range date and/or invalid DOY. |
| fn yo_opt(&self, year: i32, ordinal: u32) -> LocalResult<Date<Self>> { |
| match NaiveDate::from_yo_opt(year, ordinal) { |
| Some(d) => self.from_local_date(&d), |
| None => LocalResult::None, |
| } |
| } |
| |
| /// Makes a new `Date` from ISO week date (year and week number), day of the week (DOW) and |
| /// the current time zone. |
| /// This assumes the proleptic Gregorian calendar, with the year 0 being 1 BCE. |
| /// The resulting `Date` may have a different year from the input year. |
| /// |
| /// The time zone normally does not affect the date (unless it is between UTC-24 and UTC+24), |
| /// but it will propagate to the `DateTime` values constructed via this date. |
| /// |
| /// Panics on the out-of-range date and/or invalid week number. |
| /// |
| /// # Example |
| /// |
| /// ~~~~ |
| /// use chrono::{Utc, Weekday, TimeZone}; |
| /// |
| /// assert_eq!(Utc.isoywd(2015, 20, Weekday::Fri).to_string(), "2015-05-15UTC"); |
| /// ~~~~ |
| fn isoywd(&self, year: i32, week: u32, weekday: Weekday) -> Date<Self> { |
| self.isoywd_opt(year, week, weekday).unwrap() |
| } |
| |
| /// Makes a new `Date` from ISO week date (year and week number), day of the week (DOW) and |
| /// the current time zone. |
| /// This assumes the proleptic Gregorian calendar, with the year 0 being 1 BCE. |
| /// The resulting `Date` may have a different year from the input year. |
| /// |
| /// The time zone normally does not affect the date (unless it is between UTC-24 and UTC+24), |
| /// but it will propagate to the `DateTime` values constructed via this date. |
| /// |
| /// Returns `None` on the out-of-range date and/or invalid week number. |
| fn isoywd_opt(&self, year: i32, week: u32, weekday: Weekday) -> LocalResult<Date<Self>> { |
| match NaiveDate::from_isoywd_opt(year, week, weekday) { |
| Some(d) => self.from_local_date(&d), |
| None => LocalResult::None, |
| } |
| } |
| |
| /// Makes a new `DateTime` from the number of non-leap seconds |
| /// since January 1, 1970 0:00:00 UTC (aka "UNIX timestamp") |
| /// and the number of nanoseconds since the last whole non-leap second. |
| /// |
| /// Panics on the out-of-range number of seconds and/or invalid nanosecond, |
| /// for a non-panicking version see [`timestamp_opt`](#method.timestamp_opt). |
| /// |
| /// # Example |
| /// |
| /// ~~~~ |
| /// use chrono::{Utc, TimeZone}; |
| /// |
| /// assert_eq!(Utc.timestamp(1431648000, 0).to_string(), "2015-05-15 00:00:00 UTC"); |
| /// ~~~~ |
| fn timestamp(&self, secs: i64, nsecs: u32) -> DateTime<Self> { |
| self.timestamp_opt(secs, nsecs).unwrap() |
| } |
| |
| /// Makes a new `DateTime` from the number of non-leap seconds |
| /// since January 1, 1970 0:00:00 UTC (aka "UNIX timestamp") |
| /// and the number of nanoseconds since the last whole non-leap second. |
| /// |
| /// Returns `LocalResult::None` on out-of-range number of seconds and/or |
| /// invalid nanosecond, otherwise always returns `LocalResult::Single`. |
| fn timestamp_opt(&self, secs: i64, nsecs: u32) -> LocalResult<DateTime<Self>> { |
| match NaiveDateTime::from_timestamp_opt(secs, nsecs) { |
| Some(dt) => LocalResult::Single(self.from_utc_datetime(&dt)), |
| None => LocalResult::None, |
| } |
| } |
| |
| /// Makes a new `DateTime` from the number of non-leap milliseconds |
| /// since January 1, 1970 0:00:00 UTC (aka "UNIX timestamp"). |
| /// |
| /// Panics on out-of-range number of milliseconds for a non-panicking |
| /// version see [`timestamp_millis_opt`](#method.timestamp_millis_opt). |
| /// |
| /// # Example |
| /// |
| /// ~~~~ |
| /// use chrono::{Utc, TimeZone}; |
| /// |
| /// assert_eq!(Utc.timestamp_millis(1431648000).timestamp(), 1431648); |
| /// ~~~~ |
| fn timestamp_millis(&self, millis: i64) -> DateTime<Self> { |
| self.timestamp_millis_opt(millis).unwrap() |
| } |
| |
| /// Makes a new `DateTime` from the number of non-leap milliseconds |
| /// since January 1, 1970 0:00:00 UTC (aka "UNIX timestamp"). |
| /// |
| /// |
| /// Returns `LocalResult::None` on out-of-range number of milliseconds |
| /// and/or invalid nanosecond, otherwise always returns |
| /// `LocalResult::Single`. |
| /// |
| /// # Example |
| /// |
| /// ~~~~ |
| /// use chrono::{Utc, TimeZone, LocalResult}; |
| /// match Utc.timestamp_millis_opt(1431648000) { |
| /// LocalResult::Single(dt) => assert_eq!(dt.timestamp(), 1431648), |
| /// _ => panic!("Incorrect timestamp_millis"), |
| /// }; |
| /// ~~~~ |
| fn timestamp_millis_opt(&self, millis: i64) -> LocalResult<DateTime<Self>> { |
| let (secs, millis) = (millis / 1000, millis % 1000); |
| self.timestamp_opt(secs, millis as u32 * 1_000_000) |
| } |
| |
| /// Parses a string with the specified format string and |
| /// returns a `DateTime` with the current offset. |
| /// See the [`format::strftime` module](../format/strftime/index.html) |
| /// on the supported escape sequences. |
| /// |
| /// If the format does not include offsets, the current offset is assumed; |
| /// otherwise the input should have a matching UTC offset. |
| /// |
| /// See also `DateTime::parse_from_str` which gives a local `DateTime` |
| /// with parsed `FixedOffset`. |
| fn datetime_from_str(&self, s: &str, fmt: &str) -> ParseResult<DateTime<Self>> { |
| let mut parsed = Parsed::new(); |
| try!(parse(&mut parsed, s, StrftimeItems::new(fmt))); |
| parsed.to_datetime_with_timezone(self) |
| } |
| |
| /// Reconstructs the time zone from the offset. |
| fn from_offset(offset: &Self::Offset) -> Self; |
| |
| /// Creates the offset(s) for given local `NaiveDate` if possible. |
| fn offset_from_local_date(&self, local: &NaiveDate) -> LocalResult<Self::Offset>; |
| |
| /// Creates the offset(s) for given local `NaiveDateTime` if possible. |
| fn offset_from_local_datetime(&self, local: &NaiveDateTime) -> LocalResult<Self::Offset>; |
| |
| /// Converts the local `NaiveDate` to the timezone-aware `Date` if possible. |
| fn from_local_date(&self, local: &NaiveDate) -> LocalResult<Date<Self>> { |
| self.offset_from_local_date(local).map(|offset| { |
| // since FixedOffset is within +/- 1 day, the date is never affected |
| Date::from_utc(*local, offset) |
| }) |
| } |
| |
| /// Converts the local `NaiveDateTime` to the timezone-aware `DateTime` if possible. |
| fn from_local_datetime(&self, local: &NaiveDateTime) -> LocalResult<DateTime<Self>> { |
| self.offset_from_local_datetime(local).map(|offset| { |
| DateTime::from_utc(*local - offset.fix(), offset) |
| }) |
| } |
| |
| /// Creates the offset for given UTC `NaiveDate`. This cannot fail. |
| fn offset_from_utc_date(&self, utc: &NaiveDate) -> Self::Offset; |
| |
| /// Creates the offset for given UTC `NaiveDateTime`. This cannot fail. |
| fn offset_from_utc_datetime(&self, utc: &NaiveDateTime) -> Self::Offset; |
| |
| /// Converts the UTC `NaiveDate` to the local time. |
| /// The UTC is continuous and thus this cannot fail (but can give the duplicate local time). |
| fn from_utc_date(&self, utc: &NaiveDate) -> Date<Self> { |
| Date::from_utc(*utc, self.offset_from_utc_date(utc)) |
| } |
| |
| /// Converts the UTC `NaiveDateTime` to the local time. |
| /// The UTC is continuous and thus this cannot fail (but can give the duplicate local time). |
| fn from_utc_datetime(&self, utc: &NaiveDateTime) -> DateTime<Self> { |
| DateTime::from_utc(*utc, self.offset_from_utc_datetime(utc)) |
| } |
| } |
| |
| mod utc; |
| mod fixed; |
| #[cfg(feature="clock")] |
| mod local; |
| |
| pub use self::utc::Utc; |
| pub use self::fixed::FixedOffset; |
| #[cfg(feature="clock")] |
| pub use self::local::Local; |