Merge #193

193: Release 0.2.13 r=cuviper a=cuviper



Co-authored-by: Josh Stone <cuviper@gmail.com>

Cargo.toml

@@ -8,7 +8,7 @@ categories = ["algorithms", "science", "no-std"]
 license = "MIT/Apache-2.0"
 repository = "https://github.com/rust-num/num-traits"
 name = "num-traits"
-version = "0.2.12"
+version = "0.2.13"
 readme = "README.md"
 build = "build.rs"
 exclude = ["/bors.toml", "/ci/*", "/.github/*"]

RELEASES.md

@@ -1,3 +1,24 @@
+# Release 0.2.13 (2020-10-29)
+
+- [The new `OverflowingAdd`, `OverflowingSub`, and `OverflowingMul` traits][180]
+  return a tuple with the operation result and a `bool` indicating overflow.
+- [The "i128" feature now overrides compiler probes for that support][185].
+  This may fix scenarios where `autocfg` probing doesn't work properly.
+- [Casts from large `f64` values to `f32` now saturate to infinity][186]. They
+  previously returned `None` because that was once thought to be undefined
+  behavior, but [rust#15536] resolved that such casts are fine.
+- [`Num::from_str_radix` documents requirements for radix support][192], which
+  are now more relaxed than previously implied. It is suggested to accept at
+  least `2..=36` without panicking, but `Err` may be returned otherwise.
+
+**Contributors**: @cuviper, @Enet4, @KaczuH, @martin-t, @newpavlov
+
+[180]: https://github.com/rust-num/num-traits/pull/180
+[185]: https://github.com/rust-num/num-traits/pull/185
+[186]: https://github.com/rust-num/num-traits/pull/186
+[192]: https://github.com/rust-num/num-traits/issues/192
+[rust#15536]: https://github.com/rust-lang/rust/issues/15536
+
 # Release 0.2.12 (2020-06-11)
 
 - [The new `WrappingNeg` trait][153] will wrap the result if it exceeds the

src/lib.rs

@@ -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>;
 }
 

src/ops/overflowing.rs

@@ -17,7 +17,7 @@ macro_rules! overflowing_impl {
 
 /// Performs addition with a flag for overflow.
 pub trait OverflowingAdd: Sized + Add<Self, Output = Self> {
-    /// Returns a tuple of the addition along with a boolean indicating whether an arithmetic overflow would occur.
+    /// 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);
 }
@@ -40,7 +40,7 @@ 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 subtraction along with a boolean indicating whether an arithmetic overflow would occur.
+    /// 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);
 }
@@ -63,7 +63,7 @@ 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 subtraction along with a boolean indicating whether an arithmetic overflow would occur.
+    /// 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);
 }