Merge pull request #311 from quodlibetor/document-timestamp-nanos-panics

Document timestamp_nanos panics

Cargo.toml

@@ -28,6 +28,7 @@ default = ["clock"]
 clock = ["time"]
 
 [dependencies]
+libc = { version = "0.2", default-features = false }
 time = { version = "0.1.39", optional = true }
 num-integer = { version = "0.1.36", default-features = false }
 num-traits = { version = "0.2", default-features = false }

src/format/parse.rs

@@ -4,6 +4,8 @@
 
 //! Date and time parsing routines.
 
+#![allow(deprecated)]
+
 use std::usize;
 
 use Weekday;

src/format/scan.rs

@@ -5,6 +5,8 @@
  * Various scanning routines for the parser.
  */
 
+#![allow(deprecated)]
+
 use Weekday;
 use super::{ParseResult, TOO_SHORT, INVALID, OUT_OF_RANGE};
 

src/naive/datetime.rs

@@ -305,21 +305,33 @@ impl NaiveDateTime {
     /// Note that this does *not* account for the timezone!
     /// The true "UNIX timestamp" would count seconds since the midnight *UTC* on the epoch.
     ///
+    /// # Panics
+    ///
     /// Note also that this does reduce the number of years that can be
-    /// represented from ~584 Billion to ~584. (If this is a problem,
-    /// please file an issue to let me know what domain needs nanosecond
-    /// precision over millenia, I'm curious.)
+    /// represented from ~584 Billion to ~584 years. The dates that can be
+    /// represented as nanoseconds are between 1677-09-21T00:12:44.0 and
+    /// 2262-04-11T23:47:16.854775804.
+    ///
+    /// (If this is a problem, please file an issue to let me know what domain
+    /// needs nanosecond precision over millenia, I'm curious.)
     ///
     /// # Example
     ///
     /// ~~~~
-    /// use chrono::NaiveDate;
+    /// use chrono::{NaiveDate, NaiveDateTime};
     ///
     /// let dt = NaiveDate::from_ymd(1970, 1, 1).and_hms_nano(0, 0, 1, 444);
     /// assert_eq!(dt.timestamp_nanos(), 1_000_000_444);
     ///
     /// let dt = NaiveDate::from_ymd(2001, 9, 9).and_hms_nano(1, 46, 40, 555);
-    /// assert_eq!(dt.timestamp_nanos(), 1_000_000_000_000_000_555);
+    ///
+    /// const A_BILLION: i64 = 1_000_000_000;
+    /// let nanos = dt.timestamp_nanos();
+    /// assert_eq!(nanos, 1_000_000_000_000_000_555);
+    /// assert_eq!(
+    ///     dt,
+    ///     NaiveDateTime::from_timestamp(nanos / A_BILLION, (nanos % A_BILLION) as u32)
+    /// );
     /// ~~~~
     #[inline]
     pub fn timestamp_nanos(&self) -> i64 {
@@ -2348,4 +2360,24 @@ mod tests {
         let time = base + Duration::microseconds(t);
         assert_eq!(t, time.signed_duration_since(base).num_microseconds().unwrap());
     }
+
+    #[test]
+    fn test_nanosecond_range() {
+        const A_BILLION: i64 = 1_000_000_000;
+        let maximum = "2262-04-11T23:47:16.854775804";
+        let parsed: NaiveDateTime = maximum.parse().unwrap();
+        let nanos = parsed.timestamp_nanos();
+        assert_eq!(
+            parsed,
+            NaiveDateTime::from_timestamp(nanos / A_BILLION, (nanos % A_BILLION) as u32)
+        );
+
+        let minimum = "1677-09-21T00:12:44.000000000";
+        let parsed: NaiveDateTime = minimum.parse().unwrap();
+        let nanos = parsed.timestamp_nanos();
+        assert_eq!(
+            parsed,
+            NaiveDateTime::from_timestamp(nanos / A_BILLION, (nanos % A_BILLION) as u32)
+        );
+    }
 }