From 16cdce31d47eb48c4177a666ade2d434dcb48581 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Olivier=20Chass=C3=A9=20St-Laurent?= Date: Fri, 18 Oct 2019 17:02:01 -0400 Subject: [PATCH 1/3] FromPrimitive: fix some comments While the meaning was clear from context, the terms "value" and "type" were inverted for some method comments. Adopted the third person singular present indicative form for the summary lines ("Converts" rather than "Convert"). --- src/cast.rs | 60 ++++++++++++++++++++++++++--------------------------- 1 file changed, 30 insertions(+), 30 deletions(-) diff --git a/src/cast.rs b/src/cast.rs index 72ec7a8..c1bd9b6 100644 --- a/src/cast.rs +++ b/src/cast.rs @@ -362,44 +362,44 @@ impl_to_primitive_float!(f64); /// A generic trait for converting a number to a value. pub trait FromPrimitive: Sized { - /// Convert an `isize` to return an optional value of this type. If the - /// value cannot be represented by this value, then `None` is returned. + /// Converts an `isize` to return an optional value of this type. If the + /// value cannot be represented by this type, then `None` is returned. #[inline] fn from_isize(n: isize) -> Option { n.to_i64().and_then(FromPrimitive::from_i64) } - /// Convert an `i8` to return an optional value of this type. If the - /// type cannot be represented by this value, then `None` is returned. + /// Converts an `i8` to return an optional value of this type. If the + /// value cannot be represented by this type, then `None` is returned. #[inline] fn from_i8(n: i8) -> Option { FromPrimitive::from_i64(From::from(n)) } - /// Convert an `i16` to return an optional value of this type. If the - /// type cannot be represented by this value, then `None` is returned. + /// Converts an `i16` to return an optional value of this type. If the + /// value cannot be represented by this type, then `None` is returned. #[inline] fn from_i16(n: i16) -> Option { FromPrimitive::from_i64(From::from(n)) } - /// Convert an `i32` to return an optional value of this type. If the - /// type cannot be represented by this value, then `None` is returned. + /// Converts an `i32` to return an optional value of this type. If the + /// value cannot be represented by this type, then `None` is returned. #[inline] fn from_i32(n: i32) -> Option { FromPrimitive::from_i64(From::from(n)) } - /// Convert an `i64` to return an optional value of this type. If the - /// type cannot be represented by this value, then `None` is returned. + /// Converts an `i64` to return an optional value of this type. If the + /// value cannot be represented by this type, then `None` is returned. fn from_i64(n: i64) -> Option; - /// Convert an `i128` to return an optional value of this type. If the - /// type cannot be represented by this value, then `None` is returned. + /// Converts an `i128` to return an optional value of this type. If the + /// value cannot be represented by this type, then `None` is returned. /// /// This method is only available with feature `i128` enabled on Rust >= 1.26. /// - /// The default implementation converts through `from_i64()`. Types implementing + /// The default implementation converts through `from_i64()`. Types implementing /// this trait should override this method if they can represent a greater range. #[inline] #[cfg(has_i128)] @@ -407,44 +407,44 @@ pub trait FromPrimitive: Sized { n.to_i64().and_then(FromPrimitive::from_i64) } - /// Convert a `usize` to return an optional value of this type. If the - /// type cannot be represented by this value, then `None` is returned. + /// Converts a `usize` to return an optional value of this type. If the + /// value cannot be represented by this type, then `None` is returned. #[inline] fn from_usize(n: usize) -> Option { n.to_u64().and_then(FromPrimitive::from_u64) } - /// Convert an `u8` to return an optional value of this type. If the - /// type cannot be represented by this value, then `None` is returned. + /// Converts an `u8` to return an optional value of this type. If the + /// value cannot be represented by this type, then `None` is returned. #[inline] fn from_u8(n: u8) -> Option { FromPrimitive::from_u64(From::from(n)) } - /// Convert an `u16` to return an optional value of this type. If the - /// type cannot be represented by this value, then `None` is returned. + /// Converts an `u16` to return an optional value of this type. If the + /// value cannot be represented by this type, then `None` is returned. #[inline] fn from_u16(n: u16) -> Option { FromPrimitive::from_u64(From::from(n)) } - /// Convert an `u32` to return an optional value of this type. If the - /// type cannot be represented by this value, then `None` is returned. + /// Converts an `u32` to return an optional value of this type. If the + /// value cannot be represented by this type, then `None` is returned. #[inline] fn from_u32(n: u32) -> Option { FromPrimitive::from_u64(From::from(n)) } - /// Convert an `u64` to return an optional value of this type. If the - /// type cannot be represented by this value, then `None` is returned. + /// Converts an `u64` to return an optional value of this type. If the + /// value cannot be represented by this type, then `None` is returned. fn from_u64(n: u64) -> Option; - /// Convert an `u128` to return an optional value of this type. If the - /// type cannot be represented by this value, then `None` is returned. + /// Converts an `u128` to return an optional value of this type. If the + /// value cannot be represented by this type, then `None` is returned. /// /// This method is only available with feature `i128` enabled on Rust >= 1.26. /// - /// The default implementation converts through `from_u64()`. Types implementing + /// The default implementation converts through `from_u64()`. Types implementing /// this trait should override this method if they can represent a greater range. #[inline] #[cfg(has_i128)] @@ -452,15 +452,15 @@ pub trait FromPrimitive: Sized { n.to_u64().and_then(FromPrimitive::from_u64) } - /// Convert a `f32` to return an optional value of this type. If the - /// type cannot be represented by this value, then `None` is returned. + /// Converts a `f32` to return an optional value of this type. If the + /// value cannot be represented by this type, then `None` is returned. #[inline] fn from_f32(n: f32) -> Option { FromPrimitive::from_f64(From::from(n)) } - /// Convert a `f64` to return an optional value of this type. If the - /// type cannot be represented by this value, then `None` is returned. + /// Converts a `f64` to return an optional value of this type. If the + /// value cannot be represented by this type, then `None` is returned. #[inline] fn from_f64(n: f64) -> Option { match n.to_i64() { From 27e3f853b0cb5e0d3f33543781bb54c89b393eb0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Olivier=20Chass=C3=A9=20St-Laurent?= Date: Fri, 18 Oct 2019 17:03:59 -0400 Subject: [PATCH 2/3] NumCast: document when `from` can return `None` --- src/cast.rs | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/src/cast.rs b/src/cast.rs index c1bd9b6..4dc1b5a 100644 --- a/src/cast.rs +++ b/src/cast.rs @@ -639,7 +639,8 @@ pub fn cast(n: T) -> Option { /// An interface for casting between machine scalars. pub trait NumCast: Sized + ToPrimitive { /// Creates a number from another value that can be converted into - /// a primitive via the `ToPrimitive` trait. + /// a primitive via the `ToPrimitive` trait. If the source value cannot be + /// represented by the target type, then `None` is returned. fn from(n: T) -> Option; } From fdb41818a48d2f0bf1a9521c4ebc2656adbe4045 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Olivier=20Chass=C3=A9=20St-Laurent?= Date: Fri, 18 Oct 2019 17:17:36 -0400 Subject: [PATCH 3/3] ToPrimitive: document when `to_` methods can return `None` --- src/cast.rs | 46 +++++++++++++++++++++++++++++++--------------- 1 file changed, 31 insertions(+), 15 deletions(-) diff --git a/src/cast.rs b/src/cast.rs index 4dc1b5a..002d40a 100644 --- a/src/cast.rs +++ b/src/cast.rs @@ -10,38 +10,45 @@ use float::FloatCore; /// A generic trait for converting a value to a number. pub trait ToPrimitive { - /// Converts the value of `self` to an `isize`. + /// Converts the value of `self` to an `isize`. If the value cannot be + /// represented by an `isize`, then `None` is returned. #[inline] fn to_isize(&self) -> Option { self.to_i64().as_ref().and_then(ToPrimitive::to_isize) } - /// Converts the value of `self` to an `i8`. + /// Converts the value of `self` to an `i8`. If the value cannot be + /// represented by an `i8`, then `None` is returned. #[inline] fn to_i8(&self) -> Option { self.to_i64().as_ref().and_then(ToPrimitive::to_i8) } - /// Converts the value of `self` to an `i16`. + /// Converts the value of `self` to an `i16`. If the value cannot be + /// represented by an `i16`, then `None` is returned. #[inline] fn to_i16(&self) -> Option { self.to_i64().as_ref().and_then(ToPrimitive::to_i16) } - /// Converts the value of `self` to an `i32`. + /// Converts the value of `self` to an `i32`. If the value cannot be + /// represented by an `i32`, then `None` is returned. #[inline] fn to_i32(&self) -> Option { self.to_i64().as_ref().and_then(ToPrimitive::to_i32) } - /// Converts the value of `self` to an `i64`. + /// Converts the value of `self` to an `i64`. If the value cannot be + /// represented by an `i64`, then `None` is returned. fn to_i64(&self) -> Option; - /// Converts the value of `self` to an `i128`. + /// Converts the value of `self` to an `i128`. If the value cannot be + /// represented by an `i128` (`i64` under the default implementation), then + /// `None` is returned. /// /// This method is only available with feature `i128` enabled on Rust >= 1.26. /// - /// The default implementation converts through `to_i64()`. Types implementing + /// The default implementation converts through `to_i64()`. Types implementing /// this trait should override this method if they can represent a greater range. #[inline] #[cfg(has_i128)] @@ -49,35 +56,42 @@ pub trait ToPrimitive { self.to_i64().map(From::from) } - /// Converts the value of `self` to a `usize`. + /// Converts the value of `self` to a `usize`. If the value cannot be + /// represented by a `usize`, then `None` is returned. #[inline] fn to_usize(&self) -> Option { self.to_u64().as_ref().and_then(ToPrimitive::to_usize) } - /// Converts the value of `self` to an `u8`. + /// Converts the value of `self` to a `u8`. If the value cannot be + /// represented by a `u8`, then `None` is returned. #[inline] fn to_u8(&self) -> Option { self.to_u64().as_ref().and_then(ToPrimitive::to_u8) } - /// Converts the value of `self` to an `u16`. + /// Converts the value of `self` to a `u16`. If the value cannot be + /// represented by a `u16`, then `None` is returned. #[inline] fn to_u16(&self) -> Option { self.to_u64().as_ref().and_then(ToPrimitive::to_u16) } - /// Converts the value of `self` to an `u32`. + /// Converts the value of `self` to a `u32`. If the value cannot be + /// represented by a `u32`, then `None` is returned. #[inline] fn to_u32(&self) -> Option { self.to_u64().as_ref().and_then(ToPrimitive::to_u32) } - /// Converts the value of `self` to an `u64`. + /// Converts the value of `self` to a `u64`. If the value cannot be + /// represented by a `u64`, then `None` is returned. #[inline] fn to_u64(&self) -> Option; - /// Converts the value of `self` to an `u128`. + /// Converts the value of `self` to a `u128`. If the value cannot be + /// represented by a `u128` (`u64` under the default implementation), then + /// `None` is returned. /// /// This method is only available with feature `i128` enabled on Rust >= 1.26. /// @@ -89,13 +103,15 @@ pub trait ToPrimitive { self.to_u64().map(From::from) } - /// Converts the value of `self` to an `f32`. + /// Converts the value of `self` to an `f32`. If the value cannot be + /// represented by an `f32`, then `None` is returned. #[inline] fn to_f32(&self) -> Option { self.to_f64().as_ref().and_then(ToPrimitive::to_f32) } - /// Converts the value of `self` to an `f64`. + /// Converts the value of `self` to an `f64`. If the value cannot be + /// represented by an `f64`, then `None` is returned. #[inline] fn to_f64(&self) -> Option { match self.to_i64() {