Add from_timestamp_secs method to DateTime

Add a new single-argument function for creating a `DateTime` from a Unix
timestamp, to match `from_timestamp_micros`, `from_timestamp_millis`,
and `from_timestamp_nanos`.

Issue #1716 Suggestion: add DateTime::from_timestamp_secs function

Author: jasonaowen

src/datetime/mod.rs

@@ -755,6 +755,61 @@ impl DateTime<Utc> {
         Some(date.and_time(time).and_utc())
     }
 
+    /// Makes a new `DateTime<Utc>` from the number of non-leap seconds
+    /// since January 1, 1970 0:00:00 UTC (aka "UNIX timestamp").
+    ///
+    /// This is a convenience wrapper around [`DateTime::from_timestamp`],
+    /// which is useful in functions like [`Iterator::map`] to avoid a closure.
+    ///
+    /// This is guaranteed to round-trip with regard to [`timestamp`](DateTime::timestamp).
+    ///
+    /// If you need to create a `DateTime` with a [`TimeZone`] different from [`Utc`], use
+    /// [`TimeZone::timestamp_opt`] or [`DateTime::with_timezone`]; if you need to create a
+    /// `DateTime` with more precision, use [`DateTime::from_timestamp_micros`],
+    /// [`DateTime::from_timestamp_millis`], or [`DateTime::from_timestamp_nanos`].
+    ///
+    /// # Errors
+    ///
+    /// Returns `None` on out-of-range number of seconds,
+    /// otherwise returns `Some(DateTime {...})`.
+    ///
+    /// # Examples
+    ///
+    /// Using [`Option::and_then`]:
+    ///
+    /// ```
+    /// # use chrono::DateTime;
+    /// let maybe_timestamp: Option<i64> = Some(1431648000);
+    /// let maybe_dt = maybe_timestamp.and_then(DateTime::from_timestamp_secs);
+    ///
+    /// assert!(maybe_dt.is_some());
+    /// assert_eq!(maybe_dt.unwrap().to_string(), "2015-05-15 00:00:00 UTC");
+    /// ```
+    ///
+    /// Using [`Iterator::map`]:
+    ///
+    /// ```
+    /// # use chrono::{DateTime, Utc};
+    /// let v = vec![i64::MIN, 1_000_000_000, 1_234_567_890, i64::MAX];
+    /// let timestamps: Vec<Option<DateTime<Utc>>> = v
+    ///     .into_iter()
+    ///     .map(DateTime::from_timestamp_secs)
+    ///     .collect();
+    ///
+    /// assert_eq!(vec![
+    ///     None,
+    ///     Some(DateTime::parse_from_rfc3339("2001-09-09 01:46:40Z").unwrap().to_utc()),
+    ///     Some(DateTime::parse_from_rfc3339("2009-02-13 23:31:30Z").unwrap().to_utc()),
+    ///     None,
+    /// ], timestamps);
+    /// ```
+    ///
+    #[inline]
+    #[must_use]
+    pub const fn from_timestamp_secs(secs: i64) -> Option<Self> {
+        Self::from_timestamp(secs, 0)
+    }
+
     /// Makes a new `DateTime<Utc>` from the number of non-leap milliseconds
     /// since January 1, 1970 0:00:00.000 UTC (aka "UNIX timestamp").
     ///

src/datetime/tests.rs

@@ -247,6 +247,17 @@ fn test_datetime_from_timestamp_nanos() {
     }
 }
 
+#[test]
+fn test_datetime_from_timestamp_secs() {
+    let valid = [-2208936075, 0, 119731017, 1234567890, 2034061609];
+
+    for timestamp_secs in valid.iter().copied() {
+        let datetime = DateTime::from_timestamp_secs(timestamp_secs).unwrap();
+        assert_eq!(timestamp_secs, datetime.timestamp());
+        assert_eq!(DateTime::from_timestamp(timestamp_secs, 0).unwrap(), datetime);
+    }
+}
+
 #[test]
 fn test_datetime_from_timestamp() {
     let from_timestamp = |secs| DateTime::from_timestamp(secs, 0);