From 39fcfa8ccb4605e307eed4c7515b58c5edc97c74 Mon Sep 17 00:00:00 2001 From: Emerentius Date: Tue, 10 Jul 2018 00:00:51 +0200 Subject: [PATCH] step_by: leave time of item skip unspecified this gives us some leeway when optimizing --- src/libcore/iter/iterator.rs | 23 ++++++++++++++++++++++- 1 file changed, 22 insertions(+), 1 deletion(-) diff --git a/src/libcore/iter/iterator.rs b/src/libcore/iter/iterator.rs index 8836de3edc874..c0681619bf8b5 100644 --- a/src/libcore/iter/iterator.rs +++ b/src/libcore/iter/iterator.rs @@ -271,9 +271,30 @@ pub trait Iterator { /// Creates an iterator starting at the same point, but stepping by /// the given amount at each iteration. /// - /// Note that it will always return the first element of the iterator, + /// Note 1: The first element of the iterator will always be returned, /// regardless of the step given. /// + /// Note 2: The time at which ignored elements are pulled is not fixed. + /// `StepBy` behaves like the sequence `next(), nth(step-1), nth(step-1), …`, + /// but is also free to behave like the sequence + /// `advance_n_and_return_first(step), advance_n_and_return_first(step), …` + /// Which way is used may change for some iterators for performance reasons. + /// The second way will advance the iterator earlier and may consume more items. + /// + /// `advance_n_and_return_first` is the equivalent of: + /// ``` + /// fn advance_n_and_return_first(iter: &mut I, total_step: usize) -> Option + /// where + /// I: Iterator, + /// { + /// let next = iter.next(); + /// if total_step > 1 { + /// iter.nth(total_step-2); + /// } + /// next + /// } + /// ``` + /// /// # Panics /// /// The method will panic if the given step is `0`.