Trait core::iter::DoubleEndedIterator

pub trait DoubleEndedIterator: Iterator {
    fn next_back(&mut self) -> Option<Self::Item>;

    fn nth_back(&mut self, n: usize) -> Option<Self::Item> { ... }
    fn try_rfold<B, F, R>(&mut self, init: B, f: F) -> R
    where
        Self: Sized,
        F: FnMut(B, Self::Item) -> R,
        R: Try<Ok = B>,
    { ... }
    fn rfold<B, F>(self, accum: B, f: F) -> B
    where
        Self: Sized,
        F: FnMut(B, Self::Item) -> B,
    { ... }
    fn rfind<P>(&mut self, predicate: P) -> Option<Self::Item>
    where
        Self: Sized,
        P: FnMut(&Self::Item) -> bool,
    { ... }
}

An iterator able to yield elements from both ends.

Something that implements DoubleEndedIterator has one extra capability over something that implements Iterator: the ability to also take Items from the back, as well as the front.

It is important to note that both back and forth work on the same range, and do not cross: iteration is over when they meet in the middle.

In a similar fashion to the Iterator protocol, once a DoubleEndedIterator returns None from a next_back(), calling it again may or may not ever return Some again. next() and next_back() are interchangeable for this purpose.

Examples

Basic usage:

let numbers = vec![1, 2, 3, 4, 5, 6];

let mut iter = numbers.iter();

assert_eq!(Some(&1), iter.next());
assert_eq!(Some(&6), iter.next_back());
assert_eq!(Some(&5), iter.next_back());
assert_eq!(Some(&2), iter.next());
assert_eq!(Some(&3), iter.next());
assert_eq!(Some(&4), iter.next());
assert_eq!(None, iter.next());
assert_eq!(None, iter.next_back());

Required methods

fn next_back(&mut self) -> Option<Self::Item>

Removes and returns an element from the end of the iterator.

Returns None when there are no more elements.

The trait-level docs contain more details.

Examples

Basic usage:

let numbers = vec![1, 2, 3, 4, 5, 6];

let mut iter = numbers.iter();

assert_eq!(Some(&1), iter.next());
assert_eq!(Some(&6), iter.next_back());
assert_eq!(Some(&5), iter.next_back());
assert_eq!(Some(&2), iter.next());
assert_eq!(Some(&3), iter.next());
assert_eq!(Some(&4), iter.next());
assert_eq!(None, iter.next());
assert_eq!(None, iter.next_back());

Loading content...

Provided methods

fn nth_back(&mut self, n: usize) -> Option<Self::Item>

Returns the nth element from the end of the iterator.

This is essentially the reversed version of nth. Although like most indexing operations, the count starts from zero, so nth_back(0) returns the first value fro the end, nth_back(1) the second, and so on.

Note that all elements between the end and the returned element will be consumed, including the returned element. This also means that calling nth_back(0) multiple times on the same iterator will return different elements.

nth_back() will return None if n is greater than or equal to the length of the iterator.

Examples

Basic usage:

let a = [1, 2, 3];
assert_eq!(a.iter().nth_back(2), Some(&1));

Calling nth_back() multiple times doesn't rewind the iterator:

let a = [1, 2, 3];

let mut iter = a.iter();

assert_eq!(iter.nth_back(1), Some(&2));
assert_eq!(iter.nth_back(1), None);

Returning None if there are less than n + 1 elements:

let a = [1, 2, 3];
assert_eq!(a.iter().nth_back(10), None);

fn try_rfold<B, F, R>(&mut self, init: B, f: F) -> R where
    Self: Sized,
    F: FnMut(B, Self::Item) -> R,
    R: Try<Ok = B>, 

This is the reverse version of try_fold(): it takes elements starting from the back of the iterator.

Examples

Basic usage:

let a = ["1", "2", "3"];
let sum = a.iter()
    .map(|&s| s.parse::<i32>())
    .try_rfold(0, |acc, x| x.and_then(|y| Ok(acc + y)));
assert_eq!(sum, Ok(6));

Short-circuiting:

let a = ["1", "rust", "3"];
let mut it = a.iter();
let sum = it
    .by_ref()
    .map(|&s| s.parse::<i32>())
    .try_rfold(0, |acc, x| x.and_then(|y| Ok(acc + y)));
assert!(sum.is_err());

// Because it short-circuited, the remaining elements are still
// available through the iterator.
assert_eq!(it.next_back(), Some(&"1"));

fn rfold<B, F>(self, accum: B, f: F) -> B where
    Self: Sized,
    F: FnMut(B, Self::Item) -> B, 

An iterator method that reduces the iterator's elements to a single, final value, starting from the back.

This is the reverse version of fold(): it takes elements starting from the back of the iterator.

rfold() takes two arguments: an initial value, and a closure with two arguments: an 'accumulator', and an element. The closure returns the value that the accumulator should have for the next iteration.

The initial value is the value the accumulator will have on the first call.

After applying this closure to every element of the iterator, rfold() returns the accumulator.

This operation is sometimes called 'reduce' or 'inject'.

Folding is useful whenever you have a collection of something, and want to produce a single value from it.

Examples

Basic usage:

let a = [1, 2, 3];

// the sum of all of the elements of a
let sum = a.iter()
           .rfold(0, |acc, &x| acc + x);

assert_eq!(sum, 6);

This example builds a string, starting with an initial value and continuing with each element from the back until the front:

let numbers = [1, 2, 3, 4, 5];

let zero = "0".to_string();

let result = numbers.iter().rfold(zero, |acc, &x| {
    format!("({} + {})", x, acc)
});

assert_eq!(result, "(1 + (2 + (3 + (4 + (5 + 0)))))");

fn rfind<P>(&mut self, predicate: P) -> Option<Self::Item> where
    Self: Sized,
    P: FnMut(&Self::Item) -> bool, 

Searches for an element of an iterator from the back that satisfies a predicate.

rfind() takes a closure that returns true or false. It applies this closure to each element of the iterator, starting at the end, and if any of them return true, then rfind() returns Some(element). If they all return false, it returns None.

rfind() is short-circuiting; in other words, it will stop processing as soon as the closure returns true.

Because rfind() takes a reference, and many iterators iterate over references, this leads to a possibly confusing situation where the argument is a double reference. You can see this effect in the examples below, with &&x.

Examples

Basic usage:

let a = [1, 2, 3];

assert_eq!(a.iter().rfind(|&&x| x == 2), Some(&2));

assert_eq!(a.iter().rfind(|&&x| x == 5), None);

Stopping at the first true:

let a = [1, 2, 3];

let mut iter = a.iter();

assert_eq!(iter.rfind(|&&x| x == 2), Some(&2));

// we can still use `iter`, as there are more elements.
assert_eq!(iter.next_back(), Some(&1));

Loading content...

Implementors

impl DoubleEndedIterator for EscapeDefault

fn next_back(&mut self) -> Option<u8>

impl<'_> DoubleEndedIterator for Bytes<'_>

fn next_back(&mut self) -> Option<u8>

fn nth_back(&mut self, n: usize) -> Option<Self::Item>

fn rfind<P>(&mut self, predicate: P) -> Option<Self::Item> where
    P: FnMut(&Self::Item) -> bool, 

impl<'a> DoubleEndedIterator for CharIndices<'a>

fn next_back(&mut self) -> Option<(usize, char)>

impl<'a> DoubleEndedIterator for Chars<'a>

fn next_back(&mut self) -> Option<char>

impl<'a> DoubleEndedIterator for Lines<'a>

fn next_back(&mut self) -> Option<&'a str>

impl<'a> DoubleEndedIterator for LinesAny<'a>

fn next_back(&mut self) -> Option<&'a str>

impl<'a> DoubleEndedIterator for SplitAsciiWhitespace<'a>

fn next_back(&mut self) -> Option<&'a str>

impl<'a> DoubleEndedIterator for SplitWhitespace<'a>

fn next_back(&mut self) -> Option<&'a str>

impl<'a, A> DoubleEndedIterator for core::option::Iter<'a, A>

fn next_back(&mut self) -> Option<&'a A>

impl<'a, A> DoubleEndedIterator for core::option::IterMut<'a, A>

fn next_back(&mut self) -> Option<&'a mut A>

impl<'a, I, T: 'a> DoubleEndedIterator for Cloned<I> where
    I: DoubleEndedIterator<Item = &'a T>,
    T: Clone, 

fn next_back(&mut self) -> Option<T>

fn try_rfold<B, F, R>(&mut self, init: B, f: F) -> R where
    Self: Sized,
    F: FnMut(B, Self::Item) -> R,
    R: Try<Ok = B>, 

fn rfold<Acc, F>(self, init: Acc, f: F) -> Acc where
    F: FnMut(Acc, Self::Item) -> Acc, 

impl<'a, I, T: 'a> DoubleEndedIterator for Copied<I> where
    I: DoubleEndedIterator<Item = &'a T>,
    T: Copy, 

fn next_back(&mut self) -> Option<T>

fn try_rfold<B, F, R>(&mut self, init: B, f: F) -> R where
    Self: Sized,
    F: FnMut(B, Self::Item) -> R,
    R: Try<Ok = B>, 

fn rfold<Acc, F>(self, init: Acc, f: F) -> Acc where
    F: FnMut(Acc, Self::Item) -> Acc, 

impl<'a, I: DoubleEndedIterator + ?Sized> DoubleEndedIterator for &'a mut I

fn next_back(&mut self) -> Option<I::Item>

fn nth_back(&mut self, n: usize) -> Option<I::Item>

impl<'a, P: Pattern<'a>> DoubleEndedIterator for MatchIndices<'a, P> where
    P::Searcher: DoubleEndedSearcher<'a>, 

fn next_back(&mut self) -> Option<(usize, &'a str)>

impl<'a, P: Pattern<'a>> DoubleEndedIterator for Matches<'a, P> where
    P::Searcher: DoubleEndedSearcher<'a>, 

fn next_back(&mut self) -> Option<&'a str>

impl<'a, P: Pattern<'a>> DoubleEndedIterator for RMatchIndices<'a, P> where
    P::Searcher: DoubleEndedSearcher<'a>, 

fn next_back(&mut self) -> Option<(usize, &'a str)>

impl<'a, P: Pattern<'a>> DoubleEndedIterator for RMatches<'a, P> where
    P::Searcher: DoubleEndedSearcher<'a>, 

fn next_back(&mut self) -> Option<&'a str>

impl<'a, P: Pattern<'a>> DoubleEndedIterator for core::str::RSplit<'a, P> where
    P::Searcher: DoubleEndedSearcher<'a>, 

fn next_back(&mut self) -> Option<&'a str>

impl<'a, P: Pattern<'a>> DoubleEndedIterator for RSplitTerminator<'a, P> where
    P::Searcher: DoubleEndedSearcher<'a>, 

fn next_back(&mut self) -> Option<&'a str>

impl<'a, P: Pattern<'a>> DoubleEndedIterator for core::str::Split<'a, P> where
    P::Searcher: DoubleEndedSearcher<'a>, 

fn next_back(&mut self) -> Option<&'a str>

impl<'a, P: Pattern<'a>> DoubleEndedIterator for SplitTerminator<'a, P> where
    P::Searcher: DoubleEndedSearcher<'a>, 

fn next_back(&mut self) -> Option<&'a str>

impl<'a, T> DoubleEndedIterator for core::result::Iter<'a, T>

fn next_back(&mut self) -> Option<&'a T>

impl<'a, T> DoubleEndedIterator for core::result::IterMut<'a, T>

fn next_back(&mut self) -> Option<&'a mut T>

impl<'a, T> DoubleEndedIterator for Chunks<'a, T>

fn next_back(&mut self) -> Option<&'a [T]>

fn nth_back(&mut self, n: usize) -> Option<Self::Item>

impl<'a, T> DoubleEndedIterator for ChunksExact<'a, T>

fn next_back(&mut self) -> Option<&'a [T]>

impl<'a, T> DoubleEndedIterator for ChunksExactMut<'a, T>

fn next_back(&mut self) -> Option<&'a mut [T]>

impl<'a, T> DoubleEndedIterator for ChunksMut<'a, T>

fn next_back(&mut self) -> Option<&'a mut [T]>

impl<'a, T> DoubleEndedIterator for core::slice::Iter<'a, T>

fn next_back(&mut self) -> Option<&'a T>

fn try_rfold<B, F, R>(&mut self, init: B, f: F) -> R where
    Self: Sized,
    F: FnMut(B, Self::Item) -> R,
    R: Try<Ok = B>, 

fn rfold<Acc, Fold>(self, init: Acc, f: Fold) -> Acc where
    Fold: FnMut(Acc, Self::Item) -> Acc, 

impl<'a, T> DoubleEndedIterator for core::slice::IterMut<'a, T>

fn next_back(&mut self) -> Option<&'a mut T>

fn try_rfold<B, F, R>(&mut self, init: B, f: F) -> R where
    Self: Sized,
    F: FnMut(B, Self::Item) -> R,
    R: Try<Ok = B>, 

fn rfold<Acc, Fold>(self, init: Acc, f: Fold) -> Acc where
    Fold: FnMut(Acc, Self::Item) -> Acc, 

impl<'a, T> DoubleEndedIterator for RChunks<'a, T>

fn next_back(&mut self) -> Option<&'a [T]>

fn nth_back(&mut self, n: usize) -> Option<Self::Item>

impl<'a, T> DoubleEndedIterator for RChunksExact<'a, T>

fn next_back(&mut self) -> Option<&'a [T]>

fn nth_back(&mut self, n: usize) -> Option<Self::Item>

impl<'a, T> DoubleEndedIterator for RChunksExactMut<'a, T>

fn next_back(&mut self) -> Option<&'a mut [T]>

fn nth_back(&mut self, n: usize) -> Option<Self::Item>

impl<'a, T> DoubleEndedIterator for RChunksMut<'a, T>

fn next_back(&mut self) -> Option<&'a mut [T]>

fn nth_back(&mut self, n: usize) -> Option<Self::Item>

impl<'a, T> DoubleEndedIterator for Windows<'a, T>

fn next_back(&mut self) -> Option<&'a [T]>

fn nth_back(&mut self, n: usize) -> Option<Self::Item>

impl<'a, T, P> DoubleEndedIterator for core::slice::RSplit<'a, T, P> where
    P: FnMut(&T) -> bool, 

fn next_back(&mut self) -> Option<&'a [T]>

impl<'a, T, P> DoubleEndedIterator for RSplitMut<'a, T, P> where
    P: FnMut(&T) -> bool, 

fn next_back(&mut self) -> Option<&'a mut [T]>

impl<'a, T, P> DoubleEndedIterator for core::slice::Split<'a, T, P> where
    P: FnMut(&T) -> bool, 

fn next_back(&mut self) -> Option<&'a [T]>

impl<'a, T, P> DoubleEndedIterator for SplitMut<'a, T, P> where
    P: FnMut(&T) -> bool, 

fn next_back(&mut self) -> Option<&'a mut [T]>

impl<A> DoubleEndedIterator for core::option::IntoIter<A>

fn next_back(&mut self) -> Option<A>

impl<A, B> DoubleEndedIterator for Chain<A, B> where
    A: DoubleEndedIterator,
    B: DoubleEndedIterator<Item = A::Item>, 

fn next_back(&mut self) -> Option<A::Item>

fn try_rfold<Acc, F, R>(&mut self, init: Acc, f: F) -> R where
    Self: Sized,
    F: FnMut(Acc, Self::Item) -> R,
    R: Try<Ok = Acc>, 

fn rfold<Acc, F>(self, init: Acc, f: F) -> Acc where
    F: FnMut(Acc, Self::Item) -> Acc, 

impl<A, B> DoubleEndedIterator for Zip<A, B> where
    A: DoubleEndedIterator + ExactSizeIterator,
    B: DoubleEndedIterator + ExactSizeIterator, 

fn next_back(&mut self) -> Option<(A::Item, B::Item)>

impl<A, F: FnOnce() -> A> DoubleEndedIterator for OnceWith<F>

fn next_back(&mut self) -> Option<A>

impl<A: Clone> DoubleEndedIterator for Repeat<A>

fn next_back(&mut self) -> Option<A>

impl<A: Step> DoubleEndedIterator for Range<A>

fn next_back(&mut self) -> Option<A>

impl<A: Step> DoubleEndedIterator for RangeInclusive<A>

fn next_back(&mut self) -> Option<A>

fn try_rfold<B, F, R>(&mut self, init: B, f: F) -> R where
    Self: Sized,
    F: FnMut(B, Self::Item) -> R,
    R: Try<Ok = B>, 

impl<B, I: DoubleEndedIterator, F> DoubleEndedIterator for FilterMap<I, F> where
    F: FnMut(I::Item) -> Option<B>, 

fn next_back(&mut self) -> Option<B>

fn try_rfold<Acc, Fold, R>(&mut self, init: Acc, fold: Fold) -> R where
    Self: Sized,
    Fold: FnMut(Acc, Self::Item) -> R,
    R: Try<Ok = Acc>, 

fn rfold<Acc, Fold>(self, init: Acc, fold: Fold) -> Acc where
    Fold: FnMut(Acc, Self::Item) -> Acc, 

impl<B, I: DoubleEndedIterator, F> DoubleEndedIterator for Map<I, F> where
    F: FnMut(I::Item) -> B, 

fn next_back(&mut self) -> Option<B>

fn try_rfold<Acc, G, R>(&mut self, init: Acc, g: G) -> R where
    Self: Sized,
    G: FnMut(Acc, Self::Item) -> R,
    R: Try<Ok = Acc>, 

fn rfold<Acc, G>(self, init: Acc, g: G) -> Acc where
    G: FnMut(Acc, Self::Item) -> Acc, 

impl<I> DoubleEndedIterator for Enumerate<I> where
    I: ExactSizeIterator + DoubleEndedIterator, 

fn next_back(&mut self) -> Option<(usize, <I as Iterator>::Item)>

fn nth_back(&mut self, n: usize) -> Option<(usize, <I as Iterator>::Item)>

fn try_rfold<Acc, Fold, R>(&mut self, init: Acc, fold: Fold) -> R where
    Self: Sized,
    Fold: FnMut(Acc, Self::Item) -> R,
    R: Try<Ok = Acc>, 

fn rfold<Acc, Fold>(self, init: Acc, fold: Fold) -> Acc where
    Fold: FnMut(Acc, Self::Item) -> Acc, 

impl<I> DoubleEndedIterator for Fuse<I> where
    I: DoubleEndedIterator + FusedIterator, 

fn next_back(&mut self) -> Option<<I as Iterator>::Item>

fn nth_back(&mut self, n: usize) -> Option<<I as Iterator>::Item>

fn try_rfold<Acc, Fold, R>(&mut self, init: Acc, fold: Fold) -> R where
    Self: Sized,
    Fold: FnMut(Acc, Self::Item) -> R,
    R: Try<Ok = Acc>, 

fn rfold<Acc, Fold>(self, init: Acc, fold: Fold) -> Acc where
    Fold: FnMut(Acc, Self::Item) -> Acc, 

impl<I> DoubleEndedIterator for Fuse<I> where
    I: DoubleEndedIterator, 

default fn next_back(&mut self) -> Option<<I as Iterator>::Item>

default fn nth_back(&mut self, n: usize) -> Option<<I as Iterator>::Item>

default fn try_rfold<Acc, Fold, R>(&mut self, init: Acc, fold: Fold) -> R where
    Self: Sized,
    Fold: FnMut(Acc, Self::Item) -> R,
    R: Try<Ok = Acc>, 

default fn rfold<Acc, Fold>(self, init: Acc, fold: Fold) -> Acc where
    Fold: FnMut(Acc, Self::Item) -> Acc, 

impl<I> DoubleEndedIterator for Rev<I> where
    I: DoubleEndedIterator, 

fn next_back(&mut self) -> Option<<I as Iterator>::Item>

fn nth_back(&mut self, n: usize) -> Option<<I as Iterator>::Item>

fn try_rfold<B, F, R>(&mut self, init: B, f: F) -> R where
    Self: Sized,
    F: FnMut(B, Self::Item) -> R,
    R: Try<Ok = B>, 

fn rfold<Acc, F>(self, init: Acc, f: F) -> Acc where
    F: FnMut(Acc, Self::Item) -> Acc, 

fn rfind<P>(&mut self, predicate: P) -> Option<Self::Item> where
    P: FnMut(&Self::Item) -> bool, 

impl<I> DoubleEndedIterator for Skip<I> where
    I: DoubleEndedIterator + ExactSizeIterator, 

fn next_back(&mut self) -> Option<Self::Item>

fn try_rfold<Acc, Fold, R>(&mut self, init: Acc, fold: Fold) -> R where
    Self: Sized,
    Fold: FnMut(Acc, Self::Item) -> R,
    R: Try<Ok = Acc>, 

impl<I, U> DoubleEndedIterator for Flatten<I> where
    I: DoubleEndedIterator,
    U: DoubleEndedIterator,
    I::Item: IntoIterator<IntoIter = U, Item = U::Item>, 

fn next_back(&mut self) -> Option<U::Item>

fn try_rfold<Acc, Fold, R>(&mut self, init: Acc, fold: Fold) -> R where
    Self: Sized,
    Fold: FnMut(Acc, Self::Item) -> R,
    R: Try<Ok = Acc>, 

fn rfold<Acc, Fold>(self, init: Acc, fold: Fold) -> Acc where
    Fold: FnMut(Acc, Self::Item) -> Acc, 

impl<I: DoubleEndedIterator, F> DoubleEndedIterator for Inspect<I, F> where
    F: FnMut(&I::Item), 

fn next_back(&mut self) -> Option<I::Item>

fn try_rfold<Acc, Fold, R>(&mut self, init: Acc, fold: Fold) -> R where
    Self: Sized,
    Fold: FnMut(Acc, Self::Item) -> R,
    R: Try<Ok = Acc>, 

fn rfold<Acc, Fold>(self, init: Acc, fold: Fold) -> Acc where
    Fold: FnMut(Acc, Self::Item) -> Acc, 

impl<I: DoubleEndedIterator, P> DoubleEndedIterator for Filter<I, P> where
    P: FnMut(&I::Item) -> bool, 

fn next_back(&mut self) -> Option<I::Item>

fn try_rfold<Acc, Fold, R>(&mut self, init: Acc, fold: Fold) -> R where
    Self: Sized,
    Fold: FnMut(Acc, Self::Item) -> R,
    R: Try<Ok = Acc>, 

fn rfold<Acc, Fold>(self, init: Acc, fold: Fold) -> Acc where
    Fold: FnMut(Acc, Self::Item) -> Acc, 

impl<I: DoubleEndedIterator, U, F> DoubleEndedIterator for FlatMap<I, U, F> where
    F: FnMut(I::Item) -> U,
    U: IntoIterator,
    U::IntoIter: DoubleEndedIterator, 

fn next_back(&mut self) -> Option<U::Item>

fn try_rfold<Acc, Fold, R>(&mut self, init: Acc, fold: Fold) -> R where
    Self: Sized,
    Fold: FnMut(Acc, Self::Item) -> R,
    R: Try<Ok = Acc>, 

fn rfold<Acc, Fold>(self, init: Acc, fold: Fold) -> Acc where
    Fold: FnMut(Acc, Self::Item) -> Acc, 

impl<T> DoubleEndedIterator for Empty<T>

fn next_back(&mut self) -> Option<T>

impl<T> DoubleEndedIterator for Once<T>

fn next_back(&mut self) -> Option<T>

impl<T> DoubleEndedIterator for core::result::IntoIter<T>

fn next_back(&mut self) -> Option<T>

Loading content...