From 0393cae36d248f35fe780716368ef62bafd8b63e Mon Sep 17 00:00:00 2001 From: Kang Seonghoon Date: Mon, 8 Aug 2016 03:34:00 +0900 Subject: [PATCH] Standardized the doc example format for shortened methods. Especially for naives types, methods can be too long to fit in one line. Previously ad-hoc closures have been used for extreme cases; this commit will update them to the following form: use anything::needs::to::be::imported; let shortened = SomeType::long_name_to_be_shortened; assert_eq!(shortened(...), ...); It should be noted that the shortened name is no longer arbitrary; it should be either the original method name, or when it gets too long, a name with adjectives and clauses removed. The abbreviation is now consistent, and restricted to the following: - `num_days` -> `ndays`; `num_secs` -> `nsecs` - `hms_milli` -> `hmsm`; - `hms_micro` -> `hmsu`; `hms_nano` -> `hmsn` The goal is to make examples NOT look alike tests, and more alike the actual code. (Well, not always possible but I'm trying.) --- src/naive/date.rs | 156 +++++++++++++++++-------------- src/naive/datetime.rs | 1 + src/naive/time.rs | 212 +++++++++++++++++++++++------------------- 3 files changed, 199 insertions(+), 170 deletions(-) diff --git a/src/naive/date.rs b/src/naive/date.rs index 4aeaf19..61bff19 100644 --- a/src/naive/date.rs +++ b/src/naive/date.rs @@ -179,13 +179,14 @@ impl NaiveDate { /// ~~~~ /// use chrono::NaiveDate; /// - /// let ymd = |y,m,d| NaiveDate::from_ymd_opt(y, m, d); - /// assert!(ymd(2015, 3, 14).is_some()); - /// assert!(ymd(2015, 0, 14).is_none()); - /// assert!(ymd(2015, 2, 29).is_none()); - /// assert!(ymd(-4, 2, 29).is_some()); // 5 BCE is a leap year - /// assert!(ymd(400000, 1, 1).is_none()); - /// assert!(ymd(-400000, 1, 1).is_none()); + /// let from_ymd_opt = NaiveDate::from_ymd_opt; + /// + /// assert!(from_ymd_opt(2015, 3, 14).is_some()); + /// assert!(from_ymd_opt(2015, 0, 14).is_none()); + /// assert!(from_ymd_opt(2015, 2, 29).is_none()); + /// assert!(from_ymd_opt(-4, 2, 29).is_some()); // 5 BCE is a leap year + /// assert!(from_ymd_opt(400000, 1, 1).is_none()); + /// assert!(from_ymd_opt(-400000, 1, 1).is_none()); /// ~~~~ pub fn from_ymd_opt(year: i32, month: u32, day: u32) -> Option { let flags = YearFlags::from_year(year); @@ -224,14 +225,15 @@ impl NaiveDate { /// ~~~~ /// use chrono::NaiveDate; /// - /// let yo = |y,o| NaiveDate::from_yo_opt(y, o); - /// assert!(yo(2015, 100).is_some()); - /// assert!(yo(2015, 0).is_none()); - /// assert!(yo(2015, 365).is_some()); - /// assert!(yo(2015, 366).is_none()); - /// assert!(yo(-4, 366).is_some()); // 5 BCE is a leap year - /// assert!(yo(400000, 1).is_none()); - /// assert!(yo(-400000, 1).is_none()); + /// let from_yo_opt = NaiveDate::from_yo_opt; + /// + /// assert!(from_yo_opt(2015, 100).is_some()); + /// assert!(from_yo_opt(2015, 0).is_none()); + /// assert!(from_yo_opt(2015, 365).is_some()); + /// assert!(from_yo_opt(2015, 366).is_none()); + /// assert!(from_yo_opt(-4, 366).is_some()); // 5 BCE is a leap year + /// assert!(from_yo_opt(400000, 1).is_none()); + /// assert!(from_yo_opt(-400000, 1).is_none()); /// ~~~~ pub fn from_yo_opt(year: i32, ordinal: u32) -> Option { let flags = YearFlags::from_year(year); @@ -272,38 +274,38 @@ impl NaiveDate { /// ~~~~ /// use chrono::{NaiveDate, Weekday}; /// - /// let ymd = |y,m,d| NaiveDate::from_ymd(y, m, d); - /// let isoywd = |y,w,d| NaiveDate::from_isoywd_opt(y, w, d); + /// let from_ymd = NaiveDate::from_ymd; + /// let from_isoywd_opt = NaiveDate::from_isoywd_opt; /// - /// assert_eq!(isoywd(2015, 0, Weekday::Sun), None); - /// assert_eq!(isoywd(2015, 10, Weekday::Sun), Some(ymd(2015, 3, 8))); - /// assert_eq!(isoywd(2015, 30, Weekday::Mon), Some(ymd(2015, 7, 20))); - /// assert_eq!(isoywd(2015, 60, Weekday::Mon), None); + /// assert_eq!(from_isoywd_opt(2015, 0, Weekday::Sun), None); + /// assert_eq!(from_isoywd_opt(2015, 10, Weekday::Sun), Some(from_ymd(2015, 3, 8))); + /// assert_eq!(from_isoywd_opt(2015, 30, Weekday::Mon), Some(from_ymd(2015, 7, 20))); + /// assert_eq!(from_isoywd_opt(2015, 60, Weekday::Mon), None); /// - /// assert_eq!(isoywd(400000, 10, Weekday::Fri), None); - /// assert_eq!(isoywd(-400000, 10, Weekday::Sat), None); + /// assert_eq!(from_isoywd_opt(400000, 10, Weekday::Fri), None); + /// assert_eq!(from_isoywd_opt(-400000, 10, Weekday::Sat), None); /// ~~~~ /// /// The year number of ISO week date may differ from that of the calendar date. /// /// ~~~~ /// # use chrono::{NaiveDate, Weekday}; - /// # let ymd = |y,m,d| NaiveDate::from_ymd(y, m, d); - /// # let isoywd = |y,w,d| NaiveDate::from_isoywd_opt(y, w, d); + /// # let from_ymd = NaiveDate::from_ymd; + /// # let from_isoywd_opt = NaiveDate::from_isoywd_opt; /// // Mo Tu We Th Fr Sa Su /// // 2014-W52 22 23 24 25 26 27 28 has 4+ days of new year, /// // 2015-W01 29 30 31 1 2 3 4 <- so this is the first week - /// assert_eq!(isoywd(2014, 52, Weekday::Sun), Some(ymd(2014, 12, 28))); - /// assert_eq!(isoywd(2014, 53, Weekday::Mon), None); - /// assert_eq!(isoywd(2015, 1, Weekday::Mon), Some(ymd(2014, 12, 29))); + /// assert_eq!(from_isoywd_opt(2014, 52, Weekday::Sun), Some(from_ymd(2014, 12, 28))); + /// assert_eq!(from_isoywd_opt(2014, 53, Weekday::Mon), None); + /// assert_eq!(from_isoywd_opt(2015, 1, Weekday::Mon), Some(from_ymd(2014, 12, 29))); /// /// // 2015-W52 21 22 23 24 25 26 27 has 4+ days of old year, /// // 2015-W53 28 29 30 31 1 2 3 <- so this is the last week /// // 2016-W01 4 5 6 7 8 9 10 - /// assert_eq!(isoywd(2015, 52, Weekday::Sun), Some(ymd(2015, 12, 27))); - /// assert_eq!(isoywd(2015, 53, Weekday::Sun), Some(ymd(2016, 1, 3))); - /// assert_eq!(isoywd(2015, 54, Weekday::Mon), None); - /// assert_eq!(isoywd(2016, 1, Weekday::Mon), Some(ymd(2016, 1, 4))); + /// assert_eq!(from_isoywd_opt(2015, 52, Weekday::Sun), Some(from_ymd(2015, 12, 27))); + /// assert_eq!(from_isoywd_opt(2015, 53, Weekday::Sun), Some(from_ymd(2016, 1, 3))); + /// assert_eq!(from_isoywd_opt(2015, 54, Weekday::Mon), None); + /// assert_eq!(from_isoywd_opt(2016, 1, Weekday::Mon), Some(from_ymd(2016, 1, 4))); /// ~~~~ pub fn from_isoywd_opt(year: i32, week: u32, weekday: Weekday) -> Option { let flags = YearFlags::from_year(year); @@ -387,13 +389,15 @@ impl NaiveDate { /// ~~~~ /// use chrono::NaiveDate; /// - /// let days = |ndays| NaiveDate::from_num_days_from_ce_opt(ndays); - /// assert_eq!(days(730000), Some(NaiveDate::from_ymd(1999, 9, 3))); - /// assert_eq!(days(1), Some(NaiveDate::from_ymd(1, 1, 1))); - /// assert_eq!(days(0), Some(NaiveDate::from_ymd(0, 12, 31))); - /// assert_eq!(days(-1), Some(NaiveDate::from_ymd(0, 12, 30))); - /// assert_eq!(days(100000000), None); - /// assert_eq!(days(-100000000), None); + /// let from_ndays_opt = NaiveDate::from_num_days_from_ce_opt; + /// let from_ymd = NaiveDate::from_ymd; + /// + /// assert_eq!(from_ndays_opt(730_000), Some(from_ymd(1999, 9, 3))); + /// assert_eq!(from_ndays_opt(1), Some(from_ymd(1, 1, 1))); + /// assert_eq!(from_ndays_opt(0), Some(from_ymd(0, 12, 31))); + /// assert_eq!(from_ndays_opt(-1), Some(from_ymd(0, 12, 30))); + /// assert_eq!(from_ndays_opt(100_000_000), None); + /// assert_eq!(from_ndays_opt(-100_000_000), None); /// ~~~~ pub fn from_num_days_from_ce_opt(days: i32) -> Option { let days = days + 365; // make December 31, 1 BCE equal to day 0 @@ -413,9 +417,11 @@ impl NaiveDate { /// ~~~~ /// use chrono::NaiveDate; /// - /// assert_eq!(NaiveDate::parse_from_str("2015-09-05", "%Y-%m-%d"), + /// let parse_from_str = NaiveDate::parse_from_str; + /// + /// assert_eq!(parse_from_str("2015-09-05", "%Y-%m-%d"), /// Ok(NaiveDate::from_ymd(2015, 9, 5))); - /// assert_eq!(NaiveDate::parse_from_str("5sep2015", "%d%b%Y"), + /// assert_eq!(parse_from_str("5sep2015", "%d%b%Y"), /// Ok(NaiveDate::from_ymd(2015, 9, 5))); /// ~~~~ /// @@ -423,7 +429,8 @@ impl NaiveDate { /// /// ~~~~ /// # use chrono::NaiveDate; - /// assert_eq!(NaiveDate::parse_from_str("2014-5-17T12:34:56+09:30", "%Y-%m-%dT%H:%M:%S%z"), + /// # let parse_from_str = NaiveDate::parse_from_str; + /// assert_eq!(parse_from_str("2014-5-17T12:34:56+09:30", "%Y-%m-%dT%H:%M:%S%z"), /// Ok(NaiveDate::from_ymd(2014, 5, 17))); /// ~~~~ /// @@ -431,15 +438,17 @@ impl NaiveDate { /// /// ~~~~ /// # use chrono::NaiveDate; - /// assert!(NaiveDate::parse_from_str("2015/9", "%Y/%m").is_err()); - /// assert!(NaiveDate::parse_from_str("2015/9/31", "%Y/%m/%d").is_err()); + /// # let parse_from_str = NaiveDate::parse_from_str; + /// assert!(parse_from_str("2015/9", "%Y/%m").is_err()); + /// assert!(parse_from_str("2015/9/31", "%Y/%m/%d").is_err()); /// ~~~~ /// /// All parsed fields should be consistent to each other, otherwise it's an error. /// /// ~~~~ /// # use chrono::NaiveDate; - /// assert!(NaiveDate::parse_from_str("Sat, 09 Aug 2013", "%a, %d %b %Y").is_err()); + /// # let parse_from_str = NaiveDate::parse_from_str; + /// assert!(parse_from_str("Sat, 09 Aug 2013", "%a, %d %b %Y").is_err()); /// ~~~~ pub fn parse_from_str(s: &str, fmt: &str) -> ParseResult { let mut parsed = Parsed::new(); @@ -1279,15 +1288,16 @@ impl hash::Hash for NaiveDate { /// ~~~~ /// use chrono::{NaiveDate, Duration}; /// -/// let ymd = |y,m,d| NaiveDate::from_ymd(y, m, d); -/// assert_eq!(ymd(2014, 1, 1) + Duration::zero(), ymd(2014, 1, 1)); -/// assert_eq!(ymd(2014, 1, 1) + Duration::seconds(86399), ymd(2014, 1, 1)); -/// assert_eq!(ymd(2014, 1, 1) + Duration::seconds(-86399), ymd(2014, 1, 1)); -/// assert_eq!(ymd(2014, 1, 1) + Duration::days(1), ymd(2014, 1, 2)); -/// assert_eq!(ymd(2014, 1, 1) + Duration::days(-1), ymd(2013, 12, 31)); -/// assert_eq!(ymd(2014, 1, 1) + Duration::days(364), ymd(2014, 12, 31)); -/// assert_eq!(ymd(2014, 1, 1) + Duration::days(365*4 + 1), ymd(2018, 1, 1)); -/// assert_eq!(ymd(2014, 1, 1) + Duration::days(365*400 + 97), ymd(2414, 1, 1)); +/// let from_ymd = NaiveDate::from_ymd; +/// +/// assert_eq!(from_ymd(2014, 1, 1) + Duration::zero(), from_ymd(2014, 1, 1)); +/// assert_eq!(from_ymd(2014, 1, 1) + Duration::seconds(86399), from_ymd(2014, 1, 1)); +/// assert_eq!(from_ymd(2014, 1, 1) + Duration::seconds(-86399), from_ymd(2014, 1, 1)); +/// assert_eq!(from_ymd(2014, 1, 1) + Duration::days(1), from_ymd(2014, 1, 2)); +/// assert_eq!(from_ymd(2014, 1, 1) + Duration::days(-1), from_ymd(2013, 12, 31)); +/// assert_eq!(from_ymd(2014, 1, 1) + Duration::days(364), from_ymd(2014, 12, 31)); +/// assert_eq!(from_ymd(2014, 1, 1) + Duration::days(365*4 + 1), from_ymd(2018, 1, 1)); +/// assert_eq!(from_ymd(2014, 1, 1) + Duration::days(365*400 + 97), from_ymd(2414, 1, 1)); /// ~~~~ impl Add for NaiveDate { type Output = NaiveDate; @@ -1308,14 +1318,15 @@ impl Add for NaiveDate { /// ~~~~ /// use chrono::{NaiveDate, Duration}; /// -/// let ymd = |y,m,d| NaiveDate::from_ymd(y, m, d); -/// assert_eq!(ymd(2014, 1, 1) - ymd(2014, 1, 1), Duration::zero()); -/// assert_eq!(ymd(2014, 1, 1) - ymd(2013, 12, 31), Duration::days(1)); -/// assert_eq!(ymd(2014, 1, 1) - ymd(2014, 1, 2), Duration::days(-1)); -/// assert_eq!(ymd(2014, 1, 1) - ymd(2013, 9, 23), Duration::days(100)); -/// assert_eq!(ymd(2014, 1, 1) - ymd(2013, 1, 1), Duration::days(365)); -/// assert_eq!(ymd(2014, 1, 1) - ymd(2010, 1, 1), Duration::days(365*4 + 1)); -/// assert_eq!(ymd(2014, 1, 1) - ymd(1614, 1, 1), Duration::days(365*400 + 97)); +/// let from_ymd = NaiveDate::from_ymd; +/// +/// assert_eq!(from_ymd(2014, 1, 1) - from_ymd(2014, 1, 1), Duration::zero()); +/// assert_eq!(from_ymd(2014, 1, 1) - from_ymd(2013, 12, 31), Duration::days(1)); +/// assert_eq!(from_ymd(2014, 1, 1) - from_ymd(2014, 1, 2), Duration::days(-1)); +/// assert_eq!(from_ymd(2014, 1, 1) - from_ymd(2013, 9, 23), Duration::days(100)); +/// assert_eq!(from_ymd(2014, 1, 1) - from_ymd(2013, 1, 1), Duration::days(365)); +/// assert_eq!(from_ymd(2014, 1, 1) - from_ymd(2010, 1, 1), Duration::days(365*4 + 1)); +/// assert_eq!(from_ymd(2014, 1, 1) - from_ymd(1614, 1, 1), Duration::days(365*400 + 97)); /// ~~~~ impl Sub for NaiveDate { type Output = Duration; @@ -1343,15 +1354,16 @@ impl Sub for NaiveDate { /// ~~~~ /// use chrono::{NaiveDate, Duration}; /// -/// let ymd = |y,m,d| NaiveDate::from_ymd(y, m, d); -/// assert_eq!(ymd(2014, 1, 1) - Duration::zero(), ymd(2014, 1, 1)); -/// assert_eq!(ymd(2014, 1, 1) - Duration::seconds(86399), ymd(2014, 1, 1)); -/// assert_eq!(ymd(2014, 1, 1) - Duration::seconds(-86399), ymd(2014, 1, 1)); -/// assert_eq!(ymd(2014, 1, 1) - Duration::days(1), ymd(2013, 12, 31)); -/// assert_eq!(ymd(2014, 1, 1) - Duration::days(-1), ymd(2014, 1, 2)); -/// assert_eq!(ymd(2014, 1, 1) - Duration::days(364), ymd(2013, 1, 2)); -/// assert_eq!(ymd(2014, 1, 1) - Duration::days(365*4 + 1), ymd(2010, 1, 1)); -/// assert_eq!(ymd(2014, 1, 1) - Duration::days(365*400 + 97), ymd(1614, 1, 1)); +/// let from_ymd = NaiveDate::from_ymd; +/// +/// assert_eq!(from_ymd(2014, 1, 1) - Duration::zero(), from_ymd(2014, 1, 1)); +/// assert_eq!(from_ymd(2014, 1, 1) - Duration::seconds(86399), from_ymd(2014, 1, 1)); +/// assert_eq!(from_ymd(2014, 1, 1) - Duration::seconds(-86399), from_ymd(2014, 1, 1)); +/// assert_eq!(from_ymd(2014, 1, 1) - Duration::days(1), from_ymd(2013, 12, 31)); +/// assert_eq!(from_ymd(2014, 1, 1) - Duration::days(-1), from_ymd(2014, 1, 2)); +/// assert_eq!(from_ymd(2014, 1, 1) - Duration::days(364), from_ymd(2013, 1, 2)); +/// assert_eq!(from_ymd(2014, 1, 1) - Duration::days(365*4 + 1), from_ymd(2010, 1, 1)); +/// assert_eq!(from_ymd(2014, 1, 1) - Duration::days(365*400 + 97), from_ymd(1614, 1, 1)); /// ~~~~ impl Sub for NaiveDate { type Output = NaiveDate; @@ -1712,7 +1724,7 @@ mod tests { } #[test] - fn test_date_from_isoymd_and_isoweekdate() { + fn test_date_from_isoywd_and_isoweekdate() { for year in 2000..2401 { for week in 1..54 { for &weekday in [Weekday::Mon, Weekday::Tue, Weekday::Wed, Weekday::Thu, diff --git a/src/naive/datetime.rs b/src/naive/datetime.rs index 593dc9b..7fb248b 100644 --- a/src/naive/datetime.rs +++ b/src/naive/datetime.rs @@ -91,6 +91,7 @@ impl NaiveDateTime { /// use std::i64; /// /// let from_timestamp_opt = NaiveDateTime::from_timestamp_opt; + /// /// assert!(from_timestamp_opt(0, 0).is_some()); /// assert!(from_timestamp_opt(0, 999_999_999).is_some()); /// assert!(from_timestamp_opt(0, 1_500_000_000).is_some()); // leap second diff --git a/src/naive/time.rs b/src/naive/time.rs index 41e68d4..b87cd0a 100644 --- a/src/naive/time.rs +++ b/src/naive/time.rs @@ -117,12 +117,13 @@ impl NaiveTime { /// ~~~~ /// use chrono::NaiveTime; /// - /// let hms = |h,m,s| NaiveTime::from_hms_opt(h, m, s); - /// assert!(hms(0, 0, 0).is_some()); - /// assert!(hms(23, 59, 59).is_some()); - /// assert!(hms(24, 0, 0).is_none()); - /// assert!(hms(23, 60, 0).is_none()); - /// assert!(hms(23, 59, 60).is_none()); + /// let from_hms_opt = NaiveTime::from_hms_opt; + /// + /// assert!(from_hms_opt(0, 0, 0).is_some()); + /// assert!(from_hms_opt(23, 59, 59).is_some()); + /// assert!(from_hms_opt(24, 0, 0).is_none()); + /// assert!(from_hms_opt(23, 60, 0).is_none()); + /// assert!(from_hms_opt(23, 59, 60).is_none()); /// ~~~~ #[inline] pub fn from_hms_opt(hour: u32, min: u32, sec: u32) -> Option { @@ -164,14 +165,15 @@ impl NaiveTime { /// ~~~~ /// use chrono::NaiveTime; /// - /// let hmsm = |h,m,s,milli| NaiveTime::from_hms_milli_opt(h, m, s, milli); - /// assert!(hmsm(0, 0, 0, 0).is_some()); - /// assert!(hmsm(23, 59, 59, 999).is_some()); - /// assert!(hmsm(23, 59, 59, 1_999).is_some()); // a leap second following 23:59:59 - /// assert!(hmsm(24, 0, 0, 0).is_none()); - /// assert!(hmsm(23, 60, 0, 0).is_none()); - /// assert!(hmsm(23, 59, 60, 0).is_none()); - /// assert!(hmsm(23, 59, 59, 2_000).is_none()); + /// let from_hmsm_opt = NaiveTime::from_hms_milli_opt; + /// + /// assert!(from_hmsm_opt(0, 0, 0, 0).is_some()); + /// assert!(from_hmsm_opt(23, 59, 59, 999).is_some()); + /// assert!(from_hmsm_opt(23, 59, 59, 1_999).is_some()); // a leap second after 23:59:59 + /// assert!(from_hmsm_opt(24, 0, 0, 0).is_none()); + /// assert!(from_hmsm_opt(23, 60, 0, 0).is_none()); + /// assert!(from_hmsm_opt(23, 59, 60, 0).is_none()); + /// assert!(from_hmsm_opt(23, 59, 59, 2_000).is_none()); /// ~~~~ #[inline] pub fn from_hms_milli_opt(hour: u32, min: u32, sec: u32, milli: u32) -> Option { @@ -214,14 +216,15 @@ impl NaiveTime { /// ~~~~ /// use chrono::NaiveTime; /// - /// let hmsu = |h,m,s,micro| NaiveTime::from_hms_micro_opt(h, m, s, micro); - /// assert!(hmsu(0, 0, 0, 0).is_some()); - /// assert!(hmsu(23, 59, 59, 999_999).is_some()); - /// assert!(hmsu(23, 59, 59, 1_999_999).is_some()); // a leap second following 23:59:59 - /// assert!(hmsu(24, 0, 0, 0).is_none()); - /// assert!(hmsu(23, 60, 0, 0).is_none()); - /// assert!(hmsu(23, 59, 60, 0).is_none()); - /// assert!(hmsu(23, 59, 59, 2_000_000).is_none()); + /// let from_hmsu_opt = NaiveTime::from_hms_micro_opt; + /// + /// assert!(from_hmsu_opt(0, 0, 0, 0).is_some()); + /// assert!(from_hmsu_opt(23, 59, 59, 999_999).is_some()); + /// assert!(from_hmsu_opt(23, 59, 59, 1_999_999).is_some()); // a leap second after 23:59:59 + /// assert!(from_hmsu_opt(24, 0, 0, 0).is_none()); + /// assert!(from_hmsu_opt(23, 60, 0, 0).is_none()); + /// assert!(from_hmsu_opt(23, 59, 60, 0).is_none()); + /// assert!(from_hmsu_opt(23, 59, 59, 2_000_000).is_none()); /// ~~~~ #[inline] pub fn from_hms_micro_opt(hour: u32, min: u32, sec: u32, micro: u32) -> Option { @@ -264,14 +267,15 @@ impl NaiveTime { /// ~~~~ /// use chrono::NaiveTime; /// - /// let hmsn = |h,m,s,nano| NaiveTime::from_hms_nano_opt(h, m, s, nano); - /// assert!(hmsn(0, 0, 0, 0).is_some()); - /// assert!(hmsn(23, 59, 59, 999_999_999).is_some()); - /// assert!(hmsn(23, 59, 59, 1_999_999_999).is_some()); // a leap second following 23:59:59 - /// assert!(hmsn(24, 0, 0, 0).is_none()); - /// assert!(hmsn(23, 60, 0, 0).is_none()); - /// assert!(hmsn(23, 59, 60, 0).is_none()); - /// assert!(hmsn(23, 59, 59, 2_000_000_000).is_none()); + /// let from_hmsn_opt = NaiveTime::from_hms_nano_opt; + /// + /// assert!(from_hmsn_opt(0, 0, 0, 0).is_some()); + /// assert!(from_hmsn_opt(23, 59, 59, 999_999_999).is_some()); + /// assert!(from_hmsn_opt(23, 59, 59, 1_999_999_999).is_some()); // a leap second after 23:59:59 + /// assert!(from_hmsn_opt(24, 0, 0, 0).is_none()); + /// assert!(from_hmsn_opt(23, 60, 0, 0).is_none()); + /// assert!(from_hmsn_opt(23, 59, 60, 0).is_none()); + /// assert!(from_hmsn_opt(23, 59, 59, 2_000_000_000).is_none()); /// ~~~~ #[inline] pub fn from_hms_nano_opt(hour: u32, min: u32, sec: u32, nano: u32) -> Option { @@ -315,12 +319,13 @@ impl NaiveTime { /// ~~~~ /// use chrono::NaiveTime; /// - /// let secs = |secs,nano| NaiveTime::from_num_seconds_from_midnight_opt(secs, nano); - /// assert!(secs(0, 0).is_some()); - /// assert!(secs(86399, 999_999_999).is_some()); - /// assert!(secs(86399, 1_999_999_999).is_some()); // a leap second following 23:59:59 - /// assert!(secs(86400, 0).is_none()); - /// assert!(secs(86399, 2_000_000_000).is_none()); + /// let from_nsecs_opt = NaiveTime::from_num_seconds_from_midnight_opt; + /// + /// assert!(from_nsecs_opt(0, 0).is_some()); + /// assert!(from_nsecs_opt(86399, 999_999_999).is_some()); + /// assert!(from_nsecs_opt(86399, 1_999_999_999).is_some()); // a leap second after 23:59:59 + /// assert!(from_nsecs_opt(86400, 0).is_none()); + /// assert!(from_nsecs_opt(86399, 2_000_000_000).is_none()); /// ~~~~ #[inline] pub fn from_num_seconds_from_midnight_opt(secs: u32, nano: u32) -> Option { @@ -337,9 +342,11 @@ impl NaiveTime { /// ~~~~ /// use chrono::NaiveTime; /// - /// assert_eq!(NaiveTime::parse_from_str("23:56:04", "%H:%M:%S"), + /// let parse_from_str = NaiveTime::parse_from_str; + /// + /// assert_eq!(parse_from_str("23:56:04", "%H:%M:%S"), /// Ok(NaiveTime::from_hms(23, 56, 4))); - /// assert_eq!(NaiveTime::parse_from_str("pm012345.6789", "%p%I%M%S%.f"), + /// assert_eq!(parse_from_str("pm012345.6789", "%p%I%M%S%.f"), /// Ok(NaiveTime::from_hms_micro(13, 23, 45, 678_900))); /// ~~~~ /// @@ -347,7 +354,8 @@ impl NaiveTime { /// /// ~~~~ /// # use chrono::NaiveTime; - /// assert_eq!(NaiveTime::parse_from_str("2014-5-17T12:34:56+09:30", "%Y-%m-%dT%H:%M:%S%z"), + /// # let parse_from_str = NaiveTime::parse_from_str; + /// assert_eq!(parse_from_str("2014-5-17T12:34:56+09:30", "%Y-%m-%dT%H:%M:%S%z"), /// Ok(NaiveTime::from_hms(12, 34, 56))); /// ~~~~ /// @@ -357,7 +365,8 @@ impl NaiveTime { /// /// ~~~~ /// # use chrono::NaiveTime; - /// assert_eq!(NaiveTime::parse_from_str("08:59:60.123", "%H:%M:%S%.f"), + /// # let parse_from_str = NaiveTime::parse_from_str; + /// assert_eq!(parse_from_str("08:59:60.123", "%H:%M:%S%.f"), /// Ok(NaiveTime::from_hms_milli(8, 59, 59, 1_123))); /// ~~~~ /// @@ -366,13 +375,14 @@ impl NaiveTime { /// /// ~~~~ /// # use chrono::NaiveTime; - /// assert_eq!(NaiveTime::parse_from_str("7:15", "%H:%M"), + /// # let parse_from_str = NaiveTime::parse_from_str; + /// assert_eq!(parse_from_str("7:15", "%H:%M"), /// Ok(NaiveTime::from_hms(7, 15, 0))); /// - /// assert!(NaiveTime::parse_from_str("04m33s", "%Mm%Ss").is_err()); - /// assert!(NaiveTime::parse_from_str("12", "%H").is_err()); - /// assert!(NaiveTime::parse_from_str("17:60", "%H:%M").is_err()); - /// assert!(NaiveTime::parse_from_str("24:00:00", "%H:%M:%S").is_err()); + /// assert!(parse_from_str("04m33s", "%Mm%Ss").is_err()); + /// assert!(parse_from_str("12", "%H").is_err()); + /// assert!(parse_from_str("17:60", "%H:%M").is_err()); + /// assert!(parse_from_str("24:00:00", "%H:%M:%S").is_err()); /// ~~~~ /// /// All parsed fields should be consistent to each other, otherwise it's an error. @@ -381,7 +391,8 @@ impl NaiveTime { /// /// ~~~~ /// # use chrono::NaiveTime; - /// assert!(NaiveTime::parse_from_str("13:07 AM", "%H:%M %p").is_err()); + /// # let parse_from_str = NaiveTime::parse_from_str; + /// assert!(parse_from_str("13:07 AM", "%H:%M %p").is_err()); /// ~~~~ pub fn parse_from_str(s: &str, fmt: &str) -> ParseResult { let mut parsed = Parsed::new(); @@ -707,39 +718,41 @@ impl hash::Hash for NaiveTime { /// ~~~~ /// use chrono::{NaiveTime, Duration}; /// -/// let hmsm = |h,m,s,milli| NaiveTime::from_hms_milli(h, m, s, milli); -/// assert_eq!(hmsm(3, 5, 7, 0) + Duration::zero(), hmsm(3, 5, 7, 0)); -/// assert_eq!(hmsm(3, 5, 7, 0) + Duration::seconds(1), hmsm(3, 5, 8, 0)); -/// assert_eq!(hmsm(3, 5, 7, 0) + Duration::seconds(-1), hmsm(3, 5, 6, 0)); -/// assert_eq!(hmsm(3, 5, 7, 0) + Duration::seconds(60 + 4), hmsm(3, 6, 11, 0)); -/// assert_eq!(hmsm(3, 5, 7, 0) + Duration::seconds(7*60*60 - 6*60), hmsm(9, 59, 7, 0)); -/// assert_eq!(hmsm(3, 5, 7, 0) + Duration::milliseconds(80), hmsm(3, 5, 7, 80)); -/// assert_eq!(hmsm(3, 5, 7, 950) + Duration::milliseconds(280), hmsm(3, 5, 8, 230)); -/// assert_eq!(hmsm(3, 5, 7, 950) + Duration::milliseconds(-980), hmsm(3, 5, 6, 970)); +/// let from_hmsm = NaiveTime::from_hms_milli; +/// +/// assert_eq!(from_hmsm(3, 5, 7, 0) + Duration::zero(), from_hmsm(3, 5, 7, 0)); +/// assert_eq!(from_hmsm(3, 5, 7, 0) + Duration::seconds(1), from_hmsm(3, 5, 8, 0)); +/// assert_eq!(from_hmsm(3, 5, 7, 0) + Duration::seconds(-1), from_hmsm(3, 5, 6, 0)); +/// assert_eq!(from_hmsm(3, 5, 7, 0) + Duration::seconds(60 + 4), from_hmsm(3, 6, 11, 0)); +/// assert_eq!(from_hmsm(3, 5, 7, 0) + Duration::seconds(7*60*60 - 6*60), from_hmsm(9, 59, 7, 0)); +/// assert_eq!(from_hmsm(3, 5, 7, 0) + Duration::milliseconds(80), from_hmsm(3, 5, 7, 80)); +/// assert_eq!(from_hmsm(3, 5, 7, 950) + Duration::milliseconds(280), from_hmsm(3, 5, 8, 230)); +/// assert_eq!(from_hmsm(3, 5, 7, 950) + Duration::milliseconds(-980), from_hmsm(3, 5, 6, 970)); /// ~~~~ /// /// The addition wraps around. /// /// ~~~~ /// # use chrono::{NaiveTime, Duration}; -/// # let hmsm = |h,m,s,milli| NaiveTime::from_hms_milli(h, m, s, milli); -/// assert_eq!(hmsm(3, 5, 7, 0) + Duration::seconds(22*60*60), hmsm(1, 5, 7, 0)); -/// assert_eq!(hmsm(3, 5, 7, 0) + Duration::seconds(-8*60*60), hmsm(19, 5, 7, 0)); -/// assert_eq!(hmsm(3, 5, 7, 0) + Duration::days(800), hmsm(3, 5, 7, 0)); +/// # let from_hmsm = NaiveTime::from_hms_milli; +/// assert_eq!(from_hmsm(3, 5, 7, 0) + Duration::seconds(22*60*60), from_hmsm(1, 5, 7, 0)); +/// assert_eq!(from_hmsm(3, 5, 7, 0) + Duration::seconds(-8*60*60), from_hmsm(19, 5, 7, 0)); +/// assert_eq!(from_hmsm(3, 5, 7, 0) + Duration::days(800), from_hmsm(3, 5, 7, 0)); /// ~~~~ /// /// Leap seconds are handled, but the addition assumes that it is the only leap second happened. /// /// ~~~~ /// # use chrono::{NaiveTime, Duration}; -/// # let hmsm = |h,m,s,milli| NaiveTime::from_hms_milli(h, m, s, milli); -/// assert_eq!(hmsm(3, 5, 59, 1_300) + Duration::zero(), hmsm(3, 5, 59, 1_300)); -/// assert_eq!(hmsm(3, 5, 59, 1_300) + Duration::milliseconds(-500), hmsm(3, 5, 59, 800)); -/// assert_eq!(hmsm(3, 5, 59, 1_300) + Duration::milliseconds(500), hmsm(3, 5, 59, 1_800)); -/// assert_eq!(hmsm(3, 5, 59, 1_300) + Duration::milliseconds(800), hmsm(3, 6, 0, 100)); -/// assert_eq!(hmsm(3, 5, 59, 1_300) + Duration::seconds(10), hmsm(3, 6, 9, 300)); -/// assert_eq!(hmsm(3, 5, 59, 1_300) + Duration::seconds(-10), hmsm(3, 5, 50, 300)); -/// assert_eq!(hmsm(3, 5, 59, 1_300) + Duration::days(1), hmsm(3, 5, 59, 300)); +/// # let from_hmsm = NaiveTime::from_hms_milli; +/// let leap = from_hmsm(3, 5, 59, 1_300); +/// assert_eq!(leap + Duration::zero(), from_hmsm(3, 5, 59, 1_300)); +/// assert_eq!(leap + Duration::milliseconds(-500), from_hmsm(3, 5, 59, 800)); +/// assert_eq!(leap + Duration::milliseconds(500), from_hmsm(3, 5, 59, 1_800)); +/// assert_eq!(leap + Duration::milliseconds(800), from_hmsm(3, 6, 0, 100)); +/// assert_eq!(leap + Duration::seconds(10), from_hmsm(3, 6, 9, 300)); +/// assert_eq!(leap + Duration::seconds(-10), from_hmsm(3, 5, 50, 300)); +/// assert_eq!(leap + Duration::days(1), from_hmsm(3, 5, 59, 300)); /// ~~~~ impl Add for NaiveTime { type Output = NaiveTime; @@ -837,15 +850,16 @@ impl Add for NaiveTime { /// ~~~~ /// use chrono::{NaiveTime, Duration}; /// -/// let hmsm = |h,m,s,milli| NaiveTime::from_hms_milli(h, m, s, milli); -/// assert_eq!(hmsm(3, 5, 7, 900) - hmsm(3, 5, 7, 900), Duration::zero()); -/// assert_eq!(hmsm(3, 5, 7, 900) - hmsm(3, 5, 7, 875), Duration::milliseconds(25)); -/// assert_eq!(hmsm(3, 5, 7, 900) - hmsm(3, 5, 6, 925), Duration::milliseconds(975)); -/// assert_eq!(hmsm(3, 5, 7, 900) - hmsm(3, 5, 0, 900), Duration::seconds(7)); -/// assert_eq!(hmsm(3, 5, 7, 900) - hmsm(3, 0, 7, 900), Duration::seconds(5 * 60)); -/// assert_eq!(hmsm(3, 5, 7, 900) - hmsm(0, 5, 7, 900), Duration::seconds(3 * 3600)); -/// assert_eq!(hmsm(3, 5, 7, 900) - hmsm(4, 5, 7, 900), Duration::seconds(-3600)); -/// assert_eq!(hmsm(3, 5, 7, 900) - hmsm(2, 4, 6, 800), +/// let from_hmsm = NaiveTime::from_hms_milli; +/// +/// assert_eq!(from_hmsm(3, 5, 7, 900) - from_hmsm(3, 5, 7, 900), Duration::zero()); +/// assert_eq!(from_hmsm(3, 5, 7, 900) - from_hmsm(3, 5, 7, 875), Duration::milliseconds(25)); +/// assert_eq!(from_hmsm(3, 5, 7, 900) - from_hmsm(3, 5, 6, 925), Duration::milliseconds(975)); +/// assert_eq!(from_hmsm(3, 5, 7, 900) - from_hmsm(3, 5, 0, 900), Duration::seconds(7)); +/// assert_eq!(from_hmsm(3, 5, 7, 900) - from_hmsm(3, 0, 7, 900), Duration::seconds(5 * 60)); +/// assert_eq!(from_hmsm(3, 5, 7, 900) - from_hmsm(0, 5, 7, 900), Duration::seconds(3 * 3600)); +/// assert_eq!(from_hmsm(3, 5, 7, 900) - from_hmsm(4, 5, 7, 900), Duration::seconds(-3600)); +/// assert_eq!(from_hmsm(3, 5, 7, 900) - from_hmsm(2, 4, 6, 800), /// Duration::seconds(3600 + 60 + 1) + Duration::milliseconds(100)); /// ~~~~ /// @@ -854,12 +868,12 @@ impl Add for NaiveTime { /// /// ~~~~ /// # use chrono::{NaiveTime, Duration}; -/// # let hmsm = |h,m,s,milli| NaiveTime::from_hms_milli(h, m, s, milli); -/// assert_eq!(hmsm(3, 0, 59, 1_000) - hmsm(3, 0, 59, 0), Duration::seconds(1)); -/// assert_eq!(hmsm(3, 0, 59, 1_500) - hmsm(3, 0, 59, 0), Duration::milliseconds(1500)); -/// assert_eq!(hmsm(3, 0, 59, 1_000) - hmsm(3, 0, 0, 0), Duration::seconds(60)); -/// assert_eq!(hmsm(3, 0, 0, 0) - hmsm(2, 59, 59, 1_000), Duration::seconds(1)); -/// assert_eq!(hmsm(3, 0, 59, 1_000) - hmsm(2, 59, 59, 1_000), Duration::seconds(61)); +/// # let from_hmsm = NaiveTime::from_hms_milli; +/// assert_eq!(from_hmsm(3, 0, 59, 1_000) - from_hmsm(3, 0, 59, 0), Duration::seconds(1)); +/// assert_eq!(from_hmsm(3, 0, 59, 1_500) - from_hmsm(3, 0, 59, 0), Duration::milliseconds(1500)); +/// assert_eq!(from_hmsm(3, 0, 59, 1_000) - from_hmsm(3, 0, 0, 0), Duration::seconds(60)); +/// assert_eq!(from_hmsm(3, 0, 0, 0) - from_hmsm(2, 59, 59, 1_000), Duration::seconds(1)); +/// assert_eq!(from_hmsm(3, 0, 59, 1_000) - from_hmsm(2, 59, 59, 1_000), Duration::seconds(61)); /// ~~~~ impl Sub for NaiveTime { type Output = Duration; @@ -915,34 +929,36 @@ impl Sub for NaiveTime { /// ~~~~ /// use chrono::{NaiveTime, Duration}; /// -/// let hmsm = |h,m,s,milli| NaiveTime::from_hms_milli(h, m, s, milli); -/// assert_eq!(hmsm(3, 5, 7, 0) - Duration::zero(), hmsm(3, 5, 7, 0)); -/// assert_eq!(hmsm(3, 5, 7, 0) - Duration::seconds(1), hmsm(3, 5, 6, 0)); -/// assert_eq!(hmsm(3, 5, 7, 0) - Duration::seconds(60 + 5), hmsm(3, 4, 2, 0)); -/// assert_eq!(hmsm(3, 5, 7, 0) - Duration::seconds(2*60*60 + 6*60), hmsm(0, 59, 7, 0)); -/// assert_eq!(hmsm(3, 5, 7, 0) - Duration::milliseconds(80), hmsm(3, 5, 6, 920)); -/// assert_eq!(hmsm(3, 5, 7, 950) - Duration::milliseconds(280), hmsm(3, 5, 7, 670)); +/// let from_hmsm = NaiveTime::from_hms_milli; +/// +/// assert_eq!(from_hmsm(3, 5, 7, 0) - Duration::zero(), from_hmsm(3, 5, 7, 0)); +/// assert_eq!(from_hmsm(3, 5, 7, 0) - Duration::seconds(1), from_hmsm(3, 5, 6, 0)); +/// assert_eq!(from_hmsm(3, 5, 7, 0) - Duration::seconds(60 + 5), from_hmsm(3, 4, 2, 0)); +/// assert_eq!(from_hmsm(3, 5, 7, 0) - Duration::seconds(2*60*60 + 6*60), from_hmsm(0, 59, 7, 0)); +/// assert_eq!(from_hmsm(3, 5, 7, 0) - Duration::milliseconds(80), from_hmsm(3, 5, 6, 920)); +/// assert_eq!(from_hmsm(3, 5, 7, 950) - Duration::milliseconds(280), from_hmsm(3, 5, 7, 670)); /// ~~~~ /// /// The subtraction wraps around. /// /// ~~~~ /// # use chrono::{NaiveTime, Duration}; -/// # let hmsm = |h,m,s,milli| NaiveTime::from_hms_milli(h, m, s, milli); -/// assert_eq!(hmsm(3, 5, 7, 0) - Duration::seconds(8*60*60), hmsm(19, 5, 7, 0)); -/// assert_eq!(hmsm(3, 5, 7, 0) - Duration::days(800), hmsm(3, 5, 7, 0)); +/// # let from_hmsm = NaiveTime::from_hms_milli; +/// assert_eq!(from_hmsm(3, 5, 7, 0) - Duration::seconds(8*60*60), from_hmsm(19, 5, 7, 0)); +/// assert_eq!(from_hmsm(3, 5, 7, 0) - Duration::days(800), from_hmsm(3, 5, 7, 0)); /// ~~~~ /// /// Leap seconds are handled, but the subtraction assumes that it is the only leap second happened. /// /// ~~~~ /// # use chrono::{NaiveTime, Duration}; -/// # let hmsm = |h,m,s,milli| NaiveTime::from_hms_milli(h, m, s, milli); -/// assert_eq!(hmsm(3, 5, 59, 1_300) - Duration::zero(), hmsm(3, 5, 59, 1_300)); -/// assert_eq!(hmsm(3, 5, 59, 1_300) - Duration::milliseconds(200), hmsm(3, 5, 59, 1_100)); -/// assert_eq!(hmsm(3, 5, 59, 1_300) - Duration::milliseconds(500), hmsm(3, 5, 59, 800)); -/// assert_eq!(hmsm(3, 5, 59, 1_300) - Duration::seconds(60), hmsm(3, 5, 0, 300)); -/// assert_eq!(hmsm(3, 5, 59, 1_300) - Duration::days(1), hmsm(3, 6, 0, 300)); +/// # let from_hmsm = NaiveTime::from_hms_milli; +/// let leap = from_hmsm(3, 5, 59, 1_300); +/// assert_eq!(leap - Duration::zero(), from_hmsm(3, 5, 59, 1_300)); +/// assert_eq!(leap - Duration::milliseconds(200), from_hmsm(3, 5, 59, 1_100)); +/// assert_eq!(leap - Duration::milliseconds(500), from_hmsm(3, 5, 59, 800)); +/// assert_eq!(leap - Duration::seconds(60), from_hmsm(3, 5, 0, 300)); +/// assert_eq!(leap - Duration::days(1), from_hmsm(3, 6, 0, 300)); /// ~~~~ impl Sub for NaiveTime { type Output = NaiveTime;