Deprecate methods that have an _opt() alternative

benches/chrono.rs

@@ -35,14 +35,14 @@ fn bench_datetime_from_str(c: &mut Criterion) {
 }
 
 fn bench_datetime_to_rfc2822(c: &mut Criterion) {
-    let pst = FixedOffset::east(8 * 60 * 60);
-    let dt = pst.ymd(2018, 1, 11).and_hms_nano(10, 5, 13, 84_660_000);
+    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();
     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(8 * 60 * 60);
-    let dt = pst.ymd(2018, 1, 11).and_hms_nano(10, 5, 13, 84_660_000);
+    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();
     c.bench_function("bench_datetime_to_rfc3339", |b| b.iter(|| black_box(dt).to_rfc3339()));
 }
 
@@ -90,7 +90,7 @@ fn num_days_from_ce_alt<Date: Datelike>(date: &Date) -> i32 {
 fn bench_num_days_from_ce(c: &mut Criterion) {
     let mut group = c.benchmark_group("num_days_from_ce");
     for year in &[1, 500, 2000, 2019] {
-        let d = NaiveDate::from_ymd(*year, 1, 1);
+        let d = NaiveDate::from_ymd_opt(*year, 1, 1).unwrap();
         group.bench_with_input(BenchmarkId::new("new", year), &d, |b, y| {
             b.iter(|| num_days_from_ce_alt(y))
         });

src/date.rs

@@ -93,6 +93,7 @@ impl<Tz: TimeZone> Date<Tz> {
     /// The offset in the current date is preserved.
     ///
     /// Panics on invalid hour, minute and/or second.
+    #[deprecated(since = "0.4.23", note = "Use and_hms_opt() instead")]
     #[inline]
     pub fn and_hms(&self, hour: u32, min: u32, sec: u32) -> DateTime<Tz> {
         self.and_hms_opt(hour, min, sec).expect("invalid time")
@@ -112,6 +113,7 @@ impl<Tz: TimeZone> Date<Tz> {
     /// The offset in the current date is preserved.
     ///
     /// Panics on invalid hour, minute, second and/or millisecond.
+    #[deprecated(since = "0.4.23", note = "Use and_hms_milli_opt() instead")]
     #[inline]
     pub fn and_hms_milli(&self, hour: u32, min: u32, sec: u32, milli: u32) -> DateTime<Tz> {
         self.and_hms_milli_opt(hour, min, sec, milli).expect("invalid time")
@@ -138,6 +140,7 @@ impl<Tz: TimeZone> Date<Tz> {
     /// The offset in the current date is preserved.
     ///
     /// Panics on invalid hour, minute, second and/or microsecond.
+    #[deprecated(since = "0.4.23", note = "Use and_hms_micro_opt() instead")]
     #[inline]
     pub fn and_hms_micro(&self, hour: u32, min: u32, sec: u32, micro: u32) -> DateTime<Tz> {
         self.and_hms_micro_opt(hour, min, sec, micro).expect("invalid time")
@@ -164,6 +167,7 @@ impl<Tz: TimeZone> Date<Tz> {
     /// The offset in the current date is preserved.
     ///
     /// Panics on invalid hour, minute, second and/or nanosecond.
+    #[deprecated(since = "0.4.23", note = "Use and_hms_nano_opt() instead")]
     #[inline]
     pub fn and_hms_nano(&self, hour: u32, min: u32, sec: u32, nano: u32) -> DateTime<Tz> {
         self.and_hms_nano_opt(hour, min, sec, nano).expect("invalid time")
@@ -188,6 +192,7 @@ impl<Tz: TimeZone> Date<Tz> {
     /// Makes a new `Date` for the next date.
     ///
     /// Panics when `self` is the last representable date.
+    #[deprecated(since = "0.4.23", note = "Use succ_opt() instead")]
     #[inline]
     pub fn succ(&self) -> Date<Tz> {
         self.succ_opt().expect("out of bound")
@@ -204,6 +209,7 @@ impl<Tz: TimeZone> Date<Tz> {
     /// Makes a new `Date` for the prior date.
     ///
     /// Panics when `self` is the first representable date.
+    #[deprecated(since = "0.4.23", note = "Use pred_opt() instead")]
     #[inline]
     pub fn pred(&self) -> Date<Tz> {
         self.pred_opt().expect("out of bound")

src/naive/date.rs

@@ -257,6 +257,7 @@ impl NaiveDate {
     /// assert_eq!(d.weekday(), Weekday::Sat);
     /// assert_eq!(d.num_days_from_ce(), 735671); // days since January 1, 1 CE
     /// ```
+    #[deprecated(since = "0.4.23", note = "use `from_ymd_opt()` instead")]
     pub fn from_ymd(year: i32, month: u32, day: u32) -> NaiveDate {
         NaiveDate::from_ymd_opt(year, month, day).expect("invalid or out-of-range date")
     }
@@ -305,6 +306,7 @@ impl NaiveDate {
     /// assert_eq!(d.weekday(), Weekday::Sat);
     /// assert_eq!(d.num_days_from_ce(), 735671); // days since January 1, 1 CE
     /// ```
+    #[deprecated(since = "0.4.23", note = "use `from_yo_opt()` instead")]
     pub fn from_yo(year: i32, ordinal: u32) -> NaiveDate {
         NaiveDate::from_yo_opt(year, ordinal).expect("invalid or out-of-range date")
     }
@@ -355,6 +357,7 @@ impl NaiveDate {
     /// assert_eq!(d.ordinal(), 73); // day of year
     /// assert_eq!(d.num_days_from_ce(), 735671); // days since January 1, 1 CE
     /// ```
+    #[deprecated(since = "0.4.23", note = "use `from_isoywd_opt()` instead")]
     pub fn from_isoywd(year: i32, week: u32, weekday: Weekday) -> NaiveDate {
         NaiveDate::from_isoywd_opt(year, week, weekday).expect("invalid or out-of-range date")
     }
@@ -477,6 +480,7 @@ impl NaiveDate {
     /// assert_eq!(jd_to_date(2450000), NaiveDate::from_ymd(1995, 10, 9));
     /// assert_eq!(jd_to_date(2451545), NaiveDate::from_ymd(2000, 1, 1));
     /// ```
+    #[deprecated(since = "0.4.23", note = "use `from_num_days_from_ce_opt()` instead")]
     #[inline]
     pub fn from_num_days_from_ce(days: i32) -> NaiveDate {
         NaiveDate::from_num_days_from_ce_opt(days).expect("out-of-range date")
@@ -535,6 +539,7 @@ impl NaiveDate {
     /// assert_eq!(from_weekday_of_month(2018, 8, Weekday::Fri, 4), from_ymd(2018, 8, 24));
     /// assert_eq!(from_weekday_of_month(2018, 8, Weekday::Fri, 5), from_ymd(2018, 8, 31));
     /// ```
+    #[deprecated(since = "0.4.23", note = "use `from_weekday_of_month_opt()` instead")]
     pub fn from_weekday_of_month(year: i32, month: u32, weekday: Weekday, n: u8) -> NaiveDate {
         NaiveDate::from_weekday_of_month_opt(year, month, weekday, n).expect("out-of-range date")
     }
@@ -799,6 +804,7 @@ impl NaiveDate {
     /// assert_eq!(dt.weekday(), Weekday::Wed);
     /// assert_eq!(dt.second(), 56);
     /// ```
+    #[deprecated(since = "0.4.23", note = "use `and_hms_opt()` instead")]
     #[inline]
     pub fn and_hms(&self, hour: u32, min: u32, sec: u32) -> NaiveDateTime {
         self.and_hms_opt(hour, min, sec).expect("invalid time")
@@ -847,6 +853,7 @@ impl NaiveDate {
     /// assert_eq!(dt.second(), 56);
     /// assert_eq!(dt.nanosecond(), 789_000_000);
     /// ```
+    #[deprecated(since = "0.4.23", note = "use `and_hms_milli_opt()` instead")]
     #[inline]
     pub fn and_hms_milli(&self, hour: u32, min: u32, sec: u32, milli: u32) -> NaiveDateTime {
         self.and_hms_milli_opt(hour, min, sec, milli).expect("invalid time")
@@ -903,6 +910,7 @@ impl NaiveDate {
     /// assert_eq!(dt.second(), 56);
     /// assert_eq!(dt.nanosecond(), 789_012_000);
     /// ```
+    #[deprecated(since = "0.4.23", note = "use `and_hms_micro_opt()` instead")]
     #[inline]
     pub fn and_hms_micro(&self, hour: u32, min: u32, sec: u32, micro: u32) -> NaiveDateTime {
         self.and_hms_micro_opt(hour, min, sec, micro).expect("invalid time")
@@ -959,6 +967,7 @@ impl NaiveDate {
     /// assert_eq!(dt.second(), 56);
     /// assert_eq!(dt.nanosecond(), 789_012_345);
     /// ```
+    #[deprecated(since = "0.4.23", note = "use `and_hms_nano_opt()` instead")]
     #[inline]
     pub fn and_hms_nano(&self, hour: u32, min: u32, sec: u32, nano: u32) -> NaiveDateTime {
         self.and_hms_nano_opt(hour, min, sec, nano).expect("invalid time")
@@ -1041,6 +1050,7 @@ impl NaiveDate {
     /// assert_eq!(NaiveDate::from_ymd(2015,  6, 30).succ(), NaiveDate::from_ymd(2015, 7, 1));
     /// assert_eq!(NaiveDate::from_ymd(2015, 12, 31).succ(), NaiveDate::from_ymd(2016, 1, 1));
     /// ```
+    #[deprecated(since = "0.4.23", note = "use `succ_opt()` instead")]
     #[inline]
     pub fn succ(&self) -> NaiveDate {
         self.succ_opt().expect("out of bound")
@@ -1077,6 +1087,7 @@ impl NaiveDate {
     /// assert_eq!(NaiveDate::from_ymd(2015, 6, 1).pred(), NaiveDate::from_ymd(2015,  5, 31));
     /// assert_eq!(NaiveDate::from_ymd(2015, 1, 1).pred(), NaiveDate::from_ymd(2014, 12, 31));
     /// ```
+    #[deprecated(since = "0.4.23", note = "use `pred_opt()` instead")]
     #[inline]
     pub fn pred(&self) -> NaiveDate {
         self.pred_opt().expect("out of bound")

src/naive/datetime/mod.rs

@@ -131,6 +131,7 @@ impl NaiveDateTime {
     /// let dt = NaiveDateTime::from_timestamp(1_000_000_000, 0);
     /// assert_eq!(dt, NaiveDate::from_ymd(2001, 9, 9).and_hms(1, 46, 40));
     /// ```
+    #[deprecated(since = "0.4.23", note = "use `from_timestamp_opt()` instead")]
     #[inline]
     pub fn from_timestamp(secs: i64, nsecs: u32) -> NaiveDateTime {
         let datetime = NaiveDateTime::from_timestamp_opt(secs, nsecs);

src/naive/time/mod.rs

@@ -213,6 +213,7 @@ impl NaiveTime {
     /// assert_eq!(t.second(), 4);
     /// assert_eq!(t.nanosecond(), 0);
     /// ```
+    #[deprecated(since = "0.4.23", note = "use `from_hms_opt()` instead")]
     #[inline]
     pub fn from_hms(hour: u32, min: u32, sec: u32) -> NaiveTime {
         NaiveTime::from_hms_opt(hour, min, sec).expect("invalid time")
@@ -261,6 +262,7 @@ impl NaiveTime {
     /// assert_eq!(t.second(), 4);
     /// assert_eq!(t.nanosecond(), 12_000_000);
     /// ```
+    #[deprecated(since = "0.4.23", note = "use `from_hms_milli_opt()` instead")]
     #[inline]
     pub fn from_hms_milli(hour: u32, min: u32, sec: u32, milli: u32) -> NaiveTime {
         NaiveTime::from_hms_milli_opt(hour, min, sec, milli).expect("invalid time")
@@ -313,6 +315,7 @@ impl NaiveTime {
     /// assert_eq!(t.second(), 4);
     /// assert_eq!(t.nanosecond(), 12_345_000);
     /// ```
+    #[deprecated(since = "0.4.23", note = "use `from_hms_micro_opt()` instead")]
     #[inline]
     pub fn from_hms_micro(hour: u32, min: u32, sec: u32, micro: u32) -> NaiveTime {
         NaiveTime::from_hms_micro_opt(hour, min, sec, micro).expect("invalid time")
@@ -363,6 +366,7 @@ impl NaiveTime {
     /// assert_eq!(t.second(), 4);
     /// assert_eq!(t.nanosecond(), 12_345_678);
     /// ```
+    #[deprecated(since = "0.4.23", note = "use `from_hms_nano_opt()` instead")]
     #[inline]
     pub fn from_hms_nano(hour: u32, min: u32, sec: u32, nano: u32) -> NaiveTime {
         NaiveTime::from_hms_nano_opt(hour, min, sec, nano).expect("invalid time")
@@ -417,6 +421,7 @@ impl NaiveTime {
     /// assert_eq!(t.second(), 4);
     /// assert_eq!(t.nanosecond(), 12_345_678);
     /// ```
+    #[deprecated(since = "0.4.23", note = "use `from_num_seconds_from_midnight_opt()` instead")]
     #[inline]
     pub fn from_num_seconds_from_midnight(secs: u32, nano: u32) -> NaiveTime {
         NaiveTime::from_num_seconds_from_midnight_opt(secs, nano).expect("invalid time")

src/offset/fixed.rs

@@ -43,6 +43,7 @@ impl FixedOffset {
     ///                                           .and_hms(0, 0, 0);
     /// assert_eq!(&datetime.to_rfc3339(), "2016-11-08T00:00:00+05:00")
     /// ```
+    #[deprecated(since = "0.4.23", note = "use `east_opt()` instead")]
     pub fn east(secs: i32) -> FixedOffset {
         FixedOffset::east_opt(secs).expect("FixedOffset::east out of bounds")
     }
@@ -73,6 +74,7 @@ impl FixedOffset {
     ///                                           .and_hms(0, 0, 0);
     /// assert_eq!(&datetime.to_rfc3339(), "2016-11-08T00:00:00-05:00")
     /// ```
+    #[deprecated(since = "0.4.23", note = "use `west_opt()` instead")]
     pub fn west(secs: i32) -> FixedOffset {
         FixedOffset::west_opt(secs).expect("FixedOffset::west out of bounds")
     }

src/offset/mod.rs

@@ -221,6 +221,7 @@ pub trait TimeZone: Sized + Clone {
     ///
     /// assert_eq!(Utc.ymd(2015, 5, 15).to_string(), "2015-05-15UTC");
     /// ```
+    #[deprecated(since = "0.4.23", note = "use `ymd_opt()` instead")]
     fn ymd(&self, year: i32, month: u32, day: u32) -> Date<Self> {
         self.ymd_opt(year, month, day).unwrap()
     }
@@ -263,6 +264,7 @@ pub trait TimeZone: Sized + Clone {
     ///
     /// assert_eq!(Utc.yo(2015, 135).to_string(), "2015-05-15UTC");
     /// ```
+    #[deprecated(since = "0.4.23", note = "use `ymd_opt()` instead")]
     fn yo(&self, year: i32, ordinal: u32) -> Date<Self> {
         self.yo_opt(year, ordinal).unwrap()
     }
@@ -298,6 +300,7 @@ pub trait TimeZone: Sized + Clone {
     ///
     /// assert_eq!(Utc.isoywd(2015, 20, Weekday::Fri).to_string(), "2015-05-15UTC");
     /// ```
+    #[deprecated(since = "0.4.23", note = "use `isoywd_opt()` instead")]
     fn isoywd(&self, year: i32, week: u32, weekday: Weekday) -> Date<Self> {
         self.isoywd_opt(year, week, weekday).unwrap()
     }
@@ -332,6 +335,7 @@ pub trait TimeZone: Sized + Clone {
     ///
     /// assert_eq!(Utc.timestamp(1431648000, 0).to_string(), "2015-05-15 00:00:00 UTC");
     /// ```
+    #[deprecated(since = "0.4.23", note = "use `timestamp_opt()` instead")]
     fn timestamp(&self, secs: i64, nsecs: u32) -> DateTime<Self> {
         self.timestamp_opt(secs, nsecs).unwrap()
     }
@@ -342,6 +346,14 @@ pub trait TimeZone: Sized + Clone {
     ///
     /// Returns `LocalResult::None` on out-of-range number of seconds and/or
     /// invalid nanosecond, otherwise always returns `LocalResult::Single`.
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// use chrono::{Utc, TimeZone};
+    ///
+    /// assert_eq!(Utc.timestamp(1431648000, 0).to_string(), "2015-05-15 00:00:00 UTC");
+    /// ```
     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)),
@@ -362,6 +374,7 @@ pub trait TimeZone: Sized + Clone {
     ///
     /// assert_eq!(Utc.timestamp_millis(1431648000).timestamp(), 1431648);
     /// ```
+    #[deprecated(since = "0.4.23", note = "use `timestamp_millis_opt()` instead")]
     fn timestamp_millis(&self, millis: i64) -> DateTime<Self> {
         self.timestamp_millis_opt(millis).unwrap()
     }

tests/dateutils.rs

@@ -33,11 +33,12 @@ fn verify_against_date_command_local(path: &'static str, dt: NaiveDateTime) {
     // This is used while a decision is made wheter the `date` output needs to
     // be exactly matched, or whether LocalResult::Ambigious should be handled
     // differently
-    match Local.from_local_datetime(&NaiveDate::from_ymd(dt.year(), dt.month(), dt.day()).and_hms(
-        dt.hour(),
-        5,
-        1,
-    )) {
+    match Local.from_local_datetime(
+        &NaiveDate::from_ymd_opt(dt.year(), dt.month(), dt.day())
+            .unwrap()
+            .and_hms_opt(dt.hour(), 5, 1)
+            .unwrap(),
+    ) {
         chrono::LocalResult::Ambiguous(a, b) => assert!(
             format!("{}\n", a) == date_command_str || format!("{}\n", b) == date_command_str
         ),
@@ -63,7 +64,7 @@ fn try_verify_against_date_command() {
         return;
     }
 
-    let mut date = NaiveDate::from_ymd(1975, 1, 1).and_hms(0, 0, 0);
+    let mut date = NaiveDate::from_ymd_opt(1975, 1, 1).unwrap().and_hms_opt(0, 0, 0).unwrap();
 
     while date.year() < 2078 {
         if (1975..=1977).contains(&date.year())