From e92f6334bc26cc9a62c0129fc7fd4a35bafaec16 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Olivier=20Chass=C3=A9=20St-Laurent?= Date: Fri, 26 Jul 2024 15:15:14 -0400 Subject: [PATCH 1/2] Fix checked operations documentation. Remove the implication that wrapping is the default behaviour. --- src/ops/checked.rs | 27 +++++++++++++-------------- 1 file changed, 13 insertions(+), 14 deletions(-) diff --git a/src/ops/checked.rs b/src/ops/checked.rs index da1eb3ea..5fb0a329 100644 --- a/src/ops/checked.rs +++ b/src/ops/checked.rs @@ -1,7 +1,6 @@ use core::ops::{Add, Div, Mul, Rem, Shl, Shr, Sub}; -/// Performs addition that returns `None` instead of wrapping around on -/// overflow. +/// Performs addition, returning `None` if overflow occurred. pub trait CheckedAdd: Sized + Add { /// Adds two numbers, checking for overflow. If overflow happens, `None` is /// returned. @@ -33,7 +32,7 @@ checked_impl!(CheckedAdd, checked_add, i64); checked_impl!(CheckedAdd, checked_add, isize); checked_impl!(CheckedAdd, checked_add, i128); -/// Performs subtraction that returns `None` instead of wrapping around on underflow. +/// Performs subtraction, returning `None` if underflow occurred. pub trait CheckedSub: Sized + Sub { /// Subtracts two numbers, checking for underflow. If underflow happens, /// `None` is returned. @@ -54,8 +53,8 @@ checked_impl!(CheckedSub, checked_sub, i64); checked_impl!(CheckedSub, checked_sub, isize); checked_impl!(CheckedSub, checked_sub, i128); -/// Performs multiplication that returns `None` instead of wrapping around on underflow or -/// overflow. +/// Performs multiplication, returning `None` if underflow or overflow +/// occurred. pub trait CheckedMul: Sized + Mul { /// Multiplies two numbers, checking for underflow or overflow. If underflow /// or overflow happens, `None` is returned. @@ -76,8 +75,8 @@ checked_impl!(CheckedMul, checked_mul, i64); checked_impl!(CheckedMul, checked_mul, isize); checked_impl!(CheckedMul, checked_mul, i128); -/// Performs division that returns `None` instead of panicking on division by zero and instead of -/// wrapping around on underflow and overflow. +/// Performs division, returning `None` on division by zero or if underflow or +/// overflow occurred. pub trait CheckedDiv: Sized + Div { /// Divides two numbers, checking for underflow, overflow and division by /// zero. If any of that happens, `None` is returned. @@ -98,8 +97,8 @@ checked_impl!(CheckedDiv, checked_div, i64); checked_impl!(CheckedDiv, checked_div, isize); checked_impl!(CheckedDiv, checked_div, i128); -/// Performs an integral remainder that returns `None` instead of panicking on division by zero and -/// instead of wrapping around on underflow and overflow. +/// Performs integral remainder, returning `None` on division by zero or if +/// underflow or overflow occurred. pub trait CheckedRem: Sized + Rem { /// Finds the remainder of dividing two numbers, checking for underflow, overflow and division /// by zero. If any of that happens, `None` is returned. @@ -148,7 +147,7 @@ macro_rules! checked_impl_unary { }; } -/// Performs negation that returns `None` if the result can't be represented. +/// Performs negation, returning `None` if the result can't be represented. pub trait CheckedNeg: Sized { /// Negates a number, returning `None` for results that can't be represented, like signed `MIN` /// values that can't be positive, or non-zero unsigned values that can't be negative. @@ -183,8 +182,8 @@ checked_impl_unary!(CheckedNeg, checked_neg, i64); checked_impl_unary!(CheckedNeg, checked_neg, isize); checked_impl_unary!(CheckedNeg, checked_neg, i128); -/// Performs a left shift that returns `None` on shifts larger than -/// or equal to the type width. +/// Performs shift left, returning `None` on shifts larger than or equal to +/// the type width. pub trait CheckedShl: Sized + Shl { /// Checked shift left. Computes `self << rhs`, returning `None` /// if `rhs` is larger than or equal to the number of bits in `self`. @@ -227,8 +226,8 @@ checked_shift_impl!(CheckedShl, checked_shl, i64); checked_shift_impl!(CheckedShl, checked_shl, isize); checked_shift_impl!(CheckedShl, checked_shl, i128); -/// Performs a right shift that returns `None` on shifts larger than -/// or equal to the type width. +/// Performs shift right, returning `None` on shifts larger than or equal to +/// the type width. pub trait CheckedShr: Sized + Shr { /// Checked shift right. Computes `self >> rhs`, returning `None` /// if `rhs` is larger than or equal to the number of bits in `self`. From e8cb7b05d5d6584027dc7e038e72fad2016fe19c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Olivier=20Chass=C3=A9=20St-Laurent?= Date: Sat, 27 Jul 2024 13:00:43 -0400 Subject: [PATCH 2/2] Fix checked operations documentation. - Remove the implication that wrapping is the default behaviour for `CheckedEuclid` methods. - Replace mentions of 'underflow' with 'overflow'. --- src/ops/checked.rs | 23 +++++++++++------------ src/ops/euclid.rs | 11 ++++++----- 2 files changed, 17 insertions(+), 17 deletions(-) diff --git a/src/ops/checked.rs b/src/ops/checked.rs index 5fb0a329..553b28be 100644 --- a/src/ops/checked.rs +++ b/src/ops/checked.rs @@ -32,9 +32,9 @@ checked_impl!(CheckedAdd, checked_add, i64); checked_impl!(CheckedAdd, checked_add, isize); checked_impl!(CheckedAdd, checked_add, i128); -/// Performs subtraction, returning `None` if underflow occurred. +/// Performs subtraction, returning `None` if overflow occurred. pub trait CheckedSub: Sized + Sub { - /// Subtracts two numbers, checking for underflow. If underflow happens, + /// Subtracts two numbers, checking for overflow. If overflow happens, /// `None` is returned. fn checked_sub(&self, v: &Self) -> Option; } @@ -53,11 +53,10 @@ checked_impl!(CheckedSub, checked_sub, i64); checked_impl!(CheckedSub, checked_sub, isize); checked_impl!(CheckedSub, checked_sub, i128); -/// Performs multiplication, returning `None` if underflow or overflow -/// occurred. +/// Performs multiplication, returning `None` if overflow occurred. pub trait CheckedMul: Sized + Mul { - /// Multiplies two numbers, checking for underflow or overflow. If underflow - /// or overflow happens, `None` is returned. + /// Multiplies two numbers, checking for overflow. If overflow happens, + /// `None` is returned. fn checked_mul(&self, v: &Self) -> Option; } @@ -75,10 +74,10 @@ checked_impl!(CheckedMul, checked_mul, i64); checked_impl!(CheckedMul, checked_mul, isize); checked_impl!(CheckedMul, checked_mul, i128); -/// Performs division, returning `None` on division by zero or if underflow or -/// overflow occurred. +/// Performs division, returning `None` on division by zero or if overflow +/// occurred. pub trait CheckedDiv: Sized + Div { - /// Divides two numbers, checking for underflow, overflow and division by + /// Divides two numbers, checking for overflow and division by /// zero. If any of that happens, `None` is returned. fn checked_div(&self, v: &Self) -> Option; } @@ -98,10 +97,10 @@ checked_impl!(CheckedDiv, checked_div, isize); checked_impl!(CheckedDiv, checked_div, i128); /// Performs integral remainder, returning `None` on division by zero or if -/// underflow or overflow occurred. +/// overflow occurred. pub trait CheckedRem: Sized + Rem { - /// Finds the remainder of dividing two numbers, checking for underflow, overflow and division - /// by zero. If any of that happens, `None` is returned. + /// Finds the remainder of dividing two numbers, checking for overflow and + /// division by zero. If any of that happens, `None` is returned. /// /// # Examples /// diff --git a/src/ops/euclid.rs b/src/ops/euclid.rs index fa7b317a..194427d2 100644 --- a/src/ops/euclid.rs +++ b/src/ops/euclid.rs @@ -136,15 +136,16 @@ impl Euclid for f64 { } pub trait CheckedEuclid: Euclid { - /// Performs euclid division that returns `None` instead of panicking on division by zero - /// and instead of wrapping around on underflow and overflow. + /// Performs euclid division, returning `None` on division by zero or if + /// overflow occurred. fn checked_div_euclid(&self, v: &Self) -> Option; - /// Finds the euclid remainder of dividing two numbers, checking for underflow, overflow and - /// division by zero. If any of that happens, `None` is returned. + /// Finds the euclid remainder of dividing two numbers, returning `None` on + /// division by zero or if overflow occurred. fn checked_rem_euclid(&self, v: &Self) -> Option; - /// Returns both the quotient and remainder from checked Euclidean division. + /// Returns both the quotient and remainder from checked Euclidean division, + /// returning `None` on division by zero or if overflow occurred. /// /// By default, it internally calls both `CheckedEuclid::checked_div_euclid` and `CheckedEuclid::checked_rem_euclid`, /// but it can be overridden in order to implement some optimization.