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.

Author: kennytm

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.

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
         ///

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`.

src/libstd/io/buffered.rs

@@ -263,7 +263,7 @@ impl<R: Seek> Seek for BufReader<R> {
     /// See `std::io::Seek` for more details.
     ///
     /// Note: In the edge case where you're seeking with `SeekFrom::Current(n)`
-    /// where `n` minus the internal buffer length underflows an `i64`, two
+    /// where `n` minus the internal buffer length overflows an `i64`, two
     /// seeks will be performed instead of one. If the second seek returns
     /// `Err`, the underlying reader will be left at the same position it would
     /// have if you seeked to `SeekFrom::Current(0)`.

src/libstd/time/duration.rs

@@ -290,7 +290,7 @@ impl Duration {
     }
 
     /// Checked `Duration` subtraction. Computes `self - other`, returning [`None`]
-    /// if the result would be negative or if underflow occurred.
+    /// if the result would be negative or if overflow occurred.
     ///
     /// [`None`]: ../../std/option/enum.Option.html#variant.None
     ///