diff --git a/src/date.rs b/src/date.rs index 7c89491a..a12f383a 100644 --- a/src/date.rs +++ b/src/date.rs @@ -21,24 +21,31 @@ use {Datelike, Weekday}; /// ISO 8601 calendar date with time zone. /// -/// This type should be considered ambiguous at best, -/// due to the inherent lack of precision required for the time zone resolution. -/// For serialization and deserialization uses, it is best to use `NaiveDate` instead. +/// You almost certainly want to be using a [`NaiveDate`] instead of this type. +/// +/// This type primarily exists to aid in the construction of DateTimes that +/// have a timezone by way of the [`TimeZone`] datelike constructors (e.g. +/// [`TimeZone::ymd`]). +/// +/// This type should be considered ambiguous at best, due to the inherent lack +/// of precision required for the time zone resolution. +/// /// There are some guarantees on the usage of `Date`: /// -/// - If properly constructed via `TimeZone::ymd` and others without an error, +/// - If properly constructed via [`TimeZone::ymd`] and others without an error, /// the corresponding local date should exist for at least a moment. /// (It may still have a gap from the offset changes.) /// -/// - The `TimeZone` is free to assign *any* `Offset` to the local date, -/// as long as that offset did occur in given day. +/// - The `TimeZone` is free to assign *any* [`Offset`](::offset::Offset) to the +/// local date, as long as that offset did occur in given day. +/// /// For example, if `2015-03-08T01:59-08:00` is followed by `2015-03-08T03:00-07:00`, /// it may produce either `2015-03-08-08:00` or `2015-03-08-07:00` /// but *not* `2015-03-08+00:00` and others. /// -/// - Once constructed as a full `DateTime`, -/// `DateTime::date` and other associated methods should return those for the original `Date`. -/// For example, if `dt = tz.ymd(y,m,d).hms(h,n,s)` were valid, `dt.date() == tz.ymd(y,m,d)`. +/// - Once constructed as a full `DateTime`, [`DateTime::date`] and other associated +/// methods should return those for the original `Date`. For example, if `dt = +/// tz.ymd(y,m,d).hms(h,n,s)` were valid, `dt.date() == tz.ymd(y,m,d)`. /// /// - The date is timezone-agnostic up to one day (i.e. practically always), /// so the local date and UTC date should be equal for most cases diff --git a/src/datetime.rs b/src/datetime.rs index 72d177dc..0d68eb84 100644 --- a/src/datetime.rs +++ b/src/datetime.rs @@ -23,7 +23,7 @@ use format::DelayedFormat; use format::Locale; use format::{parse, ParseError, ParseResult, Parsed, StrftimeItems}; use format::{Fixed, Item}; -use naive::{self, IsoWeek, NaiveDateTime, NaiveTime}; +use naive::{self, IsoWeek, NaiveDate, NaiveDateTime, NaiveTime}; #[cfg(feature = "clock")] use offset::Local; use offset::{FixedOffset, Offset, TimeZone, Utc}; @@ -96,12 +96,45 @@ impl DateTime { DateTime { datetime: datetime, offset: offset } } - /// Retrieves a date component. + /// Retrieves a date component + /// + /// Unless you are immediately planning on turning this into a `DateTime` + /// with the same Timezone you should use the + /// [`date_naive`](DateTime::date_naive) method. + /// + /// ``` + /// use chrono::prelude::*; + /// + /// let date: Date = Utc.ymd(2020, 1, 1); + /// let dt: DateTime = date.and_hms(0, 0, 0); + /// + /// assert_eq!(dt.date(), date); + /// + /// assert_eq!(dt.date().and_hms(1, 1, 1), date.and_hms(1, 1, 1)); + /// ``` #[inline] pub fn date(&self) -> Date { Date::from_utc(self.naive_local().date(), self.offset.clone()) } + /// Retrieves the Date without an associated timezone + /// + /// [`NaiveDate`] is a more well-defined type, and has more traits implemented on it, + /// so should be preferred to [`Date`] any time you truly want to operate on Dates. + /// + /// ``` + /// use chrono::prelude::*; + /// + /// let date: DateTime = Utc.ymd(2020, 1, 1).and_hms(0, 0, 0); + /// let other: DateTime = FixedOffset::east(23).ymd(2020, 1, 1).and_hms(0, 0, 0); + /// assert_eq!(date.date_naive(), other.date_naive()); + /// ``` + #[inline] + pub fn date_naive(&self) -> NaiveDate { + let local = self.naive_local(); + NaiveDate::from_ymd(local.year(), local.month(), local.day()) + } + /// Retrieves a time component. /// Unlike `date`, this is not associated to the time zone. #[inline]