Document relaxed requirements for Num::from_str_radix

Author: cuviper

RELEASES.md

@@ -7,12 +7,16 @@
 - [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)

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