Make overflow behaviour more obvious in the iterator module of libcore

Added documentation of the panicking overflow to the `count` and `position`
methods of `IteratorExt`, also make them more obvious in the code.

Also mention that the `Iterator::next` method of the struct returned by
`IteratorExt::enumerate` can panic due to overflow.

Author: tbu-

src/libcore/iter.rs

@@ -106,6 +106,10 @@ pub trait Iterator {
 
     /// Counts the number of elements in this iterator.
     ///
+    /// # Panics
+    ///
+    /// Panics if the number of elements overflows a `usize`.
+    ///
     /// # Examples
     ///
     /// ```
@@ -115,7 +119,10 @@ pub trait Iterator {
     #[inline]
     #[stable(feature = "rust1", since = "1.0.0")]
     fn count(self) -> usize where Self: Sized {
-        self.fold(0, |cnt, _x| cnt + 1)
+        self.fold(0, |cnt, _| match cnt.checked_add(1) {
+            Some(c) => c,
+            None => panic!("overflow while counting the elements of an iterator"),
+        })
     }
 
     /// Loops through the entire iterator, returning the last element.
@@ -149,8 +156,10 @@ pub trait Iterator {
     #[stable(feature = "rust1", since = "1.0.0")]
     fn nth(&mut self, mut n: usize) -> Option<Self::Item> where Self: Sized {
         for x in self.by_ref() {
-            if n == 0 { return Some(x) }
-            n -= 1;
+            n = match n.checked_sub(1) {
+                Some(nn) => nn,
+                None => return Some(x),
+            }
         }
         None
     }
@@ -277,6 +286,11 @@ pub trait Iterator {
     /// `enumerate` keeps its count as a `usize`. If you want to count by a
     /// different sized integer, the `zip` function provides similar functionality.
     ///
+    /// # Panics
+    ///
+    /// The returned iterator will panic if the to-be-returned index would
+    /// overflow a `usize`.
+    ///
     /// # Examples
     ///
     /// ```
@@ -289,7 +303,7 @@ pub trait Iterator {
     #[inline]
     #[stable(feature = "rust1", since = "1.0.0")]
     fn enumerate(self) -> Enumerate<Self> where Self: Sized {
-        Enumerate{iter: self, count: 0}
+        Enumerate { iter: self, count: Some(0) }
     }
 
     /// Creates an iterator that has a `.peek()` method
@@ -665,6 +679,11 @@ pub trait Iterator {
     ///
     /// Does not consume the iterator past the first found element.
     ///
+    /// # Panics
+    ///
+    /// Panics if the number of elements overflows a `usize` and no matching
+    /// element was found until that point.
+    ///
     /// # Examples
     ///
     /// ```
@@ -684,7 +703,10 @@ pub trait Iterator {
             if predicate(x) {
                 return Some(i);
             }
-            i += 1;
+            i = match i.checked_add(1) {
+                Some(ii) => ii,
+                None => panic!("overflow while getting the position of an element in an iterator"),
+            }
         }
         None
     }
@@ -715,6 +737,8 @@ pub trait Iterator {
             if predicate(v) {
                 return Some(i - 1);
             }
+            // No need for an overflow check here, because `ExactSizeIterator`
+            // implies that the number of elements fits into a `usize`.
             i -= 1;
         }
         None
@@ -1761,19 +1785,26 @@ impl<B, I: DoubleEndedIterator, F> DoubleEndedIterator for FilterMap<I, F>
 #[stable(feature = "rust1", since = "1.0.0")]
 pub struct Enumerate<I> {
     iter: I,
-    count: usize
+    count: Option<usize>,
 }
 
 #[stable(feature = "rust1", since = "1.0.0")]
 impl<I> Iterator for Enumerate<I> where I: Iterator {
     type Item = (usize, <I as Iterator>::Item);
 
+    /// # Panics
+    ///
+    /// Panics if the index of the element overflows a `usize`.
     #[inline]
     fn next(&mut self) -> Option<(usize, <I as Iterator>::Item)> {
         match self.iter.next() {
             Some(a) => {
-                let ret = Some((self.count, a));
-                self.count += 1;
+                let count = match self.count {
+                    Some(c) => c,
+                    None => panic!("overflow while enumerating an iterator"),
+                };
+                let ret = Some((count, a));
+                self.count = count.checked_add(1);
                 ret
             }
             _ => None
@@ -1795,7 +1826,9 @@ impl<I> DoubleEndedIterator for Enumerate<I> where
         match self.iter.next_back() {
             Some(a) => {
                 let len = self.iter.len();
-                Some((self.count + len, a))
+                // Can safely `unwrap`, `ExactSizeIterator` promises that the
+                // number of elements fits into a `usize`.
+                Some((self.count.unwrap() + len, a))
             }
             _ => None
         }
@@ -1812,7 +1845,10 @@ impl<I> RandomAccessIterator for Enumerate<I> where I: RandomAccessIterator {
     #[inline]
     fn idx(&mut self, index: usize) -> Option<(usize, <I as Iterator>::Item)> {
         match self.iter.idx(index) {
-            Some(a) => Some((self.count + index, a)),
+            // Can safely `unwrap`, `ExactSizeIterator` (ancestor of
+            // `RandomAccessIterator`) promises that the number of elements
+            // fits into a `usize`.
+            Some(a) => Some((self.count.unwrap() + index, a)),
             _ => None,
         }
     }