Merge pull request chronotope#1414 from pitdicker/merge_0.4.x

Merge 0.4.x

.github/dependabot.yml

@@ -4,14 +4,14 @@ updates:
     directory: "/"
     schedule:
       interval: "weekly"
-    target-branch: "0.4.x"
+    target-branch: "main"
   - package-ecosystem: "cargo"
     directory: "/fuzz/"
     schedule:
       interval: "weekly"
-    target-branch: "0.4.x"
+    target-branch: "main"
   - package-ecosystem: "github-actions"
     directory: "/"
     schedule:
       interval: "weekly"
-    target-branch: "0.4.x"
+    target-branch: "main"

.github/workflows/codecov.yml

@@ -25,7 +25,7 @@ jobs:
       - name: Generate code coverage
         run: cargo +nightly llvm-cov ${{ env.ALL_NON_EXCLUSIVE_FEATURES }} --workspace --lcov --doctests --output-path lcov.info
       - name: Upload coverage to Codecov
-        uses: codecov/codecov-action@v3
+        uses: codecov/codecov-action@v4
         env:
           CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
         with:

src/datetime/mod.rs

@@ -88,7 +88,7 @@ impl<Tz: TimeZone> DateTime<Tz> {
         DateTime { datetime, offset }
     }
 
-    /// Retrieves the date without an associated timezone.
+    /// Retrieves the date component.
     ///
     /// # Panics
     ///
@@ -135,7 +135,7 @@ impl<Tz: TimeZone> DateTime<Tz> {
     /// ```
     #[inline]
     #[must_use]
-    pub fn timestamp(&self) -> i64 {
+    pub const fn timestamp(&self) -> i64 {
         self.datetime.timestamp()
     }
 
@@ -154,7 +154,7 @@ impl<Tz: TimeZone> DateTime<Tz> {
     /// ```
     #[inline]
     #[must_use]
-    pub fn timestamp_millis(&self) -> i64 {
+    pub const fn timestamp_millis(&self) -> i64 {
         self.datetime.timestamp_millis()
     }
 
@@ -173,7 +173,7 @@ impl<Tz: TimeZone> DateTime<Tz> {
     /// ```
     #[inline]
     #[must_use]
-    pub fn timestamp_micros(&self) -> i64 {
+    pub const fn timestamp_micros(&self) -> i64 {
         self.datetime.timestamp_micros()
     }
 
@@ -212,7 +212,7 @@ impl<Tz: TimeZone> DateTime<Tz> {
     /// ```
     #[inline]
     #[must_use]
-    pub fn timestamp_nanos(&self) -> Option<i64> {
+    pub const fn timestamp_nanos(&self) -> Option<i64> {
         self.datetime.timestamp_nanos()
     }
 
@@ -221,7 +221,7 @@ impl<Tz: TimeZone> DateTime<Tz> {
     /// In event of a leap second this may exceed 999.
     #[inline]
     #[must_use]
-    pub fn timestamp_subsec_millis(&self) -> u32 {
+    pub const fn timestamp_subsec_millis(&self) -> u32 {
         self.datetime.timestamp_subsec_millis()
     }
 
@@ -230,7 +230,7 @@ impl<Tz: TimeZone> DateTime<Tz> {
     /// In event of a leap second this may exceed 999,999.
     #[inline]
     #[must_use]
-    pub fn timestamp_subsec_micros(&self) -> u32 {
+    pub const fn timestamp_subsec_micros(&self) -> u32 {
         self.datetime.timestamp_subsec_micros()
     }
 
@@ -239,14 +239,14 @@ impl<Tz: TimeZone> DateTime<Tz> {
     /// In event of a leap second this may exceed 999,999,999.
     #[inline]
     #[must_use]
-    pub fn timestamp_subsec_nanos(&self) -> u32 {
+    pub const fn timestamp_subsec_nanos(&self) -> u32 {
         self.datetime.timestamp_subsec_nanos()
     }
 
     /// Retrieves an associated offset from UTC.
     #[inline]
     #[must_use]
-    pub fn offset(&self) -> &Tz::Offset {
+    pub const fn offset(&self) -> &Tz::Offset {
         &self.offset
     }
 
@@ -278,11 +278,11 @@ impl<Tz: TimeZone> DateTime<Tz> {
     /// information.
     #[inline]
     #[must_use]
-    pub fn to_utc(&self) -> DateTime<Utc> {
+    pub const fn to_utc(&self) -> DateTime<Utc> {
         DateTime { datetime: self.datetime, offset: Utc }
     }
 
-    /// Adds given `Duration` to the current date and time.
+    /// Adds given `TimeDelta` to the current date and time.
     ///
     /// # Errors
     ///
@@ -315,7 +315,7 @@ impl<Tz: TimeZone> DateTime<Tz> {
             .single()
     }
 
-    /// Subtracts given `Duration` from the current date and time.
+    /// Subtracts given `TimeDelta` from the current date and time.
     ///
     /// # Errors
     ///
@@ -394,7 +394,7 @@ impl<Tz: TimeZone> DateTime<Tz> {
     /// Returns a view to the naive UTC datetime.
     #[inline]
     #[must_use]
-    pub fn naive_utc(&self) -> NaiveDateTime {
+    pub const fn naive_utc(&self) -> NaiveDateTime {
         self.datetime
     }
 
@@ -571,8 +571,8 @@ impl DateTime<Utc> {
     /// ```
     #[inline]
     #[must_use]
-    pub fn from_timestamp_millis(millis: i64) -> Option<Self> {
-        NaiveDateTime::from_timestamp_millis(millis).as_ref().map(NaiveDateTime::and_utc)
+    pub const fn from_timestamp_millis(millis: i64) -> Option<Self> {
+        Some(try_opt!(NaiveDateTime::from_timestamp_millis(millis)).and_utc())
     }
 
     /// The Unix Epoch, 1970-01-01 00:00:00 UTC.
@@ -677,8 +677,7 @@ where
 }
 
 impl DateTime<FixedOffset> {
-    /// Parses an RFC 2822 date and time string such as `Tue, 1 Jul 2003 10:52:37 +0200`,
-    /// then returns a new [`DateTime`] with a parsed [`FixedOffset`].
+    /// Parses an RFC 2822 date-and-time string into a `DateTime<FixedOffset>` value.
     ///
     /// This parses valid RFC 2822 datetime strings (such as `Tue, 1 Jul 2003 10:52:37 +0200`)
     /// and returns a new [`DateTime`] instance with the parsed timezone as the [`FixedOffset`].
@@ -717,8 +716,7 @@ impl DateTime<FixedOffset> {
         parsed.to_datetime()
     }
 
-    /// Parses an RFC 3339 and ISO 8601 date and time string such as `1996-12-19T16:39:57-08:00`,
-    /// then returns a new [`DateTime`] with a parsed [`FixedOffset`].
+    /// Parses an RFC 3339 date-and-time string into a `DateTime<FixedOffset>` value.
     ///
     /// Parses all valid RFC 3339 values (as well as the subset of valid ISO 8601 values that are
     /// also valid RFC 3339 date-and-time values) and returns a new [`DateTime`] with a
@@ -740,8 +738,7 @@ impl DateTime<FixedOffset> {
         parsed.to_datetime()
     }
 
-    /// Parses a string with the specified format string and returns a new
-    /// [`DateTime`] with a parsed [`FixedOffset`].
+    /// Parses a string from a user-specified format into a `DateTime<FixedOffset>` value.
     ///
     /// Note that this method *requires a timezone* in the input string. See
     /// [`NaiveDateTime::parse_from_str`](./naive/struct.NaiveDateTime.html#method.parse_from_str)
@@ -1162,7 +1159,7 @@ impl<Tz: TimeZone> hash::Hash for DateTime<Tz> {
     }
 }
 
-/// Add `chrono::Duration` to `DateTime`.
+/// Add `TimeDelta` to `DateTime`.
 ///
 /// As a part of Chrono's [leap second handling], the addition assumes that **there is no leap
 /// second ever**, except when the `NaiveDateTime` itself represents a leap  second in which case
@@ -1177,7 +1174,7 @@ impl<Tz: TimeZone> Add<TimeDelta> for DateTime<Tz> {
 
     #[inline]
     fn add(self, rhs: TimeDelta) -> DateTime<Tz> {
-        self.checked_add_signed(rhs).expect("`DateTime + Duration` overflowed")
+        self.checked_add_signed(rhs).expect("`DateTime + TimeDelta` overflowed")
     }
 }
 
@@ -1197,8 +1194,8 @@ impl<Tz: TimeZone> Add<Duration> for DateTime<Tz> {
     #[inline]
     fn add(self, rhs: Duration) -> DateTime<Tz> {
         let rhs = TimeDelta::from_std(rhs)
-            .expect("overflow converting from core::time::Duration to chrono::Duration");
-        self.checked_add_signed(rhs).expect("`DateTime + Duration` overflowed")
+            .expect("overflow converting from core::time::Duration to TimeDelta");
+        self.checked_add_signed(rhs).expect("`DateTime + TimeDelta` overflowed")
     }
 }
 
@@ -1216,7 +1213,7 @@ impl<Tz: TimeZone> AddAssign<TimeDelta> for DateTime<Tz> {
     #[inline]
     fn add_assign(&mut self, rhs: TimeDelta) {
         let datetime =
-            self.datetime.checked_add_signed(rhs).expect("`DateTime + Duration` overflowed");
+            self.datetime.checked_add_signed(rhs).expect("`DateTime + TimeDelta` overflowed");
         let tz = self.timezone();
         *self = tz.from_utc_datetime(&datetime);
     }
@@ -1236,7 +1233,7 @@ impl<Tz: TimeZone> AddAssign<Duration> for DateTime<Tz> {
     #[inline]
     fn add_assign(&mut self, rhs: Duration) {
         let rhs = TimeDelta::from_std(rhs)
-            .expect("overflow converting from core::time::Duration to chrono::Duration");
+            .expect("overflow converting from core::time::Duration to TimeDelta");
         *self += rhs;
     }
 }
@@ -1278,9 +1275,9 @@ impl<Tz: TimeZone> Add<Months> for DateTime<Tz> {
     }
 }
 
-/// Subtract `chrono::Duration` from `DateTime`.
+/// Subtract `TimeDelta` from `DateTime`.
 ///
-/// This is the same as the addition with a negated `Duration`.
+/// This is the same as the addition with a negated `TimeDelta`.
 ///
 /// As a part of Chrono's [leap second handling] the subtraction assumes that **there is no leap
 /// second ever**, except when the `DateTime` itself represents a leap second in which case
@@ -1295,7 +1292,7 @@ impl<Tz: TimeZone> Sub<TimeDelta> for DateTime<Tz> {
 
     #[inline]
     fn sub(self, rhs: TimeDelta) -> DateTime<Tz> {
-        self.checked_sub_signed(rhs).expect("`DateTime - Duration` overflowed")
+        self.checked_sub_signed(rhs).expect("`DateTime - TimeDelta` overflowed")
     }
 }
 
@@ -1315,14 +1312,14 @@ impl<Tz: TimeZone> Sub<Duration> for DateTime<Tz> {
     #[inline]
     fn sub(self, rhs: Duration) -> DateTime<Tz> {
         let rhs = TimeDelta::from_std(rhs)
-            .expect("overflow converting from core::time::Duration to chrono::Duration");
-        self.checked_sub_signed(rhs).expect("`DateTime - Duration` overflowed")
+            .expect("overflow converting from core::time::Duration to TimeDelta");
+        self.checked_sub_signed(rhs).expect("`DateTime - TimeDelta` overflowed")
     }
 }
 
-/// Subtract-assign `chrono::Duration` from `DateTime`.
+/// Subtract-assign `TimeDelta` from `DateTime`.
 ///
-/// This is the same as the addition with a negated `Duration`.
+/// This is the same as the addition with a negated `TimeDelta`.
 ///
 /// As a part of Chrono's [leap second handling], the addition assumes that **there is no leap
 /// second ever**, except when the `DateTime` itself represents a leap  second in which case
@@ -1336,7 +1333,7 @@ impl<Tz: TimeZone> SubAssign<TimeDelta> for DateTime<Tz> {
     #[inline]
     fn sub_assign(&mut self, rhs: TimeDelta) {
         let datetime =
-            self.datetime.checked_sub_signed(rhs).expect("`DateTime - Duration` overflowed");
+            self.datetime.checked_sub_signed(rhs).expect("`DateTime - TimeDelta` overflowed");
         let tz = self.timezone();
         *self = tz.from_utc_datetime(&datetime)
     }
@@ -1356,7 +1353,7 @@ impl<Tz: TimeZone> SubAssign<Duration> for DateTime<Tz> {
     #[inline]
     fn sub_assign(&mut self, rhs: Duration) {
         let rhs = TimeDelta::from_std(rhs)
-            .expect("overflow converting from core::time::Duration to chrono::Duration");
+            .expect("overflow converting from core::time::Duration to TimeDelta");
         *self -= rhs;
     }
 }

src/lib.rs

@@ -50,18 +50,19 @@
 //!
 //! ## Overview
 //!
-//! ### Duration
+//! ### Time delta / Duration
 //!
-//! Chrono currently uses its own [`TimeDelta`] type to represent the magnitude
-//! of a time span. Note that this is an "accurate" duration represented as seconds and
-//! nanoseconds and does not represent "nominal" components such as days or
-//! months.
+//! Chrono has a [`TimeDelta`] type to represent the magnitude of a time span. This is an
+//! "accurate" duration represented as seconds and nanoseconds, and does not represent "nominal"
+//! components such as days or months.
 //!
-//! Chrono does not yet natively support
-//! the standard [`Duration`](https://doc.rust-lang.org/std/time/struct.Duration.html) type,
-//! but it will be supported in the future.
-//! Meanwhile you can convert between two types with
-//! [`TimeDelta::from_std`] and [`TimeDelta::to_std`] methods.
+//! The [`TimeDelta`] type was previously named `Duration` (and is still available as a type alias
+//! with that name). A notable difference with the similar [`core::time::Duration`] is that it is a
+//! signed value instead of unsigned.
+//!
+//! Chrono currently only supports a small number of operations with [`core::time::Duration`] .
+//! You can convert between both types with the [`TimeDelta::from_std`] and [`TimeDelta::to_std`]
+//! methods.
 //!
 //! ### Date and Time
 //!
@@ -456,6 +457,7 @@ extern crate alloc;
 
 mod time_delta;
 #[cfg(feature = "std")]
+#[doc(no_inline)]
 pub use time_delta::OutOfRangeError;
 pub use time_delta::TimeDelta;