Merge pull request #270 from asayers/from_ymwd

Construct a NaiveDate by specifying eg. "the 2nd Friday of March 2017"

CHANGELOG.md

@@ -96,6 +96,12 @@ Versions with only mechanical changes will be omitted from the following list.
 * Doc improvements -- improve README CI verification, external links
 * winapi upgrade to 0.3
 
+## Unreleased
+
+### Features
+
+* Added `NaiveDate::from_weekday_of_month{,_opt}` for getting eg. the 2nd Friday of March 2017.
+
 ## 0.4.5
 
 ### Features

src/naive/date.rs

@@ -411,6 +411,55 @@ impl NaiveDate {
                            Of::new(ordinal, flags))
     }
 
+    /// Makes a new `NaiveDate` by counting the number of occurances of a particular day-of-week
+    /// since the beginning of the given month.  For instance, if you want the 2nd Friday of March
+    /// 2017, you would use `NaiveDate::from_weekday_of_month(2017, 3, Weekday::Fri, 2)`.
+    ///
+    /// # Panics
+    ///
+    /// The resulting `NaiveDate` is guaranteed to be in `month`.  If `n` is larger than the number
+    /// of `weekday` in `month` (eg. the 6th Friday of March 2017) then this function will panic.
+    ///
+    /// `n` is 1-indexed.  Passing `n=0` will cause a panic.
+    ///
+    /// # Example
+    ///
+    /// ~~~~
+    /// use chrono::{NaiveDate, Weekday};
+    ///
+    /// let from_weekday_of_month = NaiveDate::from_weekday_of_month;
+    /// let from_ymd = NaiveDate::from_ymd;
+    ///
+    /// assert_eq!(from_weekday_of_month(2018, 8, Weekday::Wed, 1), from_ymd(2018, 8, 1));
+    /// assert_eq!(from_weekday_of_month(2018, 8, Weekday::Fri, 1), from_ymd(2018, 8, 3));
+    /// assert_eq!(from_weekday_of_month(2018, 8, Weekday::Tue, 2), from_ymd(2018, 8, 14));
+    /// 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));
+    /// ~~~~
+    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")
+    }
+
+    /// Makes a new `NaiveDate` by counting the number of occurances of a particular day-of-week
+    /// since the beginning of the given month.  For instance, if you want the 2nd Friday of March
+    /// 2017, you would use `NaiveDate::from_weekday_of_month(2017, 3, Weekday::Fri, 2)`.  `n` is 1-indexed.
+    ///
+    /// ~~~~
+    /// use chrono::{NaiveDate, Weekday};
+    /// assert_eq!(NaiveDate::from_weekday_of_month_opt(2017, 3, Weekday::Fri, 2),
+    ///            NaiveDate::from_ymd_opt(2017, 3, 10))
+    /// ~~~~
+    ///
+    /// Returns `None` if `n` out-of-range; ie. if `n` is larger than the number of `weekday` in
+    /// `month` (eg. the 6th Friday of March 2017), or if `n == 0`.
+    pub fn from_weekday_of_month_opt(year: i32, month: u32, weekday: Weekday, n: u8) -> Option<NaiveDate> {
+        if n == 0 { return None; }
+        let first = NaiveDate::from_ymd(year, month, 1).weekday();
+        let first_to_dow = (7 + weekday.number_from_monday() - first.number_from_monday()) % 7;
+        let day = (u32::from(n) - 1) * 7 + first_to_dow + 1;
+        NaiveDate::from_ymd_opt(year, month, day)
+    }
+
     /// Parses a string with the specified format string and returns a new `NaiveDate`.
     /// See the [`format::strftime` module](../format/strftime/index.html)
     /// on the supported escape sequences.
@@ -1837,6 +1886,24 @@ mod tests {
         assert_eq!(from_ndays_from_ce(MAX_DATE.num_days_from_ce() + 1), None);
     }
 
+    #[test]
+    fn test_date_from_weekday_of_month_opt() {
+        let ymwd = |y,m,w,n| NaiveDate::from_weekday_of_month_opt(y,m,w,n);
+        assert_eq!(ymwd(2018, 8, Weekday::Tue, 0), None);
+        assert_eq!(ymwd(2018, 8, Weekday::Wed, 1), Some(NaiveDate::from_ymd(2018, 8, 1)));
+        assert_eq!(ymwd(2018, 8, Weekday::Thu, 1), Some(NaiveDate::from_ymd(2018, 8, 2)));
+        assert_eq!(ymwd(2018, 8, Weekday::Sun, 1), Some(NaiveDate::from_ymd(2018, 8, 5)));
+        assert_eq!(ymwd(2018, 8, Weekday::Mon, 1), Some(NaiveDate::from_ymd(2018, 8, 6)));
+        assert_eq!(ymwd(2018, 8, Weekday::Tue, 1), Some(NaiveDate::from_ymd(2018, 8, 7)));
+        assert_eq!(ymwd(2018, 8, Weekday::Wed, 2), Some(NaiveDate::from_ymd(2018, 8, 8)));
+        assert_eq!(ymwd(2018, 8, Weekday::Sun, 2), Some(NaiveDate::from_ymd(2018, 8, 12)));
+        assert_eq!(ymwd(2018, 8, Weekday::Thu, 3), Some(NaiveDate::from_ymd(2018, 8, 16)));
+        assert_eq!(ymwd(2018, 8, Weekday::Thu, 4), Some(NaiveDate::from_ymd(2018, 8, 23)));
+        assert_eq!(ymwd(2018, 8, Weekday::Thu, 5), Some(NaiveDate::from_ymd(2018, 8, 30)));
+        assert_eq!(ymwd(2018, 8, Weekday::Fri, 5), Some(NaiveDate::from_ymd(2018, 8, 31)));
+        assert_eq!(ymwd(2018, 8, Weekday::Sat, 5), None);
+    }
+
     #[test]
     fn test_date_fields() {
         fn check(year: i32, month: u32, day: u32, ordinal: u32) {