Deprecate usage of the Date<Tz> type

benches/chrono.rs

@@ -36,13 +36,27 @@ fn bench_datetime_from_str(c: &mut Criterion) {
 
 fn bench_datetime_to_rfc2822(c: &mut Criterion) {
     let pst = FixedOffset::east_opt(8 * 60 * 60).unwrap();
-    let dt = pst.ymd_opt(2018, 1, 11).unwrap().and_hms_nano_opt(10, 5, 13, 84_660_000).unwrap();
+    let dt = pst
+        .from_local_datetime(
+            &NaiveDate::from_ymd_opt(2018, 1, 11)
+                .unwrap()
+                .and_hms_nano_opt(10, 5, 13, 84_660_000)
+                .unwrap(),
+        )
+        .unwrap();
     c.bench_function("bench_datetime_to_rfc2822", |b| b.iter(|| black_box(dt).to_rfc2822()));
 }
 
 fn bench_datetime_to_rfc3339(c: &mut Criterion) {
     let pst = FixedOffset::east_opt(8 * 60 * 60).unwrap();
-    let dt = pst.ymd_opt(2018, 1, 11).and_hms_nano_opt(10, 5, 13, 84_660_000).unwrap();
+    let dt = pst
+        .from_local_datetime(
+            &NaiveDate::from_ymd_opt(2018, 1, 11)
+                .unwrap()
+                .and_hms_nano_opt(10, 5, 13, 84_660_000)
+                .unwrap(),
+        )
+        .unwrap();
     c.bench_function("bench_datetime_to_rfc3339", |b| b.iter(|| black_box(dt).to_rfc3339()));
 }
 

ci/core-test/src/lib.rs

@@ -3,5 +3,5 @@
 use chrono::{TimeZone, Utc};
 
 pub fn create_time() {
-    let _ = Utc.ymd_opt(2019, 1, 1).unwrap().and_hms_opt(0, 0, 0).unwrap();
+    let _ = Utc.with_ymd_and_hms(2019, 1, 1, 0, 0, 0).unwrap();
 }

src/date.rs

@@ -2,6 +2,7 @@
 // See README.md and LICENSE.txt for details.
 
 //! ISO 8601 calendar date with time zone.
+#![allow(deprecated)]
 
 #[cfg(any(feature = "alloc", feature = "std", test))]
 use core::borrow::Borrow;
@@ -53,6 +54,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> {
@@ -288,15 +290,7 @@ impl<Tz: TimeZone> Date<Tz> {
 
     /// Returns the number of whole years from the given `base` until `self`.
     pub fn years_since(&self, base: Self) -> Option<u32> {
-        let mut years = self.year() - base.year();
-        if (self.month(), self.day()) < (base.month(), base.day()) {
-            years -= 1;
-        }
-
-        match years >= 0 {
-            true => Some(years as u32),
-            false => None,
-        }
+        self.date.years_since(base.date)
     }
 
     /// The minimum possible `Date`.
@@ -332,15 +326,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]