Rollup merge of #46898 - tspiteri:int-overflow-not-underflow, r=steveklabnik

docs: do not call integer overflows as underflows

In the API docs, integer overflow is sometimes called underflow. Underflow is really when the magnitude of a floating-point number is too small so the number underflows to subnormal or zero. With integers it is always overflow, even if the expected result is less than the minimum number that can be represented.

3 files changed, 13 insertions, 17 deletions

diff --git a/src/libcore/num/bignum.rs b/src/libcore/num/bignum.rs
index b5553fb2947..732a02e8c42 100644
--- a/src/libcore/num/bignum.rs
+++ b/src/libcore/num/bignum.rs
@@ -114,7 +114,7 @@ macro_rules! define_bignum {
         /// copying it recklessly may result in the performance hit.
         /// Thus this is intentionally not `Copy`.
         ///
-        /// All operations available to bignums panic in the case of over/underflows.
+        /// All operations available to bignums panic in the case of overflows.
         /// The caller is responsible to use large enough bignum types.
         pub struct $name {
             /// One plus the offset to the maximum "digit" in use.
diff --git a/src/libcore/num/mod.rs b/src/libcore/num/mod.rs
index 379dcd017e0..851c0a0dd6f 100644
--- a/src/libcore/num/mod.rs
+++ b/src/libcore/num/mod.rs
@@ -399,7 +399,7 @@ macro_rules! int_impl {
         }
 
         /// Checked integer subtraction. Computes `self - rhs`, returning
-        /// `None` if underflow occurred.
+        /// `None` if overflow occurred.
         ///
         /// # Examples
         ///
@@ -417,7 +417,7 @@ macro_rules! int_impl {
         }
 
         /// Checked integer multiplication. Computes `self * rhs`, returning
-        /// `None` if underflow or overflow occurred.
+        /// `None` if overflow occurred.
         ///
         /// # Examples
         ///
@@ -435,7 +435,7 @@ macro_rules! int_impl {
         }
 
         /// Checked integer division. Computes `self / rhs`, returning `None`
-        /// if `rhs == 0` or the operation results in underflow or overflow.
+        /// if `rhs == 0` or the operation results in overflow.
         ///
         /// # Examples
         ///
@@ -457,7 +457,7 @@ macro_rules! int_impl {
         }
 
         /// Checked integer remainder. Computes `self % rhs`, returning `None`
-        /// if `rhs == 0` or the operation results in underflow or overflow.
+        /// if `rhs == 0` or the operation results in overflow.
         ///
         /// # Examples
         ///
@@ -1563,7 +1563,7 @@ macro_rules! uint_impl {
         }
 
         /// Checked integer subtraction. Computes `self - rhs`, returning
-        /// `None` if underflow occurred.
+        /// `None` if overflow occurred.
         ///
         /// # Examples
         ///
@@ -1581,7 +1581,7 @@ macro_rules! uint_impl {
         }
 
         /// Checked integer multiplication. Computes `self * rhs`, returning
-        /// `None` if underflow or overflow occurred.
+        /// `None` if overflow occurred.
         ///
         /// # Examples
         ///
@@ -1599,7 +1599,7 @@ macro_rules! uint_impl {
         }
 
         /// Checked integer division. Computes `self / rhs`, returning `None`
-        /// if `rhs == 0` or the operation results in underflow or overflow.
+        /// if `rhs == 0` or the operation results in overflow.
         ///
         /// # Examples
         ///
@@ -1619,7 +1619,7 @@ macro_rules! uint_impl {
         }
 
         /// Checked integer remainder. Computes `self % rhs`, returning `None`
-        /// if `rhs == 0` or the operation results in underflow or overflow.
+        /// if `rhs == 0` or the operation results in overflow.
         ///
         /// # Examples
         ///
diff --git a/src/libcore/ptr.rs b/src/libcore/ptr.rs
index 39cf2ec4c21..85bdeae442b 100644
--- a/src/libcore/ptr.rs
+++ b/src/libcore/ptr.rs
@@ -581,8 +581,7 @@ impl<T: ?Sized> *const T {
     /// * Both the starting and resulting pointer must be either in bounds or one
     ///   byte past the end of an allocated object.
     ///
-    /// * The computed offset, **in bytes**, cannot overflow or underflow an
-    ///   `isize`.
+    /// * The computed offset, **in bytes**, cannot overflow an `isize`.
     ///
     /// * The offset being in bounds cannot rely on "wrapping around" the address
     ///   space. That is, the infinite-precision sum, **in bytes** must fit in a usize.
@@ -714,8 +713,7 @@ impl<T: ?Sized> *const T {
     /// * Both the starting and resulting pointer must be either in bounds or one
     ///   byte past the end of an allocated object.
     ///
-    /// * The computed offset, **in bytes**, cannot overflow or underflow an
-    ///   `isize`.
+    /// * The computed offset, **in bytes**, cannot overflow an `isize`.
     ///
     /// * The offset being in bounds cannot rely on "wrapping around" the address
     ///   space. That is, the infinite-precision sum must fit in a `usize`.
@@ -1219,8 +1217,7 @@ impl<T: ?Sized> *mut T {
     /// * Both the starting and resulting pointer must be either in bounds or one
     ///   byte past the end of an allocated object.
     ///
-    /// * The computed offset, **in bytes**, cannot overflow or underflow an
-    ///   `isize`.
+    /// * The computed offset, **in bytes**, cannot overflow an `isize`.
     ///
     /// * The offset being in bounds cannot rely on "wrapping around" the address
     ///   space. That is, the infinite-precision sum, **in bytes** must fit in a usize.
@@ -1419,8 +1416,7 @@ impl<T: ?Sized> *mut T {
     /// * Both the starting and resulting pointer must be either in bounds or one
     ///   byte past the end of an allocated object.
     ///
-    /// * The computed offset, **in bytes**, cannot overflow or underflow an
-    ///   `isize`.
+    /// * The computed offset, **in bytes**, cannot overflow an `isize`.
     ///
     /// * The offset being in bounds cannot rely on "wrapping around" the address
     ///   space. That is, the infinite-precision sum must fit in a `usize`.