8bd4ed9f95
Add Iterator::advance_by and DoubleEndedIterator::advance_back_by This PR adds the iterator method ```rust 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 #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 |
||
|---|---|---|
| .. | ||
| benches | ||
| src | ||
| tests | ||
| Cargo.toml | ||