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
     }
@@ -280,6 +289,16 @@ pub trait Iterator {
     /// different sized integer, the `zip` function provides similar
     /// functionality.
     ///
+    /// # Undefined overflow
+    ///
+    /// The method does no guarding against overflows, so enumerating more than
+    /// `usize::MAX` elements is undefined.
+    ///
+    /// # Panics
+    ///
+    /// The returned iterator might panic if the to-be-returned index would
+    /// overflow a `usize`.
+    ///
     /// # Examples
     ///
     /// ```
@@ -292,7 +311,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: 0 }
     }
 
     /// Creates an iterator that has a `.peek()` method
@@ -674,6 +693,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
     ///
     /// ```
@@ -693,7 +717,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
     }
@@ -724,6 +751,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,17 +1790,27 @@ 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: usize,
 }
 
 #[stable(feature = "rust1", since = "1.0.0")]
 impl<I> Iterator for Enumerate<I> where I: Iterator {
     type Item = (usize, <I as Iterator>::Item);
 
+
+    /// # Undefined overflow
+    ///
+    /// The method does no guarding against overflows, so enumerating more than
+    /// `usize::MAX` elements is undefined.
+    ///
+    /// # Panics
+    ///
+    /// Might panic if the index of the element overflows a `usize`.
     #[inline]
     fn next(&mut self) -> Option<(usize, <I as Iterator>::Item)> {
         self.iter.next().map(|a| {
             let ret = (self.count, a);
+            // Possible undefined overflow.
             self.count += 1;
             ret
         })
@@ -1791,6 +1830,8 @@ impl<I> DoubleEndedIterator for Enumerate<I> where
     fn next_back(&mut self) -> Option<(usize, <I as Iterator>::Item)> {
         self.iter.next_back().map(|a| {
             let len = self.iter.len();
+            // Can safely add, `ExactSizeIterator` promises that the number of
+            // elements fits into a `usize`.
             (self.count + len, a)
         })
     }
@@ -1805,6 +1846,9 @@ impl<I> RandomAccessIterator for Enumerate<I> where I: RandomAccessIterator {
 
     #[inline]
     fn idx(&mut self, index: usize) -> Option<(usize, <I as Iterator>::Item)> {
+        // Can safely add, `ExactSizeIterator` (ancestor of
+        // `RandomAccessIterator`) promises that the number of elements fits
+        // into a `usize`.
         self.iter.idx(index).map(|a| (self.count + index, a))
     }
 }