diff --git a/Cargo.toml b/Cargo.toml index d947ec35..8ac65554 100644 --- a/Cargo.toml +++ b/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/*"] diff --git a/RELEASES.md b/RELEASES.md index 75a74f91..0ce9f225 100644 --- a/RELEASES.md +++ b/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 diff --git a/src/lib.rs b/src/lib.rs index d9989467..a6c202c9 100644 --- a/src/lib.rs +++ b/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 = ::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; } diff --git a/src/ops/overflowing.rs b/src/ops/overflowing.rs index ff97ea54..56118a03 100644 --- a/src/ops/overflowing.rs +++ b/src/ops/overflowing.rs @@ -17,7 +17,7 @@ macro_rules! overflowing_impl { /// Performs addition with a flag for overflow. pub trait OverflowingAdd: Sized + Add { - /// 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 { - /// 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 { - /// 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); }