Add Iterator::advance_by and DoubleEndedIterator::advance_back_by by timvermeulen · Pull Request #76909 · rust-lang/rust (original) (raw)

This PR adds the iterator method

fn advance_by(&mut self, n: usize) -> Result<(), usize>

that advances the iterator by n elements, returning Ok(()) if this succeeds or Err(len) if the length of the iterator was less than n.

Currently Iterator::nth is the method to override for efficiently advancing an iterator by multiple elements at once. advance_by is superior for this purpose because

• it's simpler to implement: instead of advancing the iterator and producing the next element you only need to advance the iterator
• it composes better: iterators like Chain and FlatMap can implement advance_by in terms of advance_by on their inner iterators, but they cannot implement nth in terms of nth on their inner iterators (see Iterator::nth doesn't compose well #60395)
• the default implementation of nth can trivially be implemented in terms of advance_by and next, which this PR also does

This PR also adds DoubleEndedIterator::advance_back_by for all the same reasons.

I'll make a tracking issue if it's decided this is worth merging. Also let me know if anything can be improved, this went through several iterations so there might very well still be room for improvement (especially in the doc comments). I've written overrides of these methods for most iterators that already override nth/nth_back, but those still need tests so I'll add them in a later PR.

cc @cuviper @scottmcm @Amanieu