diff --git a/src/naive/mod.rs b/src/naive/mod.rs index ca76c0a3..cdbe85bc 100644 --- a/src/naive/mod.rs +++ b/src/naive/mod.rs @@ -60,13 +60,37 @@ impl NaiveWeek { #[inline] #[must_use] pub const fn first_day(&self) -> NaiveDate { + expect(self.checked_first_day(), "first weekday out of range for `NaiveDate`") + } + + /// Returns a date representing the first day of the week or + /// `None` if the date is out of `NaiveDate`'s range + /// (more than ca. 262,000 years away from common era). + /// + /// # Examples + /// + /// ``` + /// use chrono::{NaiveDate, Weekday}; + /// + /// let date = NaiveDate::MIN; + /// let week = date.week(Weekday::Mon); + /// if let Some(first_day) = week.checked_first_day() { + /// assert!(first_day == date); + /// } else { + /// // error handling code + /// return; + /// }; + /// ``` + #[inline] + #[must_use] + pub const fn checked_first_day(&self) -> Option { let start = self.start.num_days_from_monday() as i32; let ref_day = self.date.weekday().num_days_from_monday() as i32; // Calculate the number of days to subtract from `self.date`. // Do not construct an intermediate date beyond `self.date`, because that may be out of // range if `date` is close to `NaiveDate::MAX`. let days = start - ref_day - if start > ref_day { 7 } else { 0 }; - expect(self.date.add_days(days), "first weekday out of range for `NaiveDate`") + self.date.add_days(days) } /// Returns a date representing the last day of the week.