diff --git a/CHANGELOG.md b/CHANGELOG.md index f6f3b64..7035c8c 100644 --- a/CHANGELOG.md +++ b/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 diff --git a/src/naive/date.rs b/src/naive/date.rs index 8470c5a..bfe76cf 100644 --- a/src/naive/date.rs +++ b/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 { + 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) {