From d9a50cb767a4227a5733896c74a53c82cd0cd970 Mon Sep 17 00:00:00 2001 From: Toby Dimmick Date: Tue, 3 Apr 2018 13:58:26 +0100 Subject: [PATCH] Documentation --- src/naive/date.rs | 27 +++++++++++++++++++++++ src/naive/datetime.rs | 46 ++++++++++++++++++++++++++++++++++++++ src/naive/time.rs | 51 +++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 124 insertions(+) diff --git a/src/naive/date.rs b/src/naive/date.rs index e5c363e..ef6627d 100644 --- a/src/naive/date.rs +++ b/src/naive/date.rs @@ -1378,6 +1378,33 @@ impl Sub for NaiveDate { } } +/// Subtracts another `NaiveDate` from the current date. +/// Returns a `Duration` of integral numbers. +/// +/// This does not overflow or underflow at all, +/// as all possible output fits in the range of `Duration`. +/// +/// The implementation is a wrapper around +/// [`NaiveDate::signed_duration_since`](#method.signed_duration_since). +/// +/// # Example +/// +/// ~~~~ +/// # extern crate chrono; extern crate time; fn main() { +/// use chrono::NaiveDate; +/// use time::Duration; +/// +/// 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 = OldDuration; diff --git a/src/naive/datetime.rs b/src/naive/datetime.rs index b404cb9..3c761f7 100644 --- a/src/naive/datetime.rs +++ b/src/naive/datetime.rs @@ -1272,6 +1272,52 @@ impl Sub for NaiveDateTime { } } +/// Subtracts another `NaiveDateTime` from the current date and time. +/// This does not overflow or underflow at all. +/// +/// As a part of Chrono's [leap second handling](./struct.NaiveTime.html#leap-second-handling), +/// the subtraction assumes that **there is no leap second ever**, +/// except when any of the `NaiveDateTime`s themselves represents a leap second +/// in which case the assumption becomes that +/// **there are exactly one (or two) leap second(s) ever**. +/// +/// The implementation is a wrapper around +/// [`NaiveDateTime::signed_duration_since`](#method.signed_duration_since). +/// +/// # Example +/// +/// ~~~~ +/// # extern crate chrono; extern crate time; fn main() { +/// use chrono::NaiveDate; +/// use time::Duration; +/// +/// let from_ymd = NaiveDate::from_ymd; +/// +/// let d = from_ymd(2016, 7, 8); +/// assert_eq!(d.and_hms(3, 5, 7) - d.and_hms(2, 4, 6), Duration::seconds(3600 + 60 + 1)); +/// +/// // July 8 is 190th day in the year 2016 +/// let d0 = from_ymd(2016, 1, 1); +/// assert_eq!(d.and_hms_milli(0, 7, 6, 500) - d0.and_hms(0, 0, 0), +/// Duration::seconds(189 * 86_400 + 7 * 60 + 6) + Duration::milliseconds(500)); +/// # } +/// ~~~~ +/// +/// Leap seconds are handled, but the subtraction assumes that +/// there were no other leap seconds happened. +/// +/// ~~~~ +/// # extern crate chrono; extern crate time; fn main() { +/// # use chrono::NaiveDate; +/// # use time::Duration; +/// # let from_ymd = NaiveDate::from_ymd; +/// let leap = from_ymd(2015, 6, 30).and_hms_milli(23, 59, 59, 1_500); +/// assert_eq!(leap - from_ymd(2015, 6, 30).and_hms(23, 0, 0), +/// Duration::seconds(3600) + Duration::milliseconds(500)); +/// assert_eq!(from_ymd(2015, 7, 1).and_hms(1, 0, 0) - leap, +/// Duration::seconds(3600) - Duration::milliseconds(500)); +/// # } +/// ~~~~ impl Sub for NaiveDateTime { type Output = OldDuration; diff --git a/src/naive/time.rs b/src/naive/time.rs index 1c78165..73e1c3e 100644 --- a/src/naive/time.rs +++ b/src/naive/time.rs @@ -1126,6 +1126,57 @@ impl Sub for NaiveTime { } } +/// Subtracts another `NaiveTime` from the current time. +/// Returns a `Duration` within +/- 1 day. +/// This does not overflow or underflow at all. +/// +/// As a part of Chrono's [leap second handling](#leap-second-handling), +/// the subtraction assumes that **there is no leap second ever**, +/// except when any of the `NaiveTime`s themselves represents a leap second +/// in which case the assumption becomes that +/// **there are exactly one (or two) leap second(s) ever**. +/// +/// The implementation is a wrapper around +/// [`NaiveTime::signed_duration_since`](#method.signed_duration_since). +/// +/// # Example +/// +/// ~~~~ +/// # extern crate chrono; extern crate time; fn main() { +/// use chrono::NaiveTime; +/// use time::Duration; +/// +/// 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)); +/// # } +/// ~~~~ +/// +/// Leap seconds are handled, but the subtraction assumes that +/// there were no other leap seconds happened. +/// +/// ~~~~ +/// # extern crate chrono; extern crate time; fn main() { +/// # use chrono::NaiveTime; +/// # use time::Duration; +/// # 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 = OldDuration;