Deprecate usage of the Date<Tz> type

src/date.rs

@@ -53,6 +53,7 @@ use crate::{Datelike, Weekday};
 /// - 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
 ///   even though the raw calculation between `NaiveDate` and `Duration` may not.
+#[deprecated(since = "0.4.23", note = "Use `NaiveDate` or `DateTime<Tz>` instead")]
 #[derive(Clone)]
 #[cfg_attr(feature = "rkyv", derive(Archive, Deserialize, Serialize))]
 pub struct Date<Tz: TimeZone> {
@@ -324,15 +325,6 @@ where
     /// Formats the date with the specified format string.
     /// See the [`crate::format::strftime`] module
     /// on the supported escape sequences.
-    ///
-    /// # Example
-    /// ```rust
-    /// use chrono::prelude::*;
-    ///
-    /// let date_time: Date<Utc> = Utc.ymd_opt(2017, 04, 02).unwrap();
-    /// let formatted = format!("{}", date_time.format("%d/%m/%Y"));
-    /// assert_eq!(formatted, "02/04/2017");
-    /// ```
     #[cfg(any(feature = "alloc", feature = "std", test))]
     #[cfg_attr(docsrs, doc(cfg(any(feature = "alloc", feature = "std"))))]
     #[inline]

src/datetime/mod.rs

@@ -152,18 +152,9 @@ impl<Tz: TimeZone> DateTime<Tz> {
     /// 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> = Utc.ymd_opt(2020, 1, 1).unwrap();
-    /// let dt: DateTime<Utc> = date.and_hms_opt(0, 0, 0).unwrap();
-    ///
-    /// assert_eq!(dt.date(), date);
-    ///
-    /// assert_eq!(dt.date().and_hms_opt(1, 1, 1).unwrap(), date.and_hms_opt(1, 1, 1).unwrap());
-    /// ```
     #[inline]
+    #[deprecated(since = "0.4.23", note = "Use `date_naive()` instead")]
+    #[allow(deprecated)]
     pub fn date(&self) -> Date<Tz> {
         Date::from_utc(self.naive_local().date(), self.offset.clone())
     }

src/offset/local/mod.rs

@@ -57,6 +57,8 @@ pub struct Local;
 
 impl Local {
     /// Returns a `Date` which corresponds to the current date.
+    #[deprecated(since = "0.4.23", note = "use `Local::now()` instead")]
+    #[allow(deprecated)]
     pub fn today() -> Date<Local> {
         Local::now().date()
     }
@@ -97,6 +99,7 @@ impl TimeZone for Local {
     }
 
     // they are easier to define in terms of the finished date and time unlike other offsets
+    #[allow(deprecated)]
     fn offset_from_local_date(&self, local: &NaiveDate) -> LocalResult<FixedOffset> {
         self.from_local_date(local).map(|date| *date.offset())
     }

src/offset/mod.rs

@@ -234,7 +234,8 @@ pub trait TimeZone: Sized + Clone {
     /// but it will propagate to the `DateTime` values constructed via this date.
     ///
     /// Panics on the out-of-range date, invalid month and/or day.
-    #[deprecated(since = "0.4.23", note = "use `ymd_opt()` instead")]
+    #[deprecated(since = "0.4.23", note = "use `with_ymd_and_hms()` instead")]
+    #[allow(deprecated)]
     fn ymd(&self, year: i32, month: u32, day: u32) -> Date<Self> {
         self.ymd_opt(year, month, day).unwrap()
     }
@@ -246,15 +247,8 @@ pub trait TimeZone: Sized + Clone {
     /// 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);
-    /// ```
+    #[deprecated(since = "0.4.23", note = "use `with_ymd_and_hms()` instead")]
+    #[allow(deprecated)]
     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),
@@ -269,7 +263,11 @@ pub trait TimeZone: Sized + Clone {
     /// but it will propagate to the `DateTime` values constructed via this date.
     ///
     /// Panics on the out-of-range date and/or invalid DOY.
-    #[deprecated(since = "0.4.23", note = "use `ymd_opt()` instead")]
+    #[deprecated(
+        since = "0.4.23",
+        note = "use `from_local_datetime()` with a `NaiveDateTime` instead"
+    )]
+    #[allow(deprecated)]
     fn yo(&self, year: i32, ordinal: u32) -> Date<Self> {
         self.yo_opt(year, ordinal).unwrap()
     }
@@ -281,14 +279,11 @@ pub trait TimeZone: Sized + Clone {
     /// but it will propagate to the `DateTime` values constructed via this date.
     ///
     /// Returns `None` on the out-of-range date and/or invalid DOY.
-    ///
-    /// # Example
-    ///
-    /// ```
-    /// use chrono::{Utc, TimeZone};
-    ///
-    /// assert_eq!(Utc.yo_opt(2015, 135).unwrap().to_string(), "2015-05-15UTC");
-    /// ```
+    #[deprecated(
+        since = "0.4.23",
+        note = "use `from_local_datetime()` with a `NaiveDateTime` instead"
+    )]
+    #[allow(deprecated)]
     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),
@@ -305,7 +300,11 @@ pub trait TimeZone: Sized + Clone {
     /// but it will propagate to the `DateTime` values constructed via this date.
     ///
     /// Panics on the out-of-range date and/or invalid week number.
-    #[deprecated(since = "0.4.23", note = "use `isoywd_opt()` instead")]
+    #[deprecated(
+        since = "0.4.23",
+        note = "use `from_local_datetime()` with a `NaiveDateTime` instead"
+    )]
+    #[allow(deprecated)]
     fn isoywd(&self, year: i32, week: u32, weekday: Weekday) -> Date<Self> {
         self.isoywd_opt(year, week, weekday).unwrap()
     }
@@ -319,14 +318,11 @@ pub trait TimeZone: Sized + Clone {
     /// 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.
-    ///
-    /// # Example
-    ///
-    /// ```
-    /// use chrono::{Utc, Weekday, TimeZone};
-    ///
-    /// assert_eq!(Utc.isoywd_opt(2015, 20, Weekday::Fri).unwrap().to_string(), "2015-05-15UTC");
-    /// ```
+    #[deprecated(
+        since = "0.4.23",
+        note = "use `from_local_datetime()` with a `NaiveDateTime` instead"
+    )]
+    #[allow(deprecated)]
     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),
@@ -452,6 +448,8 @@ pub trait TimeZone: Sized + Clone {
 
     /// Converts the local `NaiveDate` to the timezone-aware `Date` if possible.
     #[allow(clippy::wrong_self_convention)]
+    #[deprecated(since = "0.4.23", note = "use `from_local_datetime()` instead")]
+    #[allow(deprecated)]
     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
@@ -475,6 +473,8 @@ pub trait TimeZone: Sized + Clone {
     /// Converts the UTC `NaiveDate` to the local time.
     /// The UTC is continuous and thus this cannot fail (but can give the duplicate local time).
     #[allow(clippy::wrong_self_convention)]
+    #[deprecated(since = "0.4.23", note = "use `from_utc_datetime()` instead")]
+    #[allow(deprecated)]
     fn from_utc_date(&self, utc: &NaiveDate) -> Date<Self> {
         Date::from_utc(*utc, self.offset_from_utc_date(utc))
     }

src/offset/utc.rs

@@ -48,6 +48,11 @@ pub struct Utc;
 #[cfg_attr(docsrs, doc(cfg(feature = "clock")))]
 impl Utc {
     /// Returns a `Date` which corresponds to the current date.
+    #[deprecated(
+        since = "0.4.23",
+        note = "use `Utc::now()` instead, potentially with `.date_naive()`"
+    )]
+    #[allow(deprecated)]
     pub fn today() -> Date<Utc> {
         Utc::now().date()
     }