diff --git a/src/datetime/mod.rs b/src/datetime/mod.rs index 65a39aa8da..99a3917210 100644 --- a/src/datetime/mod.rs +++ b/src/datetime/mod.rs @@ -121,6 +121,13 @@ impl DateTime { /// Makes a new `DateTime` with given **local** datetime and offset that /// presents local timezone. /// + /// # Panics + /// + /// Panics if the local datetime can't be converted to UTC because it would be out of range. + /// + /// This can happen if `datetime` is near the end of the representable range of `NaiveDateTime`, + /// and the offset from UTC pushes it beyond that. + /// /// # Example /// /// ``` @@ -150,11 +157,19 @@ impl DateTime { DateTime { datetime: datetime_utc, offset } } - /// Retrieves a date component + /// Retrieves the date component with an associated timezone. /// /// Unless you are immediately planning on turning this into a `DateTime` - /// with the same Timezone you should use the - /// [`date_naive`](DateTime::date_naive) method. + /// with the same timezone you should use the [`date_naive`](DateTime::date_naive) method. + /// + /// [`NaiveDate`] is a more well-defined type, and has more traits implemented on it, + /// so should be preferred to [`Date`] any time you truly want to operate on dates. + /// + /// # Panics + /// + /// [`DateTime`] internally stores the date and time in UTC with a [`NaiveDateTime`]. This + /// method will panic if the offset from UTC would push the local date outside of the + /// representable range of a [`Date`]. #[inline] #[deprecated(since = "0.4.23", note = "Use `date_naive()` instead")] #[allow(deprecated)] @@ -163,10 +178,15 @@ impl DateTime { Date::from_utc(self.naive_local().date(), self.offset.clone()) } - /// Retrieves the Date without an associated timezone + /// Retrieves the date component. /// - /// [`NaiveDate`] is a more well-defined type, and has more traits implemented on it, - /// so should be preferred to [`Date`] any time you truly want to operate on Dates. + /// # Panics + /// + /// [`DateTime`] internally stores the date and time in UTC with a [`NaiveDateTime`]. This + /// method will panic if the offset from UTC would push the local date outside of the + /// representable range of a [`NaiveDate`]. + /// + /// # Example /// /// ``` /// use chrono::prelude::*; @@ -182,8 +202,7 @@ impl DateTime { NaiveDate::from_ymd_opt(local.year(), local.month(), local.day()).unwrap() } - /// Retrieves a time component. - /// Unlike `date`, this is not associated to the time zone. + /// Retrieves the time component. #[inline] #[must_use] pub fn time(&self) -> NaiveTime { @@ -198,12 +217,7 @@ impl DateTime { self.datetime.timestamp() } - /// Returns the number of non-leap-milliseconds since January 1, 1970 UTC - /// - /// Note that this does reduce the number of years that can be represented - /// from ~584 Billion to ~584 Million. (If this is a problem, please file - /// an issue to let me know what domain needs millisecond precision over - /// billions of years, I'm curious.) + /// Returns the number of non-leap-milliseconds since January 1, 1970 UTC. /// /// # Example /// @@ -222,12 +236,7 @@ impl DateTime { self.datetime.timestamp_millis() } - /// Returns the number of non-leap-microseconds since January 1, 1970 UTC - /// - /// Note that this does reduce the number of years that can be represented - /// from ~584 Billion to ~584 Thousand. (If this is a problem, please file - /// an issue to let me know what domain needs microsecond precision over - /// millennia, I'm curious.) + /// Returns the number of non-leap-microseconds since January 1, 1970 UTC. /// /// # Example /// @@ -246,12 +255,15 @@ impl DateTime { self.datetime.timestamp_micros() } - /// Returns the number of non-leap-nanoseconds since January 1, 1970 UTC + /// Returns the number of non-leap-nanoseconds since January 1, 1970 UTC. + /// + /// # Panics /// - /// Note 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 - /// millennia, I'm curious.) + /// An `i64` with nanosecond precision can span a range of ~584 years. This function panics on + /// an out of range `DateTime`. + /// + /// The dates that can be represented as nanoseconds are between 1677-09-21T00:12:44.0 and + /// 2262-04-11T23:47:16.854775804. /// /// # Example /// @@ -270,22 +282,18 @@ impl DateTime { self.datetime.timestamp_nanos() } - /// Returns the number of milliseconds since the last second boundary - /// - /// warning: in event of a leap second, this may exceed 999 + /// Returns the number of milliseconds since the last second boundary. /// - /// note: this is not the number of milliseconds since January 1, 1970 0:00:00 UTC + /// In event of a leap second this may exceed 999. #[inline] #[must_use] pub fn timestamp_subsec_millis(&self) -> u32 { self.datetime.timestamp_subsec_millis() } - /// Returns the number of microseconds since the last second boundary + /// Returns the number of microseconds since the last second boundary. /// - /// warning: in event of a leap second, this may exceed 999_999 - /// - /// note: this is not the number of microseconds since January 1, 1970 0:00:00 UTC + /// In event of a leap second this may exceed 999,999. #[inline] #[must_use] pub fn timestamp_subsec_micros(&self) -> u32 { @@ -294,9 +302,7 @@ impl DateTime { /// Returns the number of nanoseconds since the last second boundary /// - /// warning: in event of a leap second, this may exceed 999_999_999 - /// - /// note: this is not the number of nanoseconds since January 1, 1970 0:00:00 UTC + /// In event of a leap second this may exceed 999,999,999. #[inline] #[must_use] pub fn timestamp_subsec_nanos(&self) -> u32 { @@ -318,7 +324,8 @@ impl DateTime { } /// Changes the associated time zone. - /// The returned `DateTime` references the same instant of time from the perspective of the provided time zone. + /// The returned `DateTime` references the same instant of time from the perspective of the + /// provided time zone. #[inline] #[must_use] pub fn with_timezone(&self, tz: &Tz2) -> DateTime { @@ -335,7 +342,9 @@ impl DateTime { /// Adds given `Duration` to the current date and time. /// - /// Returns `None` when it will result in overflow. + /// # Errors + /// + /// Returns `None` if the resulting date would be out of range. #[inline] #[must_use] pub fn checked_add_signed(self, rhs: OldDuration) -> Option> { @@ -346,10 +355,16 @@ impl DateTime { /// Adds given `Months` to the current date and time. /// - /// Returns `None` when it will result in overflow, or if the - /// local time is not valid on the newly calculated date. + /// Uses the last day of the month if the day does not exist in the resulting month. + /// + /// See [`NaiveDate::checked_add_months`] for more details on behavior. /// - /// See [`NaiveDate::checked_add_months`] for more details on behavior + /// # Errors + /// + /// Returns `None` if: + /// - The resulting date would be out of range. + /// - The local time at the resulting date does not exist or is ambiguous, for example during a + /// daylight saving time transition. #[must_use] pub fn checked_add_months(self, rhs: Months) -> Option> { self.naive_local() @@ -360,7 +375,9 @@ impl DateTime { /// Subtracts given `Duration` from the current date and time. /// - /// Returns `None` when it will result in overflow. + /// # Errors + /// + /// Returns `None` if the resulting date would be out of range. #[inline] #[must_use] pub fn checked_sub_signed(self, rhs: OldDuration) -> Option> { @@ -371,10 +388,16 @@ impl DateTime { /// Subtracts given `Months` from the current date and time. /// - /// Returns `None` when it will result in overflow, or if the - /// local time is not valid on the newly calculated date. + /// Uses the last day of the month if the day does not exist in the resulting month. + /// + /// See [`NaiveDate::checked_sub_months`] for more details on behavior. /// - /// See [`NaiveDate::checked_sub_months`] for more details on behavior + /// # Errors + /// + /// Returns `None` if: + /// - The resulting date would be out of range. + /// - The local time at the resulting date does not exist or is ambiguous, for example during a + /// daylight saving time transition. #[must_use] pub fn checked_sub_months(self, rhs: Months) -> Option> { self.naive_local() @@ -383,9 +406,14 @@ impl DateTime { .single() } - /// Add a duration in [`Days`] to the date part of the `DateTime` + /// Add a duration in [`Days`] to the date part of the `DateTime`. /// - /// Returns `None` if the resulting date would be out of range. + /// # Errors + /// + /// Returns `None` if: + /// - The resulting date would be out of range. + /// - The local time at the resulting date does not exist or is ambiguous, for example during a + /// daylight saving time transition. #[must_use] pub fn checked_add_days(self, days: Days) -> Option { self.naive_local() @@ -394,9 +422,14 @@ impl DateTime { .single() } - /// Subtract a duration in [`Days`] from the date part of the `DateTime` + /// Subtract a duration in [`Days`] from the date part of the `DateTime`. /// - /// Returns `None` if the resulting date would be out of range. + /// # Errors + /// + /// Returns `None` if: + /// - The resulting date would be out of range. + /// - The local time at the resulting date does not exist or is ambiguous, for example during a + /// daylight saving time transition. #[must_use] pub fn checked_sub_days(self, days: Days) -> Option { self.naive_local() @@ -421,6 +454,12 @@ impl DateTime { } /// Returns a view to the naive local datetime. + /// + /// # Panics + /// + /// [`DateTime`] internally stores the date and time in UTC with a [`NaiveDateTime`]. This + /// method will panic if the offset from UTC would push the local datetime outside of the + /// representable range of a [`NaiveDateTime`]. #[inline] #[must_use] pub fn naive_local(&self) -> NaiveDateTime { @@ -428,6 +467,10 @@ impl DateTime { } /// Retrieve the elapsed years from now to the given [`DateTime`]. + /// + /// # Errors + /// + /// Returns `None` if `base < self`. #[must_use] pub fn years_since(&self, base: Self) -> Option { let mut years = self.year() - base.year(); @@ -659,6 +702,11 @@ where Tz::Offset: fmt::Display, { /// Returns an RFC 2822 date and time string such as `Tue, 1 Jul 2003 10:52:37 +0200`. + /// + /// # Panics + /// + /// Panics if the date can not be represented in this format: the year may not be negative and + /// can not have more than 4 digits. #[cfg(any(feature = "alloc", feature = "std", test))] #[cfg_attr(docsrs, doc(cfg(any(feature = "alloc", feature = "std"))))] #[must_use] @@ -864,35 +912,112 @@ impl Datelike for DateTime { } #[inline] + /// Makes a new `DateTime` with the year number changed, while keeping the same month and day. + /// + /// See also the [`NaiveDate::with_year`] method. + /// + /// # Errors + /// + /// Returns `None` if: + /// - The resulting date does not exist. + /// - When the `NaiveDateTime` would be out of range. + /// - The local time at the resulting date does not exist or is ambiguous, for example during a + /// daylight saving time transition. fn with_year(&self, year: i32) -> Option> { map_local(self, |datetime| datetime.with_year(year)) } + /// Makes a new `DateTime` with the month number (starting from 1) changed. + /// + /// See also the [`NaiveDate::with_month`] method. + /// + /// # Errors + /// + /// Returns `None` if: + /// - The resulting date does not exist. + /// - The value for `month` is invalid. + /// - The local time at the resulting date does not exist or is ambiguous, for example during a + /// daylight saving time transition. #[inline] fn with_month(&self, month: u32) -> Option> { map_local(self, |datetime| datetime.with_month(month)) } + /// Makes a new `DateTime` with the month number (starting from 0) changed. + /// + /// See also the [`NaiveDate::with_month0`] method. + /// + /// # Errors + /// + /// Returns `None` if: + /// - The resulting date does not exist. + /// - The value for `month0` is invalid. + /// - The local time at the resulting date does not exist or is ambiguous, for example during a + /// daylight saving time transition. #[inline] fn with_month0(&self, month0: u32) -> Option> { map_local(self, |datetime| datetime.with_month0(month0)) } + /// Makes a new `DateTime` with the month number (starting from 0) changed. + /// + /// See also the [`NaiveDate::with_day`] method. + /// + /// # Errors + /// + /// Returns `None` if: + /// - The resulting date does not exist. + /// - The value for `day` is invalid. + /// - The local time at the resulting date does not exist or is ambiguous, for example during a + /// daylight saving time transition. #[inline] fn with_day(&self, day: u32) -> Option> { map_local(self, |datetime| datetime.with_day(day)) } + /// Makes a new `DateTime` with the month number (starting from 0) changed. + /// + /// See also the [`NaiveDate::with_day0`] method. + /// + /// # Errors + /// + /// Returns `None` if: + /// - The resulting date does not exist. + /// - The value for `day0` is invalid. + /// - The local time at the resulting date does not exist or is ambiguous, for example during a + /// daylight saving time transition. #[inline] fn with_day0(&self, day0: u32) -> Option> { map_local(self, |datetime| datetime.with_day0(day0)) } + /// Makes a new `DateTime` with the month number (starting from 0) changed. + /// + /// See also the [`NaiveDate::with_ordinal`] method. + /// + /// # Errors + /// + /// Returns `None` if: + /// - The resulting date does not exist. + /// - The value for `ordinal` is invalid. + /// - The local time at the resulting date does not exist or is ambiguous, for example during a + /// daylight saving time transition. #[inline] fn with_ordinal(&self, ordinal: u32) -> Option> { map_local(self, |datetime| datetime.with_ordinal(ordinal)) } + /// Makes a new `DateTime` with the month number (starting from 0) changed. + /// + /// See also the [`NaiveDate::with_ordinal0`] method. + /// + /// # Errors + /// + /// Returns `None` if: + /// - The resulting date does not exist. + /// - The value for `ordinal0` is invalid. + /// - The local time at the resulting date does not exist or is ambiguous, for example during a + /// daylight saving time transition. #[inline] fn with_ordinal0(&self, ordinal0: u32) -> Option> { map_local(self, |datetime| datetime.with_ordinal0(ordinal0)) @@ -917,21 +1042,64 @@ impl Timelike for DateTime { self.naive_local().nanosecond() } + /// Makes a new `DateTime` with the hour number changed. + /// + /// See also the [`NaiveTime::with_hour`] method. + /// + /// # Errors + /// + /// Returns `None` if: + /// - The value for `hour` is invalid. + /// - The local time at the resulting date does not exist or is ambiguous, for example during a + /// daylight saving time transition. #[inline] fn with_hour(&self, hour: u32) -> Option> { map_local(self, |datetime| datetime.with_hour(hour)) } + /// Makes a new `DateTime` with the minute number changed. + /// + /// See also the [`NaiveTime::with_minute`] method. + /// + /// # Errors + /// + /// - The value for `minute` is invalid. + /// - The local time at the resulting date does not exist or is ambiguous, for example during a + /// daylight saving time transition. #[inline] fn with_minute(&self, min: u32) -> Option> { map_local(self, |datetime| datetime.with_minute(min)) } + /// Makes a new `DateTime` with the second number changed. + /// + /// As with the [`second`](#method.second) method, + /// the input range is restricted to 0 through 59. + /// + /// See also the [`NaiveTime::with_second`] method. + /// + /// # Errors + /// + /// Returns `None` if: + /// - The value for `second` is invalid. + /// - The local time at the resulting date does not exist or is ambiguous, for example during a + /// daylight saving time transition. #[inline] fn with_second(&self, sec: u32) -> Option> { map_local(self, |datetime| datetime.with_second(sec)) } + /// Makes a new `DateTime` with nanoseconds since the whole non-leap second changed. + /// + /// Returns `None` when the resulting `NaiveDateTime` would be invalid. + /// As with the [`NaiveDateTime::nanosecond`] method, + /// the input range can exceed 1,000,000,000 for leap seconds. + /// + /// See also the [`NaiveTime::with_nanosecond`] method. + /// + /// # Errors + /// + /// Returns `None` if `nanosecond >= 2,000,000,000`. #[inline] fn with_nanosecond(&self, nano: u32) -> Option> { map_local(self, |datetime| datetime.with_nanosecond(nano)) diff --git a/src/naive/date.rs b/src/naive/date.rs index b9404a15f5..3f5730f10c 100644 --- a/src/naive/date.rs +++ b/src/naive/date.rs @@ -66,6 +66,11 @@ pub struct NaiveWeek { impl NaiveWeek { /// Returns a date representing the first day of the week. /// + /// # Panics + /// + /// Panics if the first day of the week happens to fall just out of range of `NaiveDate` + /// (more than ca. 262,000 years away from common era). + /// /// # Examples /// /// ``` @@ -89,6 +94,11 @@ impl NaiveWeek { /// Returns a date representing the last day of the week. /// + /// # Panics + /// + /// Panics if the last day of the week happens to fall just out of range of `NaiveDate` + /// (more than ca. 262,000 years away from common era). + /// /// # Examples /// /// ``` @@ -114,6 +124,11 @@ impl NaiveWeek { /// [first_day](./struct.NaiveWeek.html#method.first_day) and /// [last_day](./struct.NaiveWeek.html#method.last_day) functions. /// + /// # Panics + /// + /// Panics if the either the first or last day of the week happens to fall just out of range of + /// `NaiveDate` (more than ca. 262,000 years away from common era). + /// /// # Examples /// /// ``` @@ -285,7 +300,10 @@ impl NaiveDate { /// Makes a new `NaiveDate` from the [calendar date](#calendar-date) /// (year, month and day). /// - /// Panics on the out-of-range date, invalid month and/or day. + /// # Panics + /// + /// Panics if the specified calendar day does not exist, on invalid values for `month` or `day`, + /// or if `year` is out of range for `NaiveDate`. #[deprecated(since = "0.4.23", note = "use `from_ymd_opt()` instead")] #[must_use] pub fn from_ymd(year: i32, month: u32, day: u32) -> NaiveDate { @@ -295,7 +313,12 @@ impl NaiveDate { /// Makes a new `NaiveDate` from the [calendar date](#calendar-date) /// (year, month and day). /// - /// Returns `None` on the out-of-range date, invalid month and/or day. + /// # Errors + /// + /// Returns `None` if: + /// - The specified calendar day does not exist (for example 2023-04-31). + /// - The value for `month` or `day` is invalid. + /// - `year` is out of range for `NaiveDate`. /// /// # Example /// @@ -320,7 +343,10 @@ impl NaiveDate { /// Makes a new `NaiveDate` from the [ordinal date](#ordinal-date) /// (year and day of the year). /// - /// Panics on the out-of-range date and/or invalid day of year. + /// # Panics + /// + /// Panics if the specified ordinal day does not exist, on invalid values for `ordinal`, or if + /// `year` is out of range for `NaiveDate`. #[deprecated(since = "0.4.23", note = "use `from_yo_opt()` instead")] #[must_use] pub fn from_yo(year: i32, ordinal: u32) -> NaiveDate { @@ -330,7 +356,12 @@ impl NaiveDate { /// Makes a new `NaiveDate` from the [ordinal date](#ordinal-date) /// (year and day of the year). /// - /// Returns `None` on the out-of-range date and/or invalid day of year. + /// # Errors + /// + /// Returns `None` if: + /// - The specified ordinal day does not exist (for example 2023-366). + /// - The value for `ordinal` is invalid (for example: `0`, `400`). + /// - `year` is out of range for `NaiveDate`. /// /// # Example /// @@ -357,7 +388,10 @@ impl NaiveDate { /// (year, week number and day of the week). /// The resulting `NaiveDate` may have a different year from the input year. /// - /// Panics on the out-of-range date and/or invalid week number. + /// # Panics + /// + /// Panics if the specified week does not exist in that year, on invalid values for `week`, or + /// if the resulting date is out of range for `NaiveDate`. #[deprecated(since = "0.4.23", note = "use `from_isoywd_opt()` instead")] #[must_use] pub fn from_isoywd(year: i32, week: u32, weekday: Weekday) -> NaiveDate { @@ -368,7 +402,12 @@ impl NaiveDate { /// (year, week number and day of the week). /// The resulting `NaiveDate` may have a different year from the input year. /// - /// Returns `None` on the out-of-range date and/or invalid week number. + /// # Errors + /// + /// Returns `None` if: + /// - The specified week does not exist in that year (for example 2023 week 53). + /// - The value for `week` is invalid (for example: `0`, `60`). + /// - If the resulting date is out of range for `NaiveDate`. /// /// # Example /// @@ -444,6 +483,8 @@ impl NaiveDate { /// Makes a new `NaiveDate` from a day's number in the proleptic Gregorian calendar, with /// January 1, 1 being day 1. /// + /// # Panics + /// /// Panics if the date is out of range. #[deprecated(since = "0.4.23", note = "use `from_num_days_from_ce_opt()` instead")] #[inline] @@ -455,6 +496,8 @@ impl NaiveDate { /// Makes a new `NaiveDate` from a day's number in the proleptic Gregorian calendar, with /// January 1, 1 being day 1. /// + /// # Errors + /// /// Returns `None` if the date is out of range. /// /// # Example @@ -482,15 +525,15 @@ impl NaiveDate { } /// Makes a new `NaiveDate` by counting the number of occurrences of a particular day-of-week - /// since the beginning of the given month. For instance, if you want the 2nd Friday of March + /// since the beginning of the given month. For instance, if you want the 2nd Friday of March /// 2017, you would use `NaiveDate::from_weekday_of_month(2017, 3, Weekday::Fri, 2)`. /// - /// # Panics + /// `n` is 1-indexed. /// - /// The resulting `NaiveDate` is guaranteed to be in `month`. If `n` is larger than the number - /// of `weekday` in `month` (eg. the 6th Friday of March 2017) then this function will panic. + /// # Panics /// - /// `n` is 1-indexed. Passing `n=0` will cause a panic. + /// Panics if the specified day does not exist in that month, on invalid values for `month` or + /// `n`, or if `year` is out of range for `NaiveDate`. #[deprecated(since = "0.4.23", note = "use `from_weekday_of_month_opt()` instead")] #[must_use] pub fn from_weekday_of_month(year: i32, month: u32, weekday: Weekday, n: u8) -> NaiveDate { @@ -498,17 +541,25 @@ impl NaiveDate { } /// Makes a new `NaiveDate` by counting the number of occurrences of a particular day-of-week - /// since the beginning of the given month. For instance, if you want the 2nd Friday of March - /// 2017, you would use `NaiveDate::from_weekday_of_month(2017, 3, Weekday::Fri, 2)`. `n` is 1-indexed. + /// since the beginning of the given month. For instance, if you want the 2nd Friday of March + /// 2017, you would use `NaiveDate::from_weekday_of_month(2017, 3, Weekday::Fri, 2)`. + /// + /// `n` is 1-indexed. + /// + /// # Errors + /// + /// Returns `None` if: + /// - The specified day does not exist in that month (for example the 5th Monday of Apr. 2023). + /// - The value for `month` or `n` is invalid. + /// - `year` is out of range for `NaiveDate`. + /// + /// # Example /// /// ``` /// use chrono::{NaiveDate, Weekday}; /// assert_eq!(NaiveDate::from_weekday_of_month_opt(2017, 3, Weekday::Fri, 2), /// NaiveDate::from_ymd_opt(2017, 3, 10)) /// ``` - /// - /// Returns `None` if `n` out-of-range; ie. if `n` is larger than the number of `weekday` in - /// `month` (eg. the 6th Friday of March 2017), or if `n == 0`. #[must_use] pub fn from_weekday_of_month_opt( year: i32, @@ -597,10 +648,14 @@ impl NaiveDate { /// Add a duration in [`Months`] to the date /// - /// If the day would be out of range for the resulting month, use the last day for that month. + /// Uses the last day of the month if the day does not exist in the resulting month. + /// + /// # Errors /// /// Returns `None` if the resulting date would be out of range. /// + /// # Example + /// /// ``` /// # use chrono::{NaiveDate, Months}; /// assert_eq!( @@ -626,10 +681,14 @@ impl NaiveDate { /// Subtract a duration in [`Months`] from the date /// - /// If the day would be out of range for the resulting month, use the last day for that month. + /// Uses the last day of the month if the day does not exist in the resulting month. + /// + /// # Errors /// /// Returns `None` if the resulting date would be out of range. /// + /// # Example + /// /// ``` /// # use chrono::{NaiveDate, Months}; /// assert_eq!( @@ -700,8 +759,12 @@ impl NaiveDate { /// Add a duration in [`Days`] to the date /// + /// # Errors + /// /// Returns `None` if the resulting date would be out of range. /// + /// # Example + /// /// ``` /// # use chrono::{NaiveDate, Days}; /// assert_eq!( @@ -728,8 +791,12 @@ impl NaiveDate { /// Subtract a duration in [`Days`] from the date /// + /// # Errors + /// /// Returns `None` if the resulting date would be out of range. /// + /// # Example + /// /// ``` /// # use chrono::{NaiveDate, Days}; /// assert_eq!( @@ -783,6 +850,8 @@ impl NaiveDate { /// No [leap second](./struct.NaiveTime.html#leap-second-handling) is allowed here; /// use `NaiveDate::and_hms_*` methods with a subsecond parameter instead. /// + /// # Panics + /// /// Panics on invalid hour, minute and/or second. #[deprecated(since = "0.4.23", note = "use `and_hms_opt()` instead")] #[inline] @@ -796,6 +865,8 @@ impl NaiveDate { /// No [leap second](./struct.NaiveTime.html#leap-second-handling) is allowed here; /// use `NaiveDate::and_hms_*_opt` methods with a subsecond parameter instead. /// + /// # Errors + /// /// Returns `None` on invalid hour, minute and/or second. /// /// # Example @@ -820,6 +891,8 @@ impl NaiveDate { /// The millisecond part can exceed 1,000 /// in order to represent the [leap second](./struct.NaiveTime.html#leap-second-handling). /// + /// # Panics + /// /// Panics on invalid hour, minute, second and/or millisecond. #[deprecated(since = "0.4.23", note = "use `and_hms_milli_opt()` instead")] #[inline] @@ -833,6 +906,8 @@ impl NaiveDate { /// The millisecond part can exceed 1,000 /// in order to represent the [leap second](./struct.NaiveTime.html#leap-second-handling). /// + /// # Errors + /// /// Returns `None` on invalid hour, minute, second and/or millisecond. /// /// # Example @@ -865,6 +940,8 @@ impl NaiveDate { /// The microsecond part can exceed 1,000,000 /// in order to represent the [leap second](./struct.NaiveTime.html#leap-second-handling). /// + /// # Panics + /// /// Panics on invalid hour, minute, second and/or microsecond. /// /// # Example @@ -892,6 +969,8 @@ impl NaiveDate { /// The microsecond part can exceed 1,000,000 /// in order to represent the [leap second](./struct.NaiveTime.html#leap-second-handling). /// + /// # Errors + /// /// Returns `None` on invalid hour, minute, second and/or microsecond. /// /// # Example @@ -924,6 +1003,8 @@ impl NaiveDate { /// The nanosecond part can exceed 1,000,000,000 /// in order to represent the [leap second](./struct.NaiveTime.html#leap-second-handling). /// + /// # Panics + /// /// Panics on invalid hour, minute, second and/or nanosecond. #[deprecated(since = "0.4.23", note = "use `and_hms_nano_opt()` instead")] #[inline] @@ -937,6 +1018,8 @@ impl NaiveDate { /// The nanosecond part can exceed 1,000,000,000 /// in order to represent the [leap second](./struct.NaiveTime.html#leap-second-handling). /// + /// # Errors + /// /// Returns `None` on invalid hour, minute, second and/or nanosecond. /// /// # Example @@ -995,6 +1078,8 @@ impl NaiveDate { /// Makes a new `NaiveDate` for the next calendar date. /// + /// # Panics + /// /// Panics when `self` is the last representable date. #[deprecated(since = "0.4.23", note = "use `succ_opt()` instead")] #[inline] @@ -1005,6 +1090,8 @@ impl NaiveDate { /// Makes a new `NaiveDate` for the next calendar date. /// + /// # Errors + /// /// Returns `None` when `self` is the last representable date. /// /// # Example @@ -1027,6 +1114,8 @@ impl NaiveDate { /// Makes a new `NaiveDate` for the previous calendar date. /// + /// # Panics + /// /// Panics when `self` is the first representable date. #[deprecated(since = "0.4.23", note = "use `pred_opt()` instead")] #[inline] @@ -1037,6 +1126,8 @@ impl NaiveDate { /// Makes a new `NaiveDate` for the previous calendar date. /// + /// # Errors + /// /// Returns `None` when `self` is the first representable date. /// /// # Example @@ -1057,9 +1148,11 @@ impl NaiveDate { } } - /// Adds the `days` part of given `Duration` to the current date. + /// Adds the number of whole days in the given `Duration` to the current date. /// - /// Returns `None` when it will result in overflow. + /// # Errors + /// + /// Returns `None` if the resulting date would be out of range. /// /// # Example /// @@ -1089,9 +1182,11 @@ impl NaiveDate { NaiveDate::from_ordinal_and_flags(year_div_400 * 400 + year_mod_400 as i32, ordinal, flags) } - /// Subtracts the `days` part of given `Duration` from the current date. + /// Subtracts the number of whole days in the given `Duration` from the current date. /// - /// Returns `None` when it will result in overflow. + /// # Errors + /// + /// Returns `None` if the resulting date would be out of range. /// /// # Example /// @@ -1157,6 +1252,10 @@ impl NaiveDate { } /// Returns the number of whole years from the given `base` until `self`. + /// + /// # Errors + /// + /// Returns `None` if `base < self`. #[must_use] pub fn years_since(&self, base: Self) -> Option { let mut years = self.year() - base.year(); @@ -1540,9 +1639,12 @@ impl Datelike for NaiveDate { isoweek::iso_week_from_yof(self.year(), self.of()) } - /// Makes a new `NaiveDate` with the year number changed. + /// Makes a new `NaiveDate` with the year number changed, while keeping the same month and day. /// - /// Returns `None` when the resulting `NaiveDate` would be invalid. + /// # Errors + /// + /// Returns `None` if the resulting date does not exist, or when the `NaiveDate` would be + /// out of range. /// /// # Example /// @@ -1576,7 +1678,9 @@ impl Datelike for NaiveDate { /// Makes a new `NaiveDate` with the month number (starting from 1) changed. /// - /// Returns `None` when the resulting `NaiveDate` would be invalid. + /// # Errors + /// + /// Returns `None` if the resulting date does not exist, or if the value for `month` is invalid. /// /// # Example /// @@ -1595,7 +1699,10 @@ impl Datelike for NaiveDate { /// Makes a new `NaiveDate` with the month number (starting from 0) changed. /// - /// Returns `None` when the resulting `NaiveDate` would be invalid. + /// # Errors + /// + /// Returns `None` if the resulting date does not exist, or if the value for `month0` is + /// invalid. /// /// # Example /// @@ -1615,7 +1722,9 @@ impl Datelike for NaiveDate { /// Makes a new `NaiveDate` with the day of month (starting from 1) changed. /// - /// Returns `None` when the resulting `NaiveDate` would be invalid. + /// # Errors + /// + /// Returns `None` if the resulting date does not exist, or if the value for `day` is invalid. /// /// # Example /// @@ -1634,7 +1743,9 @@ impl Datelike for NaiveDate { /// Makes a new `NaiveDate` with the day of month (starting from 0) changed. /// - /// Returns `None` when the resulting `NaiveDate` would be invalid. + /// # Errors + /// + /// Returns `None` if the resulting date does not exist, or if the value for `day0` is invalid. /// /// # Example /// @@ -1654,7 +1765,10 @@ impl Datelike for NaiveDate { /// Makes a new `NaiveDate` with the day of year (starting from 1) changed. /// - /// Returns `None` when the resulting `NaiveDate` would be invalid. + /// # Errors + /// + /// Returns `None` if the resulting date does not exist, or if the value for `ordinal` is + /// invalid. /// /// # Example /// @@ -1678,7 +1792,10 @@ impl Datelike for NaiveDate { /// Makes a new `NaiveDate` with the day of year (starting from 0) changed. /// - /// Returns `None` when the resulting `NaiveDate` would be invalid. + /// # Errors + /// + /// Returns `None` if the resulting date does not exist, or if the value for `ordinal0` is + /// invalid. /// /// # Example /// diff --git a/src/naive/datetime/mod.rs b/src/naive/datetime/mod.rs index 0a3f70380e..9c36cb1b77 100644 --- a/src/naive/datetime/mod.rs +++ b/src/naive/datetime/mod.rs @@ -113,7 +113,11 @@ impl NaiveDateTime { /// [leap second](./struct.NaiveTime.html#leap-second-handling). (The true "UNIX /// timestamp" cannot represent a leap second unambiguously.) /// - /// Panics on the out-of-range number of seconds and/or invalid nanosecond. + /// # Panics + /// + /// Panics if the number of seconds would be out of range for a `NaiveDateTime` (more than + /// ca. 262,000 years away from common era), and panics on an invalid nanosecond (2 seconds or + /// more). #[deprecated(since = "0.4.23", note = "use `from_timestamp_opt()` instead")] #[inline] #[must_use] @@ -126,7 +130,10 @@ impl NaiveDateTime { /// /// The UNIX epoch starts on midnight, January 1, 1970, UTC. /// - /// Returns `None` on an out-of-range number of milliseconds. + /// # Errors + /// + /// Returns `None` if the number of milliseconds would be out of range for a `NaiveDateTime` + /// (more than ca. 262,000 years away from common era) /// /// # Example /// @@ -155,7 +162,10 @@ impl NaiveDateTime { /// /// The UNIX epoch starts on midnight, January 1, 1970, UTC. /// - /// Returns `None` on an out-of-range number of microseconds. + /// # Errors + /// + /// Returns `None` if the number of microseconds would be out of range for a `NaiveDateTime` + /// (more than ca. 262,000 years away from common era) /// /// # Example /// @@ -189,8 +199,11 @@ impl NaiveDateTime { /// in order to represent the [leap second](./struct.NaiveTime.html#leap-second-handling). /// (The true "UNIX timestamp" cannot represent a leap second unambiguously.) /// - /// Returns `None` on the out-of-range number of seconds (more than 262 000 years away - /// from common era) and/or invalid nanosecond (2 seconds or more). + /// # Errors + /// + /// Returns `None` if the number of seconds would be out of range for a `NaiveDateTime` (more + /// than ca. 262,000 years away from common era), and panics on an invalid nanosecond + /// (2 seconds or more). /// /// # Example /// @@ -390,11 +403,6 @@ 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. /// - /// Note also that this does reduce the number of years that can be - /// represented from ~584 Billion to ~584 Million. (If this is a problem, - /// please file an issue to let me know what domain needs millisecond - /// precision over billions of years, I'm curious.) - /// /// # Example /// /// ``` @@ -421,11 +429,6 @@ 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. /// - /// Note also that this does reduce the number of years that can be - /// represented from ~584 Billion to ~584 Thousand. (If this is a problem, - /// please file an issue to let me know what domain needs microsecond - /// precision over millennia, I'm curious.) - /// /// # Example /// /// ``` @@ -451,13 +454,11 @@ impl NaiveDateTime { /// /// # Panics /// - /// Note also that this does reduce the number of years that can be - /// 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. + /// An `i64` with nanosecond precision can span a range of ~584 years. This function panics on + /// an out of range `NaiveDateTime`. /// - /// (If this is a problem, please file an issue to let me know what domain - /// needs nanosecond precision over millennia, I'm curious.) + /// The dates that can be represented as nanoseconds are between 1677-09-21T00:12:44.0 and + /// 2262-04-11T23:47:16.854775804. /// /// # Example /// @@ -557,7 +558,9 @@ impl NaiveDateTime { /// except when the `NaiveDateTime` itself represents a leap second /// in which case the assumption becomes that **there is exactly a single leap second ever**. /// - /// Returns `None` when it will result in overflow. + /// # Errors + /// + /// Returns `None` if the resulting date would be out of range. /// /// # Example /// @@ -630,9 +633,11 @@ impl NaiveDateTime { /// Adds given `Months` to the current date and time. /// - /// Returns `None` when it will result in overflow. + /// Uses the last day of the month if the day does not exist in the resulting month. /// - /// Overflow returns `None`. + /// # Errors + /// + /// Returns `None` if the resulting date would be out of range. /// /// # Example /// @@ -663,7 +668,9 @@ impl NaiveDateTime { /// except when the `NaiveDateTime` itself represents a leap second /// in which case the assumption becomes that **there is exactly a single leap second ever**. /// - /// Returns `None` when it will result in overflow. + /// # Errors + /// + /// Returns `None` if the resulting date would be out of range. /// /// # Example /// @@ -732,9 +739,11 @@ impl NaiveDateTime { /// Subtracts given `Months` from the current date and time. /// - /// Returns `None` when it will result in overflow. + /// Uses the last day of the month if the day does not exist in the resulting month. /// - /// Overflow returns `None`. + /// # Errors + /// + /// Returns `None` if the resulting date would be out of range. /// /// # Example /// @@ -1095,12 +1104,16 @@ impl Datelike for NaiveDateTime { self.date.iso_week() } - /// Makes a new `NaiveDateTime` with the year number changed. - /// - /// Returns `None` when the resulting `NaiveDateTime` would be invalid. + /// Makes a new `NaiveDateTime` with the year number changed, while keeping the same month and + /// day. /// /// See also the [`NaiveDate::with_year`] method. /// + /// # Errors + /// + /// Returns `None` if the resulting date does not exist, or when the `NaiveDateTime` would be + /// out of range. + /// /// # Example /// /// ``` @@ -1117,10 +1130,12 @@ impl Datelike for NaiveDateTime { /// Makes a new `NaiveDateTime` with the month number (starting from 1) changed. /// - /// Returns `None` when the resulting `NaiveDateTime` would be invalid. - /// /// See also the [`NaiveDate::with_month`] method. /// + /// # Errors + /// + /// Returns `None` if the resulting date does not exist, or if the value for `month` is invalid. + /// /// # Example /// /// ``` @@ -1138,10 +1153,13 @@ impl Datelike for NaiveDateTime { /// Makes a new `NaiveDateTime` with the month number (starting from 0) changed. /// - /// Returns `None` when the resulting `NaiveDateTime` would be invalid. - /// /// See also the [`NaiveDate::with_month0`] method. /// + /// # Errors + /// + /// Returns `None` if the resulting date does not exist, or if the value for `month0` is + /// invalid. + /// /// # Example /// /// ``` @@ -1159,10 +1177,12 @@ impl Datelike for NaiveDateTime { /// Makes a new `NaiveDateTime` with the day of month (starting from 1) changed. /// - /// Returns `None` when the resulting `NaiveDateTime` would be invalid. - /// /// See also the [`NaiveDate::with_day`] method. /// + /// # Errors + /// + /// Returns `None` if the resulting date does not exist, or if the value for `day` is invalid. + /// /// # Example /// /// ``` @@ -1179,10 +1199,12 @@ impl Datelike for NaiveDateTime { /// Makes a new `NaiveDateTime` with the day of month (starting from 0) changed. /// - /// Returns `None` when the resulting `NaiveDateTime` would be invalid. - /// /// See also the [`NaiveDate::with_day0`] method. /// + /// # Errors + /// + /// Returns `None` if the resulting date does not exist, or if the value for `day0` is invalid. + /// /// # Example /// /// ``` @@ -1199,10 +1221,13 @@ impl Datelike for NaiveDateTime { /// Makes a new `NaiveDateTime` with the day of year (starting from 1) changed. /// - /// Returns `None` when the resulting `NaiveDateTime` would be invalid. - /// /// See also the [`NaiveDate::with_ordinal`] method. /// + /// # Errors + /// + /// Returns `None` if the resulting date does not exist, or if the value for `ordinal` is + /// invalid. + /// /// # Example /// /// ``` @@ -1226,10 +1251,13 @@ impl Datelike for NaiveDateTime { /// Makes a new `NaiveDateTime` with the day of year (starting from 0) changed. /// - /// Returns `None` when the resulting `NaiveDateTime` would be invalid. - /// /// See also the [`NaiveDate::with_ordinal0`] method. /// + /// # Errors + /// + /// Returns `None` if the resulting date does not exist, or if the value for `ordinal0` is + /// invalid. + /// /// # Example /// /// ``` @@ -1325,10 +1353,12 @@ impl Timelike for NaiveDateTime { /// Makes a new `NaiveDateTime` with the hour number changed. /// - /// Returns `None` when the resulting `NaiveDateTime` would be invalid. - /// /// See also the [`NaiveTime::with_hour`] method. /// + /// # Errors + /// + /// Returns `None` if the value for `hour` is invalid. + /// /// # Example /// /// ``` @@ -1346,10 +1376,11 @@ impl Timelike for NaiveDateTime { /// Makes a new `NaiveDateTime` with the minute number changed. /// - /// Returns `None` when the resulting `NaiveDateTime` would be invalid. + /// See also the [`NaiveTime::with_minute`] method. /// - /// See also the - /// [`NaiveTime::with_minute`] method. + /// # Errors + /// + /// Returns `None` if the value for `minute` is invalid. /// /// # Example /// @@ -1368,12 +1399,15 @@ impl Timelike for NaiveDateTime { /// Makes a new `NaiveDateTime` with the second number changed. /// - /// Returns `None` when the resulting `NaiveDateTime` would be invalid. As - /// with the [`NaiveDateTime::second`] method, the input range is - /// restricted to 0 through 59. + /// As with the [`second`](#method.second) method, + /// the input range is restricted to 0 through 59. /// /// See also the [`NaiveTime::with_second`] method. /// + /// # Errors + /// + /// Returns `None` if the value for `second` is invalid. + /// /// # Example /// /// ``` @@ -1397,6 +1431,10 @@ impl Timelike for NaiveDateTime { /// /// See also the [`NaiveTime::with_nanosecond`] method. /// + /// # Errors + /// + /// Returns `None` if `nanosecond >= 2,000,000,000`. + /// /// # Example /// /// ``` @@ -1421,7 +1459,9 @@ impl Timelike for NaiveDateTime { /// second ever**, except when the `NaiveDateTime` itself represents a leap second in which case /// the assumption becomes that **there is exactly a single leap second ever**. /// -/// Panics on underflow or overflow. Use [`NaiveDateTime::checked_add_signed`] +/// # Panics +/// +/// Panics if the resulting date would be out of range. Use [`NaiveDateTime::checked_add_signed`] /// to detect that. /// /// # Example diff --git a/src/naive/time/mod.rs b/src/naive/time/mod.rs index 3700c5cba2..328f2cbf76 100644 --- a/src/naive/time/mod.rs +++ b/src/naive/time/mod.rs @@ -212,6 +212,8 @@ impl NaiveTime { /// No [leap second](#leap-second-handling) is allowed here; /// use `NaiveTime::from_hms_*` methods with a subsecond parameter instead. /// + /// # Panics + /// /// Panics on invalid hour, minute and/or second. #[deprecated(since = "0.4.23", note = "use `from_hms_opt()` instead")] #[inline] @@ -225,6 +227,8 @@ impl NaiveTime { /// No [leap second](#leap-second-handling) is allowed here; /// use `NaiveTime::from_hms_*_opt` methods with a subsecond parameter instead. /// + /// # Errors + /// /// Returns `None` on invalid hour, minute and/or second. /// /// # Example @@ -251,6 +255,8 @@ impl NaiveTime { /// The millisecond part can exceed 1,000 /// in order to represent the [leap second](#leap-second-handling). /// + /// # Panics + /// /// Panics on invalid hour, minute, second and/or millisecond. #[deprecated(since = "0.4.23", note = "use `from_hms_milli_opt()` instead")] #[inline] @@ -264,6 +270,8 @@ impl NaiveTime { /// The millisecond part can exceed 1,000 /// in order to represent the [leap second](#leap-second-handling). /// + /// # Errors + /// /// Returns `None` on invalid hour, minute, second and/or millisecond. /// /// # Example @@ -294,6 +302,8 @@ impl NaiveTime { /// The microsecond part can exceed 1,000,000 /// in order to represent the [leap second](#leap-second-handling). /// + /// # Panics + /// /// Panics on invalid hour, minute, second and/or microsecond. #[deprecated(since = "0.4.23", note = "use `from_hms_micro_opt()` instead")] #[inline] @@ -307,6 +317,8 @@ impl NaiveTime { /// The microsecond part can exceed 1,000,000 /// in order to represent the [leap second](#leap-second-handling). /// + /// # Errors + /// /// Returns `None` on invalid hour, minute, second and/or microsecond. /// /// # Example @@ -335,6 +347,8 @@ impl NaiveTime { /// The nanosecond part can exceed 1,000,000,000 /// in order to represent the [leap second](#leap-second-handling). /// + /// # Panics + /// /// Panics on invalid hour, minute, second and/or nanosecond. #[deprecated(since = "0.4.23", note = "use `from_hms_nano_opt()` instead")] #[inline] @@ -348,6 +362,8 @@ impl NaiveTime { /// The nanosecond part can exceed 1,000,000,000 /// in order to represent the [leap second](#leap-second-handling). /// + /// # Errors + /// /// Returns `None` on invalid hour, minute, second and/or nanosecond. /// /// # Example @@ -380,6 +396,8 @@ impl NaiveTime { /// The nanosecond part can exceed 1,000,000,000 /// in order to represent the [leap second](#leap-second-handling). /// + /// # Panics + /// /// Panics on invalid number of seconds and/or nanosecond. #[deprecated(since = "0.4.23", note = "use `from_num_seconds_from_midnight_opt()` instead")] #[inline] @@ -393,6 +411,8 @@ impl NaiveTime { /// The nanosecond part can exceed 1,000,000,000 /// in order to represent the [leap second](#leap-second-handling). /// + /// # Errors + /// /// Returns `None` on invalid number of seconds and/or nanosecond. /// /// # Example @@ -506,10 +526,8 @@ impl NaiveTime { parsed.to_naive_time().map(|t| (t, remainder)) } - /// Adds given `Duration` to the current time, - /// and also returns the number of *seconds* + /// Adds given `Duration` to the current time, and also returns the number of *seconds* /// in the integral number of days ignored from the addition. - /// (We cannot return `Duration` because it is subject to overflow or underflow.) /// /// # Example /// @@ -589,10 +607,8 @@ impl NaiveTime { (NaiveTime { secs: secs as u32, frac: frac as u32 }, morerhssecs) } - /// Subtracts given `Duration` from the current time, - /// and also returns the number of *seconds* + /// Subtracts given `Duration` from the current time, and also returns the number of *seconds* /// in the integral number of days ignored from the subtraction. - /// (We cannot return `Duration` because it is subject to overflow or underflow.) /// /// # Example /// @@ -886,7 +902,9 @@ impl Timelike for NaiveTime { /// Makes a new `NaiveTime` with the hour number changed. /// - /// Returns `None` when the resulting `NaiveTime` would be invalid. + /// # Errors + /// + /// Returns `None` if the value for `hour` is invalid. /// /// # Example /// @@ -908,7 +926,9 @@ impl Timelike for NaiveTime { /// Makes a new `NaiveTime` with the minute number changed. /// - /// Returns `None` when the resulting `NaiveTime` would be invalid. + /// # Errors + /// + /// Returns `None` if the value for `minute` is invalid. /// /// # Example /// @@ -930,10 +950,13 @@ impl Timelike for NaiveTime { /// Makes a new `NaiveTime` with the second number changed. /// - /// Returns `None` when the resulting `NaiveTime` would be invalid. /// As with the [`second`](#method.second) method, /// the input range is restricted to 0 through 59. /// + /// # Errors + /// + /// Returns `None` if the value for `second` is invalid. + /// /// # Example /// /// ``` @@ -954,10 +977,13 @@ impl Timelike for NaiveTime { /// Makes a new `NaiveTime` with nanoseconds since the whole non-leap second changed. /// - /// Returns `None` when the resulting `NaiveTime` would be invalid. /// As with the [`nanosecond`](#method.nanosecond) method, /// the input range can exceed 1,000,000,000 for leap seconds. /// + /// # Errors + /// + /// Returns `None` if `nanosecond >= 2,000,000,000`. + /// /// # Example /// /// ``` diff --git a/src/traits.rs b/src/traits.rs index a6199dc6dc..22174da209 100644 --- a/src/traits.rs +++ b/src/traits.rs @@ -53,7 +53,7 @@ pub trait Datelike: Sized { /// Returns the ISO week. fn iso_week(&self) -> IsoWeek; - /// Makes a new value with the year number changed. + /// Makes a new value with the year number changed, while keeping the same month and day. /// /// Returns `None` when the resulting value would be invalid. fn with_year(&self, year: i32) -> Option;