diff --git a/src/libcore/iter/iterator.rs b/src/libcore/iter/iterator.rs index 79767b37601f8..f8fb35e1428fe 100644 --- a/src/libcore/iter/iterator.rs +++ b/src/libcore/iter/iterator.rs @@ -660,6 +660,11 @@ pub trait Iterator { /// current index of iteration and `val` is the value returned by the /// iterator. /// + /// The index of iteration starts at zero. + /// To count from a different value, see [`enumerate_from`]. + /// + /// [`enumerate_from`]: ../../std/iter/trait.Iterator.html#method.enumerate_from + /// /// `enumerate()` keeps its count as a [`usize`]. If you want to count by a /// different sized integer, the [`zip`] function provides similar /// functionality. @@ -697,6 +702,49 @@ pub trait Iterator { Enumerate { iter: self, count: 0 } } + /// Creates an iterator which gives the current iteration count, + /// starting with `first`, + /// as well as the next value. + /// + /// When `first` is zero this is equivalent to [`enumerate`]. + /// + /// [`enumerate`]: ../../std/iter/trait.Iterator.html#method.enumerate + /// + /// # Overflow Behavior + /// + /// The method does no guarding against overflows, so enumerating + /// beyond index [`usize::MAX`] either produces the wrong result or panics. + /// If debug assertions are enabled, a panic is guaranteed. + /// + /// # Panics + /// + /// The returned iterator might panic if the to-be-returned index would + /// overflow a [`usize`]. + /// + /// [`usize::MAX`]: ../../std/usize/constant.MAX.html + /// [`usize`]: ../../std/primitive.usize.html + /// [`zip`]: #method.zip + /// + /// # Examples + /// + /// ``` + /// #![feature(enumerate_from)] + /// + /// let a = ['a', 'b', 'c']; + /// + /// let mut iter = a.iter().enumerate_from(1); + /// + /// assert_eq!(iter.next(), Some((1, &'a'))); + /// assert_eq!(iter.next(), Some((2, &'b'))); + /// assert_eq!(iter.next(), Some((3, &'c'))); + /// assert_eq!(iter.next(), None); + /// ``` + #[inline] + #[unstable(feature = "enumerate_from", issue = /* FIXME */ "0")] + fn enumerate_from(self, first: usize) -> Enumerate where Self: Sized { + Enumerate { iter: self, count: first } + } + /// Creates an iterator which can use `peek` to look at the next element of /// the iterator without consuming it. /// diff --git a/src/libcore/tests/iter.rs b/src/libcore/tests/iter.rs index f8c6fc5c8fa42..2b2b5a14b3db7 100644 --- a/src/libcore/tests/iter.rs +++ b/src/libcore/tests/iter.rs @@ -276,6 +276,15 @@ fn test_iterator_enumerate() { } } +#[test] +fn test_iterator_enumerate_from() { + let xs = [2, 3, 4, 5]; + let it = xs.iter().enumerate_from(2); + for (i, &x) in it { + assert_eq!(i, x); + } +} + #[test] fn test_iterator_enumerate_nth() { let xs = [0, 1, 2, 3, 4, 5]; diff --git a/src/libcore/tests/lib.rs b/src/libcore/tests/lib.rs index afc5de7b0ee35..01a561a560654 100644 --- a/src/libcore/tests/lib.rs +++ b/src/libcore/tests/lib.rs @@ -16,6 +16,7 @@ #![feature(core_private_diy_float)] #![feature(dec2flt)] #![feature(decode_utf8)] +#![feature(enumerate_from)] #![feature(exact_size_is_empty)] #![feature(fixed_size_array)] #![feature(flt2dec)]