From 052e765df0faa9a95c04133e7e95c16b06bfeb8d Mon Sep 17 00:00:00 2001 From: Tom Repetti Date: Thu, 30 Apr 2020 14:35:03 -0400 Subject: [PATCH 1/4] Add saturating_mul() and refactor Saturating into subtraits. Fixes #40. --- src/int.rs | 6 ++- src/lib.rs | 4 +- src/ops/saturating.rs | 121 +++++++++++++++++++++++++++++++++++------- 3 files changed, 109 insertions(+), 22 deletions(-) diff --git a/src/int.rs b/src/int.rs index 10e751a9..3cff2b4f 100644 --- a/src/int.rs +++ b/src/int.rs @@ -2,7 +2,7 @@ use core::ops::{BitAnd, BitOr, BitXor, Not, Shl, Shr}; use bounds::Bounded; use ops::checked::*; -use ops::saturating::Saturating; +use ops::saturating::*; use {Num, NumCast}; /// Generic trait for primitive integers. @@ -50,7 +50,9 @@ pub trait PrimInt: + CheckedSub + CheckedMul + CheckedDiv - + Saturating + + SaturatingAdd + + SaturatingSub + + SaturatingMul { /// Returns the number of ones in the binary representation of `self`. /// diff --git a/src/lib.rs b/src/lib.rs index dfcc6a7d..3eb2a13e 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -42,7 +42,9 @@ pub use ops::checked::{ }; pub use ops::inv::Inv; pub use ops::mul_add::{MulAdd, MulAddAssign}; -pub use ops::saturating::Saturating; +pub use ops::saturating::{ + SaturatingAdd, SaturatingMul, SaturatingSub, +}; pub use ops::wrapping::{ WrappingAdd, WrappingMul, WrappingNeg, WrappingShl, WrappingShr, WrappingSub, }; diff --git a/src/ops/saturating.rs b/src/ops/saturating.rs index fdce1897..702e335f 100644 --- a/src/ops/saturating.rs +++ b/src/ops/saturating.rs @@ -1,30 +1,113 @@ -/// Saturating math operations -pub trait Saturating { - /// Saturating addition operator. - /// Returns a+b, saturating at the numeric bounds instead of overflowing. - fn saturating_add(self, v: Self) -> Self; - - /// Saturating subtraction operator. - /// Returns a-b, saturating at the numeric bounds instead of overflowing. - fn saturating_sub(self, v: Self) -> Self; -} +use core::ops::{Add, Mul, Sub}; macro_rules! saturating_impl { - ($trait_name:ident for $($t:ty)*) => {$( + ($trait_name:ident, $method:ident, $t:ty) => { impl $trait_name for $t { #[inline] - fn saturating_add(self, v: Self) -> Self { - Self::saturating_add(self, v) + fn $method(&self, v: &Self) -> Self { + <$t>::$method(*self, *v) } - + } + }; + ($trait_name:ident, $method:ident, $t:ty, $rhs:ty) => { + impl $trait_name<$rhs> for $t { #[inline] - fn saturating_sub(self, v: Self) -> Self { - Self::saturating_sub(self, v) + fn $method(&self, v: &$rhs) -> Self { + <$t>::$method(*self, *v) } } - )*} + }; +} + +/// Performs addition that saturates high on overflow and low on underflow. +pub trait SaturatingAdd: Sized + Add { + /// Saturating addition. Computes `self + other`, saturating at the relevant high or low boundary of + /// the type. + fn saturating_add(&self, v: &Self) -> Self; +} + +saturating_impl!(SaturatingAdd, saturating_add, u8); +saturating_impl!(SaturatingAdd, saturating_add, u16); +saturating_impl!(SaturatingAdd, saturating_add, u32); +saturating_impl!(SaturatingAdd, saturating_add, u64); +saturating_impl!(SaturatingAdd, saturating_add, usize); +#[cfg(has_i128)] +saturating_impl!(SaturatingAdd, saturating_add, u128); + +saturating_impl!(SaturatingAdd, saturating_add, i8); +saturating_impl!(SaturatingAdd, saturating_add, i16); +saturating_impl!(SaturatingAdd, saturating_add, i32); +saturating_impl!(SaturatingAdd, saturating_add, i64); +saturating_impl!(SaturatingAdd, saturating_add, isize); +#[cfg(has_i128)] +saturating_impl!(SaturatingAdd, saturating_add, i128); + +/// Performs subtraction that saturates high on overflow and low on underflow. +pub trait SaturatingSub: Sized + Sub { + /// Saturating subtraction. Computes `self - other`, saturating at the relevant high or low boundary of + /// the type. + fn saturating_sub(&self, v: &Self) -> Self; } -saturating_impl!(Saturating for isize usize i8 u8 i16 u16 i32 u32 i64 u64); +saturating_impl!(SaturatingSub, saturating_sub, u8); +saturating_impl!(SaturatingSub, saturating_sub, u16); +saturating_impl!(SaturatingSub, saturating_sub, u32); +saturating_impl!(SaturatingSub, saturating_sub, u64); +saturating_impl!(SaturatingSub, saturating_sub, usize); #[cfg(has_i128)] -saturating_impl!(Saturating for i128 u128); +saturating_impl!(SaturatingSub, saturating_sub, u128); + +saturating_impl!(SaturatingSub, saturating_sub, i8); +saturating_impl!(SaturatingSub, saturating_sub, i16); +saturating_impl!(SaturatingSub, saturating_sub, i32); +saturating_impl!(SaturatingSub, saturating_sub, i64); +saturating_impl!(SaturatingSub, saturating_sub, isize); +#[cfg(has_i128)] +saturating_impl!(SaturatingSub, saturating_sub, i128); + +/// Performs subtraction that saturates high on overflow and low on underflow. +pub trait SaturatingMul: Sized + Mul { + /// Saturating multiplication. Computes `self * other`, saturating at the relevant high or low boundary of + /// the type. + fn saturating_mul(&self, v: &Self) -> Self; +} + +saturating_impl!(SaturatingMul, saturating_mul, u8); +saturating_impl!(SaturatingMul, saturating_mul, u16); +saturating_impl!(SaturatingMul, saturating_mul, u32); +saturating_impl!(SaturatingMul, saturating_mul, u64); +saturating_impl!(SaturatingMul, saturating_mul, usize); +#[cfg(has_i128)] +saturating_impl!(SaturatingMul, saturating_mul, u128); + +saturating_impl!(SaturatingMul, saturating_mul, i8); +saturating_impl!(SaturatingMul, saturating_mul, i16); +saturating_impl!(SaturatingMul, saturating_mul, i32); +saturating_impl!(SaturatingMul, saturating_mul, i64); +saturating_impl!(SaturatingMul, saturating_mul, isize); +#[cfg(has_i128)] +saturating_impl!(SaturatingMul, saturating_mul, i128); + +// TODO: add SaturatingNeg for signed integer primitives once the saturating_neg() API is stable. + +#[test] +fn test_saturating_traits() { + fn saturating_add(a: T, b: T) -> T { + a.saturating_add(&b) + } + fn saturating_sub(a: T, b: T) -> T { + a.saturating_sub(&b) + } + fn saturating_mul(a: T, b: T) -> T { + a.saturating_mul(&b) + } + assert_eq!(saturating_add(255, 1), 255u8); + assert_eq!(saturating_add(127, 1), 127i8); + assert_eq!(saturating_add(-128, -1), -128i8); + assert_eq!(saturating_sub(0, 1), 0u8); + assert_eq!(saturating_sub(-128, 1), -128i8); + assert_eq!(saturating_sub(127, -1), 127i8); + assert_eq!(saturating_mul(255, 2), 255u8); + assert_eq!(saturating_mul(127, 2), 127i8); + assert_eq!(saturating_mul(-128, 2), -128i8); +} From 964752f01961a77f5ffce12dc488d05c2dcb498e Mon Sep 17 00:00:00 2001 From: Tom Repetti Date: Thu, 30 Apr 2020 14:53:27 -0400 Subject: [PATCH 2/4] Fix formatting for SaturatingAdd, SaturatingMul and SaturatingSub traits in lib.rs. --- src/lib.rs | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/src/lib.rs b/src/lib.rs index 3eb2a13e..9b996eeb 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -42,9 +42,7 @@ pub use ops::checked::{ }; pub use ops::inv::Inv; pub use ops::mul_add::{MulAdd, MulAddAssign}; -pub use ops::saturating::{ - SaturatingAdd, SaturatingMul, SaturatingSub, -}; +pub use ops::saturating::{SaturatingAdd, SaturatingMul, SaturatingSub}; pub use ops::wrapping::{ WrappingAdd, WrappingMul, WrappingNeg, WrappingShl, WrappingShr, WrappingSub, }; From 86c31265f582d98ca58ff494567f1bbaf6aa4b5b Mon Sep 17 00:00:00 2001 From: Tom Repetti Date: Sat, 2 May 2020 10:53:54 -0400 Subject: [PATCH 3/4] Restore and deprecate Saturating trait. Fix up doc strings for Saturating* traits. --- src/int.rs | 6 ++---- src/lib.rs | 2 +- src/ops/saturating.rs | 38 +++++++++++++++++++++++++++++++++++--- 3 files changed, 38 insertions(+), 8 deletions(-) diff --git a/src/int.rs b/src/int.rs index 3cff2b4f..10e751a9 100644 --- a/src/int.rs +++ b/src/int.rs @@ -2,7 +2,7 @@ use core::ops::{BitAnd, BitOr, BitXor, Not, Shl, Shr}; use bounds::Bounded; use ops::checked::*; -use ops::saturating::*; +use ops::saturating::Saturating; use {Num, NumCast}; /// Generic trait for primitive integers. @@ -50,9 +50,7 @@ pub trait PrimInt: + CheckedSub + CheckedMul + CheckedDiv - + SaturatingAdd - + SaturatingSub - + SaturatingMul + + Saturating { /// Returns the number of ones in the binary representation of `self`. /// diff --git a/src/lib.rs b/src/lib.rs index 9b996eeb..d9989467 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -42,7 +42,7 @@ pub use ops::checked::{ }; pub use ops::inv::Inv; pub use ops::mul_add::{MulAdd, MulAddAssign}; -pub use ops::saturating::{SaturatingAdd, SaturatingMul, SaturatingSub}; +pub use ops::saturating::{Saturating, SaturatingAdd, SaturatingMul, SaturatingSub}; pub use ops::wrapping::{ WrappingAdd, WrappingMul, WrappingNeg, WrappingShl, WrappingShr, WrappingSub, }; diff --git a/src/ops/saturating.rs b/src/ops/saturating.rs index 702e335f..47bf55c5 100644 --- a/src/ops/saturating.rs +++ b/src/ops/saturating.rs @@ -1,5 +1,37 @@ use core::ops::{Add, Mul, Sub}; +/// Saturating math operations. Deprecated, use `SaturatingAdd`, `SaturatingSub` and +/// `SaturatingMul` instead. +pub trait Saturating { + /// Saturating addition operator. + /// Returns a+b, saturating at the numeric bounds instead of overflowing. + fn saturating_add(self, v: Self) -> Self; + + /// Saturating subtraction operator. + /// Returns a-b, saturating at the numeric bounds instead of overflowing. + fn saturating_sub(self, v: Self) -> Self; +} + +macro_rules! deprecated_saturating_impl { + ($trait_name:ident for $($t:ty)*) => {$( + impl $trait_name for $t { + #[inline] + fn saturating_add(self, v: Self) -> Self { + Self::saturating_add(self, v) + } + + #[inline] + fn saturating_sub(self, v: Self) -> Self { + Self::saturating_sub(self, v) + } + } + )*} +} + +deprecated_saturating_impl!(Saturating for isize usize i8 u8 i16 u16 i32 u32 i64 u64); +#[cfg(has_i128)] +deprecated_saturating_impl!(Saturating for i128 u128); + macro_rules! saturating_impl { ($trait_name:ident, $method:ident, $t:ty) => { impl $trait_name for $t { @@ -19,7 +51,7 @@ macro_rules! saturating_impl { }; } -/// Performs addition that saturates high on overflow and low on underflow. +/// Performs addition that saturates at the numeric bounds instead of overflowing. pub trait SaturatingAdd: Sized + Add { /// Saturating addition. Computes `self + other`, saturating at the relevant high or low boundary of /// the type. @@ -42,7 +74,7 @@ saturating_impl!(SaturatingAdd, saturating_add, isize); #[cfg(has_i128)] saturating_impl!(SaturatingAdd, saturating_add, i128); -/// Performs subtraction that saturates high on overflow and low on underflow. +/// Performs subtraction that saturates at the numeric bounds instead of overflowing. pub trait SaturatingSub: Sized + Sub { /// Saturating subtraction. Computes `self - other`, saturating at the relevant high or low boundary of /// the type. @@ -65,7 +97,7 @@ saturating_impl!(SaturatingSub, saturating_sub, isize); #[cfg(has_i128)] saturating_impl!(SaturatingSub, saturating_sub, i128); -/// Performs subtraction that saturates high on overflow and low on underflow. +/// Performs multiplication that saturates at the numeric bounds instead of overflowing. pub trait SaturatingMul: Sized + Mul { /// Saturating multiplication. Computes `self * other`, saturating at the relevant high or low boundary of /// the type. From 5f00e22314a9ec2fa44eee242dea09169650a555 Mon Sep 17 00:00:00 2001 From: Josh Stone Date: Thu, 11 Jun 2020 15:57:48 -0700 Subject: [PATCH 4/4] remove an unused pattern from saturating_impl --- src/ops/saturating.rs | 8 -------- 1 file changed, 8 deletions(-) diff --git a/src/ops/saturating.rs b/src/ops/saturating.rs index 47bf55c5..e39cfd7b 100644 --- a/src/ops/saturating.rs +++ b/src/ops/saturating.rs @@ -41,14 +41,6 @@ macro_rules! saturating_impl { } } }; - ($trait_name:ident, $method:ident, $t:ty, $rhs:ty) => { - impl $trait_name<$rhs> for $t { - #[inline] - fn $method(&self, v: &$rhs) -> Self { - <$t>::$method(*self, *v) - } - } - }; } /// Performs addition that saturates at the numeric bounds instead of overflowing.