From 6d5fa1eb44876d19973eb7679b37b8d0845264b5 Mon Sep 17 00:00:00 2001 From: Garrett Squire Date: Thu, 30 Nov 2023 21:12:06 -0800 Subject: [PATCH] Panic Documentation (#638) --- time/src/date.rs | 12 ++++++++++++ time/src/date_time.rs | 15 +++++++++++++++ time/src/duration.rs | 41 +++++++++++++++++++++++++++++++++++++++++ time/src/ext.rs | 36 ++++++++++++++++++++++++++++++++++++ time/src/instant.rs | 3 +++ 5 files changed, 107 insertions(+) diff --git a/time/src/date.rs b/time/src/date.rs index 5e62dfabc..5f524b1ab 100644 --- a/time/src/date.rs +++ b/time/src/date.rs @@ -1403,6 +1403,9 @@ impl fmt::Debug for Date { impl Add for Date { type Output = Self; + /// # Panics + /// + /// This may panic if an overflow occurs. fn add(self, duration: Duration) -> Self::Output { self.checked_add(duration) .expect("overflow adding duration to date") @@ -1412,6 +1415,9 @@ impl Add for Date { impl Add for Date { type Output = Self; + /// # Panics + /// + /// This may panic if an overflow occurs. fn add(self, duration: StdDuration) -> Self::Output { self.checked_add_std(duration) .expect("overflow adding duration to date") @@ -1423,6 +1429,9 @@ impl_add_assign!(Date: Duration, StdDuration); impl Sub for Date { type Output = Self; + /// # Panics + /// + /// This may panic if an overflow occurs. fn sub(self, duration: Duration) -> Self::Output { self.checked_sub(duration) .expect("overflow subtracting duration from date") @@ -1432,6 +1441,9 @@ impl Sub for Date { impl Sub for Date { type Output = Self; + /// # Panics + /// + /// This may panic if an overflow occurs. fn sub(self, duration: StdDuration) -> Self::Output { self.checked_sub_std(duration) .expect("overflow subtracting duration from date") diff --git a/time/src/date_time.rs b/time/src/date_time.rs index 27f07cec8..f036012a8 100644 --- a/time/src/date_time.rs +++ b/time/src/date_time.rs @@ -1009,6 +1009,9 @@ impl Hash for DateTime { impl Add for DateTime { type Output = Self; + /// # Panics + /// + /// This may panic if an overflow occurs. fn add(self, duration: Duration) -> Self { self.checked_add(duration) .expect("resulting value is out of range") @@ -1018,6 +1021,9 @@ impl Add for DateTime { impl Add for DateTime { type Output = Self; + /// # Panics + /// + /// This may panic if an overflow occurs. fn add(self, duration: StdDuration) -> Self::Output { let (is_next_day, time) = self.time.adjusting_add_std(duration); @@ -1050,6 +1056,9 @@ impl AddAssign for DateTime { impl Sub for DateTime { type Output = Self; + /// # Panics + /// + /// This may panic if an overflow occurs. fn sub(self, duration: Duration) -> Self { self.checked_sub(duration) .expect("resulting value is out of range") @@ -1059,6 +1068,9 @@ impl Sub for DateTime { impl Sub for DateTime { type Output = Self; + /// # Panics + /// + /// This may panic if an overflow occurs. fn sub(self, duration: StdDuration) -> Self::Output { let (is_previous_day, time) = self.time.adjusting_sub_std(duration); @@ -1224,6 +1236,9 @@ impl From> for SystemTime { feature = "wasm-bindgen" ))] impl From for DateTime { + /// # Panics + /// + /// This may panic if the timestamp can not be represented. fn from(js_date: js_sys::Date) -> Self { // get_time() returns milliseconds let timestamp_nanos = (js_date.get_time() * Nanosecond::per(Millisecond) as f64) as i128; diff --git a/time/src/duration.rs b/time/src/duration.rs index 4b4134f9e..57281056e 100644 --- a/time/src/duration.rs +++ b/time/src/duration.rs @@ -380,6 +380,10 @@ impl Duration { /// assert_eq!(Duration::new(-1, 0), (-1).seconds()); /// assert_eq!(Duration::new(1, 2_000_000_000), 3.seconds()); /// ``` + /// + /// # Panics + /// + /// This may panic if an overflow occurs. pub const fn new(mut seconds: i64, mut nanoseconds: i32) -> Self { seconds = expect_opt!( seconds.checked_add(nanoseconds as i64 / Nanosecond::per(Second) as i64), @@ -431,6 +435,10 @@ impl Duration { /// # use time::{Duration, ext::NumericalDuration}; /// assert_eq!(Duration::weeks(1), 604_800.seconds()); /// ``` + /// + /// # Panics + /// + /// This may panic if an overflow occurs. pub const fn weeks(weeks: i64) -> Self { Self::seconds(expect_opt!( weeks.checked_mul(Second::per(Week) as _), @@ -445,6 +453,10 @@ impl Duration { /// # use time::{Duration, ext::NumericalDuration}; /// assert_eq!(Duration::days(1), 86_400.seconds()); /// ``` + /// + /// # Panics + /// + /// This may panic if an overflow occurs. pub const fn days(days: i64) -> Self { Self::seconds(expect_opt!( days.checked_mul(Second::per(Day) as _), @@ -459,6 +471,10 @@ impl Duration { /// # use time::{Duration, ext::NumericalDuration}; /// assert_eq!(Duration::hours(1), 3_600.seconds()); /// ``` + /// + /// # Panics + /// + /// This may panic if an overflow occurs. pub const fn hours(hours: i64) -> Self { Self::seconds(expect_opt!( hours.checked_mul(Second::per(Hour) as _), @@ -473,6 +489,10 @@ impl Duration { /// # use time::{Duration, ext::NumericalDuration}; /// assert_eq!(Duration::minutes(1), 60.seconds()); /// ``` + /// + /// # Panics + /// + /// This may panic if an overflow occurs. pub const fn minutes(minutes: i64) -> Self { Self::seconds(expect_opt!( minutes.checked_mul(Second::per(Minute) as _), @@ -1263,6 +1283,9 @@ impl TryFrom for StdDuration { impl Add for Duration { type Output = Self; + /// # Panics + /// + /// This may panic if an overflow occurs. fn add(self, rhs: Self) -> Self::Output { self.checked_add(rhs) .expect("overflow when adding durations") @@ -1272,6 +1295,9 @@ impl Add for Duration { impl Add for Duration { type Output = Self; + /// # Panics + /// + /// This may panic if an overflow occurs. fn add(self, std_duration: StdDuration) -> Self::Output { self + Self::try_from(std_duration) .expect("overflow converting `std::time::Duration` to `time::Duration`") @@ -1289,6 +1315,9 @@ impl Add for StdDuration { impl_add_assign!(Duration: Self, StdDuration); impl AddAssign for StdDuration { + /// # Panics + /// + /// This may panic if the resulting addition cannot be represented. fn add_assign(&mut self, rhs: Duration) { *self = (*self + rhs).try_into().expect( "Cannot represent a resulting duration in std. Try `let x = x + rhs;`, which will \ @@ -1308,6 +1337,9 @@ impl Neg for Duration { impl Sub for Duration { type Output = Self; + /// # Panics + /// + /// This may panic if an overflow occurs. fn sub(self, rhs: Self) -> Self::Output { self.checked_sub(rhs) .expect("overflow when subtracting durations") @@ -1317,6 +1349,9 @@ impl Sub for Duration { impl Sub for Duration { type Output = Self; + /// # Panics + /// + /// This may panic if an overflow occurs. fn sub(self, rhs: StdDuration) -> Self::Output { self - Self::try_from(rhs) .expect("overflow converting `std::time::Duration` to `time::Duration`") @@ -1326,6 +1361,9 @@ impl Sub for Duration { impl Sub for StdDuration { type Output = Duration; + /// # Panics + /// + /// This may panic if an overflow occurs. fn sub(self, rhs: Duration) -> Self::Output { Duration::try_from(self) .expect("overflow converting `std::time::Duration` to `time::Duration`") @@ -1336,6 +1374,9 @@ impl Sub for StdDuration { impl_sub_assign!(Duration: Self, StdDuration); impl SubAssign for StdDuration { + /// # Panics + /// + /// This may panic if the resulting subtraction can not be represented. fn sub_assign(&mut self, rhs: Duration) { *self = (*self - rhs).try_into().expect( "Cannot represent a resulting duration in std. Try `let x = x - rhs;`, which will \ diff --git a/time/src/ext.rs b/time/src/ext.rs index 1b89d4155..714f325f2 100644 --- a/time/src/ext.rs +++ b/time/src/ext.rs @@ -219,6 +219,9 @@ impl NumericalStdDuration for u64 { StdDuration::from_secs(self) } + /// # Panics + /// + /// This may panic if an overflow occurs. fn std_minutes(self) -> StdDuration { StdDuration::from_secs( self.checked_mul(Second::per(Minute) as Self) @@ -226,6 +229,9 @@ impl NumericalStdDuration for u64 { ) } + /// # Panics + /// + /// This may panic if an overflow occurs. fn std_hours(self) -> StdDuration { StdDuration::from_secs( self.checked_mul(Second::per(Hour) as Self) @@ -233,6 +239,9 @@ impl NumericalStdDuration for u64 { ) } + /// # Panics + /// + /// This may panic if an overflow occurs. fn std_days(self) -> StdDuration { StdDuration::from_secs( self.checked_mul(Second::per(Day) as Self) @@ -240,6 +249,9 @@ impl NumericalStdDuration for u64 { ) } + /// # Panics + /// + /// This may panic if an overflow occurs. fn std_weeks(self) -> StdDuration { StdDuration::from_secs( self.checked_mul(Second::per(Week) as Self) @@ -249,41 +261,65 @@ impl NumericalStdDuration for u64 { } impl NumericalStdDuration for f64 { + /// # Panics + /// + /// This will panic if self is negative. fn std_nanoseconds(self) -> StdDuration { assert!(self >= 0.); StdDuration::from_nanos(self as _) } + /// # Panics + /// + /// This will panic if self is negative. fn std_microseconds(self) -> StdDuration { assert!(self >= 0.); StdDuration::from_nanos((self * Nanosecond::per(Microsecond) as Self) as _) } + /// # Panics + /// + /// This will panic if self is negative. fn std_milliseconds(self) -> StdDuration { assert!(self >= 0.); StdDuration::from_nanos((self * Nanosecond::per(Millisecond) as Self) as _) } + /// # Panics + /// + /// This will panic if self is negative. fn std_seconds(self) -> StdDuration { assert!(self >= 0.); StdDuration::from_nanos((self * Nanosecond::per(Second) as Self) as _) } + /// # Panics + /// + /// This will panic if self is negative. fn std_minutes(self) -> StdDuration { assert!(self >= 0.); StdDuration::from_nanos((self * Nanosecond::per(Minute) as Self) as _) } + /// # Panics + /// + /// This will panic if self is negative. fn std_hours(self) -> StdDuration { assert!(self >= 0.); StdDuration::from_nanos((self * Nanosecond::per(Hour) as Self) as _) } + /// # Panics + /// + /// This will panic if self is negative. fn std_days(self) -> StdDuration { assert!(self >= 0.); StdDuration::from_nanos((self * Nanosecond::per(Day) as Self) as _) } + /// # Panics + /// + /// This will panic if self is negative. fn std_weeks(self) -> StdDuration { assert!(self >= 0.); StdDuration::from_nanos((self * Nanosecond::per(Week) as Self) as _) diff --git a/time/src/instant.rs b/time/src/instant.rs index 706c759c4..0ebda4c3e 100644 --- a/time/src/instant.rs +++ b/time/src/instant.rs @@ -129,6 +129,9 @@ impl From for StdInstant { impl Sub for Instant { type Output = Duration; + /// # Panics + /// + /// This may panic if an overflow occurs. fn sub(self, other: Self) -> Self::Output { match self.0.cmp(&other.0) { Ordering::Equal => Duration::ZERO,