diff options
Diffstat (limited to 'src')
| -rw-r--r-- | src/cast.rs | 76 | ||||
| -rw-r--r-- | src/lib.rs | 14 | ||||
| -rw-r--r-- | src/ops/mod.rs | 1 | ||||
| -rw-r--r-- | src/ops/overflowing.rs | 104 | ||||
| -rw-r--r-- | src/sign.rs | 13 |
5 files changed, 172 insertions, 36 deletions
diff --git a/src/cast.rs b/src/cast.rs index b33f1a1..d38c338 100644 --- a/src/cast.rs +++ b/src/cast.rs @@ -6,9 +6,16 @@ use core::{i128, u128}; use core::{i16, i32, i64, i8, isize}; use core::{u16, u32, u64, u8, usize}; -use float::FloatCore; - /// A generic trait for converting a value to a number. +/// +/// A value can be represented by the target type when it lies within +/// the range of scalars supported by the target type. +/// For example, a negative integer cannot be represented by an unsigned +/// integer type, and an `i64` with a very high magnitude might not be +/// convertible to an `i32`. +/// On the other hand, conversions with possible precision loss or truncation +/// are admitted, like an `f32` with a decimal part to an integer type, or +/// even a large `f64` saturating to `f32` infinity. pub trait ToPrimitive { /// Converts the value of `self` to an `isize`. If the value cannot be /// represented by an `isize`, then `None` is returned. @@ -94,7 +101,7 @@ pub trait ToPrimitive { /// /// This method is only available with feature `i128` enabled on Rust >= 1.26. /// - /// The default implementation converts through `to_u64()`. Types implementing + /// The default implementation converts through `to_u64()`. Types implementing /// this trait should override this method if they can represent a greater range. #[inline] #[cfg(has_i128)] @@ -102,15 +109,21 @@ pub trait ToPrimitive { self.to_u64().map(From::from) } - /// Converts the value of `self` to an `f32`. If the value cannot be - /// represented by an `f32`, then `None` is returned. + /// Converts the value of `self` to an `f32`. Overflows may map to positive + /// or negative inifinity, otherwise `None` is returned if the value cannot + /// be represented by an `f32`. #[inline] fn to_f32(&self) -> Option<f32> { self.to_f64().as_ref().and_then(ToPrimitive::to_f32) } - /// Converts the value of `self` to an `f64`. If the value cannot be - /// represented by an `f64`, then `None` is returned. + /// Converts the value of `self` to an `f64`. Overflows may map to positive + /// or negative inifinity, otherwise `None` is returned if the value cannot + /// be represented by an `f64`. + /// + /// The default implementation tries to convert through `to_i64()`, and + /// failing that through `to_u64()`. Types implementing this trait should + /// override this method if they can represent a greater range. #[inline] fn to_f64(&self) -> Option<f64> { match self.to_i64() { @@ -271,14 +284,8 @@ macro_rules! impl_to_primitive_float_to_float { ($SrcT:ident : $( fn $method:ident -> $DstT:ident ; )*) => {$( #[inline] fn $method(&self) -> Option<$DstT> { - // Only finite values that are reducing size need to worry about overflow. - if size_of::<$SrcT>() > size_of::<$DstT>() && FloatCore::is_finite(*self) { - let n = *self as f64; - if n < $DstT::MIN as f64 || n > $DstT::MAX as f64 { - return None; - } - } - // We can safely cast NaN, +-inf, and finite values in range. + // We can safely cast all values, whether NaN, +-inf, or finite. + // Finite values that are reducing size may saturate to +-inf. Some(*self as $DstT) } )*} @@ -392,6 +399,15 @@ impl_to_primitive_float!(f32); impl_to_primitive_float!(f64); /// A generic trait for converting a number to a value. +/// +/// A value can be represented by the target type when it lies within +/// the range of scalars supported by the target type. +/// For example, a negative integer cannot be represented by an unsigned +/// integer type, and an `i64` with a very high magnitude might not be +/// convertible to an `i32`. +/// On the other hand, conversions with possible precision loss or truncation +/// are admitted, like an `f32` with a decimal part to an integer type, or +/// even a large `f64` saturating to `f32` infinity. pub trait FromPrimitive: Sized { /// Converts an `isize` to return an optional value of this type. If the /// value cannot be represented by this type, then `None` is returned. @@ -492,6 +508,10 @@ pub trait FromPrimitive: Sized { /// Converts a `f64` to return an optional value of this type. If the /// value cannot be represented by this type, then `None` is returned. + /// + /// The default implementation tries to convert through `from_i64()`, and + /// failing that through `from_u64()`. Types implementing this trait should + /// override this method if they can represent a greater range. #[inline] fn from_f64(n: f64) -> Option<Self> { match n.to_i64() { @@ -672,6 +692,15 @@ pub trait NumCast: Sized + ToPrimitive { /// Creates a number from another value that can be converted into /// a primitive via the `ToPrimitive` trait. If the source value cannot be /// represented by the target type, then `None` is returned. + /// + /// A value can be represented by the target type when it lies within + /// the range of scalars supported by the target type. + /// For example, a negative integer cannot be represented by an unsigned + /// integer type, and an `i64` with a very high magnitude might not be + /// convertible to an `i32`. + /// On the other hand, conversions with possible precision loss or truncation + /// are admitted, like an `f32` with a decimal part to an integer type, or + /// even a large `f64` saturating to `f32` infinity. fn from<T: ToPrimitive>(n: T) -> Option<Self>; } @@ -728,25 +757,16 @@ impl<T: NumCast> NumCast for Wrapping<T> { /// /// # Safety /// -/// Currently, some uses of the `as` operator are not entirely safe. -/// In particular, it is undefined behavior if: -/// -/// - A truncated floating point value cannot fit in the target integer -/// type ([#10184](https://github.com/rust-lang/rust/issues/10184)); +/// **In Rust versions before 1.45.0**, some uses of the `as` operator were not entirely safe. +/// In particular, it was undefined behavior if +/// a truncated floating point value could not fit in the target integer +/// type ([#10184](https://github.com/rust-lang/rust/issues/10184)). /// /// ```ignore /// # use num_traits::AsPrimitive; /// let x: u8 = (1.04E+17).as_(); // UB /// ``` /// -/// - Or a floating point value does not fit in another floating -/// point type ([#15536](https://github.com/rust-lang/rust/issues/15536)). -/// -/// ```ignore -/// # use num_traits::AsPrimitive; -/// let x: f32 = (1e300f64).as_(); // UB -/// ``` -/// pub trait AsPrimitive<T>: 'static + Copy where T: 'static + Copy, @@ -67,7 +67,7 @@ pub mod sign; pub trait Num: PartialEq + Zero + One + NumOps { type FromStrRadixErr; - /// Convert from a string and radix <= 36. + /// Convert from a string and radix (typically `2..=36`). /// /// # Examples /// @@ -80,6 +80,18 @@ pub trait Num: PartialEq + Zero + One + NumOps { /// let result = <i32 as Num>::from_str_radix("foo", 10); /// assert!(result.is_err()); /// ``` + /// + /// # Supported radices + /// + /// The exact range of supported radices is at the discretion of each type implementation. For + /// primitive integers, this is implemented by the inherent `from_str_radix` methods in the + /// standard library, which **panic** if the radix is not in the range from 2 to 36. The + /// implementation in this crate for primitive floats is similar. + /// + /// For third-party types, it is suggested that implementations should follow suit and at least + /// accept `2..=36` without panicking, but an `Err` may be returned for any unsupported radix. + /// It's possible that a type might not even support the common radix 10, nor any, if string + /// parsing doesn't make sense for that type. fn from_str_radix(str: &str, radix: u32) -> Result<Self, Self::FromStrRadixErr>; } diff --git a/src/ops/mod.rs b/src/ops/mod.rs index fd1695d..73c4f90 100644 --- a/src/ops/mod.rs +++ b/src/ops/mod.rs @@ -1,5 +1,6 @@ pub mod checked; pub mod inv; pub mod mul_add; +pub mod overflowing; pub mod saturating; pub mod wrapping; diff --git a/src/ops/overflowing.rs b/src/ops/overflowing.rs new file mode 100644 index 0000000..56118a0 --- /dev/null +++ b/src/ops/overflowing.rs @@ -0,0 +1,104 @@ +use core::ops::{Add, Mul, Sub}; +#[cfg(has_i128)] +use core::{i128, u128}; +use core::{i16, i32, i64, i8, isize}; +use core::{u16, u32, u64, u8, usize}; + +macro_rules! overflowing_impl { + ($trait_name:ident, $method:ident, $t:ty) => { + impl $trait_name for $t { + #[inline] + fn $method(&self, v: &Self) -> (Self, bool) { + <$t>::$method(*self, *v) + } + } + }; +} + +/// Performs addition with a flag for overflow. +pub trait OverflowingAdd: Sized + Add<Self, Output = Self> { + /// Returns a tuple of the sum along with a boolean indicating whether an arithmetic overflow would occur. + /// If an overflow would have occurred then the wrapped value is returned. + fn overflowing_add(&self, v: &Self) -> (Self, bool); +} + +overflowing_impl!(OverflowingAdd, overflowing_add, u8); +overflowing_impl!(OverflowingAdd, overflowing_add, u16); +overflowing_impl!(OverflowingAdd, overflowing_add, u32); +overflowing_impl!(OverflowingAdd, overflowing_add, u64); +overflowing_impl!(OverflowingAdd, overflowing_add, usize); +#[cfg(has_i128)] +overflowing_impl!(OverflowingAdd, overflowing_add, u128); + +overflowing_impl!(OverflowingAdd, overflowing_add, i8); +overflowing_impl!(OverflowingAdd, overflowing_add, i16); +overflowing_impl!(OverflowingAdd, overflowing_add, i32); +overflowing_impl!(OverflowingAdd, overflowing_add, i64); +overflowing_impl!(OverflowingAdd, overflowing_add, isize); +#[cfg(has_i128)] +overflowing_impl!(OverflowingAdd, overflowing_add, i128); + +/// Performs substraction with a flag for overflow. +pub trait OverflowingSub: Sized + Sub<Self, Output = Self> { + /// Returns a tuple of the difference along with a boolean indicating whether an arithmetic overflow would occur. + /// If an overflow would have occurred then the wrapped value is returned. + fn overflowing_sub(&self, v: &Self) -> (Self, bool); +} + +overflowing_impl!(OverflowingSub, overflowing_sub, u8); +overflowing_impl!(OverflowingSub, overflowing_sub, u16); +overflowing_impl!(OverflowingSub, overflowing_sub, u32); +overflowing_impl!(OverflowingSub, overflowing_sub, u64); +overflowing_impl!(OverflowingSub, overflowing_sub, usize); +#[cfg(has_i128)] +overflowing_impl!(OverflowingSub, overflowing_sub, u128); + +overflowing_impl!(OverflowingSub, overflowing_sub, i8); +overflowing_impl!(OverflowingSub, overflowing_sub, i16); +overflowing_impl!(OverflowingSub, overflowing_sub, i32); +overflowing_impl!(OverflowingSub, overflowing_sub, i64); +overflowing_impl!(OverflowingSub, overflowing_sub, isize); +#[cfg(has_i128)] +overflowing_impl!(OverflowingSub, overflowing_sub, i128); + +/// Performs multiplication with a flag for overflow. +pub trait OverflowingMul: Sized + Mul<Self, Output = Self> { + /// Returns a tuple of the product along with a boolean indicating whether an arithmetic overflow would occur. + /// If an overflow would have occurred then the wrapped value is returned. + fn overflowing_mul(&self, v: &Self) -> (Self, bool); +} + +overflowing_impl!(OverflowingMul, overflowing_mul, u8); +overflowing_impl!(OverflowingMul, overflowing_mul, u16); +overflowing_impl!(OverflowingMul, overflowing_mul, u32); +overflowing_impl!(OverflowingMul, overflowing_mul, u64); +overflowing_impl!(OverflowingMul, overflowing_mul, usize); +#[cfg(has_i128)] +overflowing_impl!(OverflowingMul, overflowing_mul, u128); + +overflowing_impl!(OverflowingMul, overflowing_mul, i8); +overflowing_impl!(OverflowingMul, overflowing_mul, i16); +overflowing_impl!(OverflowingMul, overflowing_mul, i32); +overflowing_impl!(OverflowingMul, overflowing_mul, i64); +overflowing_impl!(OverflowingMul, overflowing_mul, isize); +#[cfg(has_i128)] +overflowing_impl!(OverflowingMul, overflowing_mul, i128); + +#[test] +fn test_overflowing_traits() { + fn overflowing_add<T: OverflowingAdd>(a: T, b: T) -> (T, bool) { + a.overflowing_add(&b) + } + fn overflowing_sub<T: OverflowingSub>(a: T, b: T) -> (T, bool) { + a.overflowing_sub(&b) + } + fn overflowing_mul<T: OverflowingMul>(a: T, b: T) -> (T, bool) { + a.overflowing_mul(&b) + } + assert_eq!(overflowing_add(5i16, 2), (7, false)); + assert_eq!(overflowing_add(i16::MAX, 1), (i16::MIN, true)); + assert_eq!(overflowing_sub(5i16, 2), (3, false)); + assert_eq!(overflowing_sub(i16::MIN, 1), (i16::MAX, true)); + assert_eq!(overflowing_mul(5i16, 2), (10, false)); + assert_eq!(overflowing_mul(1_000_000_000i32, 10), (1410065408, true)); +} diff --git a/src/sign.rs b/src/sign.rs index 26d44c5..5c32071 100644 --- a/src/sign.rs +++ b/src/sign.rs @@ -213,13 +213,12 @@ fn unsigned_wrapping_is_unsigned() { fn require_unsigned<T: Unsigned>(_: &T) {} require_unsigned(&Wrapping(42_u32)); } -/* + // Commenting this out since it doesn't compile on Rust 1.8, // because on this version Wrapping doesn't implement Neg and therefore can't // implement Signed. -#[test] -fn signed_wrapping_is_signed() { - fn require_signed<T: Signed>(_: &T) {} - require_signed(&Wrapping(-42)); -} -*/ +// #[test] +// fn signed_wrapping_is_signed() { +// fn require_signed<T: Signed>(_: &T) {} +// require_signed(&Wrapping(-42)); +// } |