Add first and last day of year methods

time/src/date.rs

@@ -1252,6 +1252,43 @@ impl Date {
         // Safety: `ordinal` is in range and `is_leap_year` is correct.
         Ok(unsafe { Self::from_parts(self.year(), is_leap_year, ordinal) })
     }
+
+    /// Get the first day of the year.
+    ///
+    /// ```rust
+    /// # use time_macros::date;
+    /// assert_eq!(date!(2022-049).first_day_of_year(), date!(2022-001));
+    /// ```
+    #[inline]
+    #[must_use = "This method does not mutate the original `Date`."]
+    pub const fn first_day_of_year(self) -> Self {
+        let is_leap_year = self.is_in_leap_year();
+        // Safety: ordinal of 1 is in range and `is_leap_year` is correct.
+        unsafe { Self::from_parts(self.year(), is_leap_year, 1) }
+    }
+
+    /// Get the last day of the year.
+    ///
+    /// ```rust
+    /// # use time_macros::date;
+    /// // 2022 isn't a leap year
+    /// assert_eq!(date!(2022-049).last_day_of_year(), date!(2022-365));
+    /// // 2024 is a leap year
+    /// assert_eq!(date!(2024-001).last_day_of_year(), date!(2024-366));
+    /// ```
+    #[inline]
+    #[must_use = "This method does not mutate the original `Date`."]
+    pub const fn last_day_of_year(self) -> Self {
+        let is_leap_year = self.is_in_leap_year();
+        let last_ordinal = if !is_leap_year {
+            365
+        } else {
+            hint::cold_path();
+            366
+        };
+        // Safety: ordinals are checked to be in range and `is_leap_year` is correct.
+        unsafe { Self::from_parts(self.year(), is_leap_year, last_ordinal) }
+    }
 }
 
 /// Methods to add a [`Time`] component, resulting in a [`PrimitiveDateTime`].

time/src/offset_date_time.rs

@@ -1448,6 +1448,39 @@ impl OffsetDateTime {
         )
     }
 
+    /// Get the start of the first day of the year.
+    ///
+    /// ```rust
+    /// # use time_macros::datetime;
+    /// assert_eq!(datetime!(2022-049 12:00:00 +01:00).first_day_of_year(), datetime!(2022-001 00:00:00 +01:00));
+    /// ```
+    #[inline]
+    #[must_use = "This method does not mutate the original `PrimitiveDateTime`."]
+    pub const fn first_day_of_year(self) -> Self {
+        OffsetDateTime {
+            local_date_time: self.local_date_time.first_day_of_year(),
+            offset: self.offset,
+        }
+    }
+
+    /// Get the start of the last day of the year.
+    ///
+    /// ```rust
+    /// # use time_macros::datetime;
+    /// // 2022 isn't a leap year
+    /// assert_eq!(datetime!(2022-049 12:00:00 +01:00).last_day_of_year(), datetime!(2022-365 00:00:00 +01:00));
+    /// // 2024 is a leap year
+    /// assert_eq!(datetime!(2024-001 12:00:00 -08:00).last_day_of_year(), datetime!(2024-366 00:00:00 -08:00));
+    /// ```
+    #[inline]
+    #[must_use = "This method does not mutate the original `PrimitiveDateTime`."]
+    pub const fn last_day_of_year(self) -> Self {
+        OffsetDateTime {
+            local_date_time: self.local_date_time.last_day_of_year(),
+            offset: self.offset,
+        }
+    }
+
     /// Truncate to the microsecond, setting the nanosecond component to zero.
     ///
     /// ```rust

time/src/primitive_date_time.rs

@@ -982,6 +982,39 @@ impl PrimitiveDateTime {
         self.replace_time(self.time.truncate_to_millisecond())
     }
 
+    /// Get the start of the first day of the year.
+    ///
+    /// ```rust
+    /// # use time_macros::datetime;
+    /// assert_eq!(datetime!(2022-049 12:00:00).first_day_of_year(), datetime!(2022-001 00:00:00));
+    /// ```
+    #[inline]
+    #[must_use = "This method does not mutate the original `PrimitiveDateTime`."]
+    pub const fn first_day_of_year(self) -> Self {
+        PrimitiveDateTime {
+            time: Time::MIDNIGHT,
+            date: self.date.first_day_of_year(),
+        }
+    }
+
+    /// Get the start of the last day of the year.
+    ///
+    /// ```rust
+    /// # use time_macros::datetime;
+    /// // 2022 isn't a leap year
+    /// assert_eq!(datetime!(2022-049 12:00:00).last_day_of_year(), datetime!(2022-365 00:00:00));
+    /// // 2024 is a leap year
+    /// assert_eq!(datetime!(2024-001 12:00:00).last_day_of_year(), datetime!(2024-366 00:00:00));
+    /// ```
+    #[inline]
+    #[must_use = "This method does not mutate the original `PrimitiveDateTime`."]
+    pub const fn last_day_of_year(self) -> Self {
+        PrimitiveDateTime {
+            time: Time::MIDNIGHT,
+            date: self.date.last_day_of_year(),
+        }
+    }
+
     /// Replace the microseconds within the second.
     ///
     /// ```rust