std::iter::DoubleEndedIterator - Rust
Description: API documentation for the Rust `DoubleEndedIterator` trait in crate `std`.
Keywords: rust, rustlang, rust-lang, DoubleEndedIterator

# Trait std::iter::DoubleEndedIterator 1.0.0[−][src]

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

        fn try_rfold<B, F, R>(&mut self, init: B, f: F) -> R
        where
            F: FnMut(B, Self::Item) -> R,
            R: Try<Ok = B>,
        { ... }
        fn rfold<B, F>(self, accum: B, f: F) -> B
        where
            F: FnMut(B, Self::Item) -> B,
        { ... }
        fn rfind<P>(&mut self, predicate: P) -> Option<Self::Item>
        where
            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 `Item`s 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());Run

## 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());Run

## Provided Methods

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

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));Run

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"));Run

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

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);Run

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)))))");Run

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

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);Run

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));Run

## Implementors

- `impl<'a, T> DoubleEndedIterator for Windows<'a, T>` | [src]

- `impl<A> DoubleEndedIterator for Repeat<A> where A: Clone,` | [src]

- `impl<A> DoubleEndedIterator for std::ops::Range<A> where A: Step,` | [src]

- `impl<T> DoubleEndedIterator for Once<T>` | [src]

- `impl<'a, P> DoubleEndedIterator for RSplitTerminator<'a, P> where P: Pattern<'a>, <P as Pattern<'a>>::Searcher: DoubleEndedSearcher<'a>,` | [src]

- `impl<I> DoubleEndedIterator for Enumerate<I> where I: ExactSizeIterator + DoubleEndedIterator,` | [src]

- `impl DoubleEndedIterator for EscapeDefault` | [src]

- `impl<I, F> DoubleEndedIterator for Inspect<I, F> where F: FnMut(&<I as Iterator>::Item), I: DoubleEndedIterator,` | [src]

- `impl<'a, T> DoubleEndedIterator for ChunksMut<'a, T>` | [src]

- `impl<'a, T, P> DoubleEndedIterator for SplitMut<'a, T, P> where P: FnMut(&T) -> bool,` | [src]

- `impl<'a, T, P> DoubleEndedIterator for std::slice::Split<'a, T, P> where P: FnMut(&T) -> bool,` | [src]

- `impl<'a, T> DoubleEndedIterator for ExactChunks<'a, T>` | [src]

- `impl<B, I, F> DoubleEndedIterator for Map<I, F> where F: FnMut(<I as Iterator>::Item) -> B, I: DoubleEndedIterator,` | [src]

- `impl<I> DoubleEndedIterator for Fuse<I> where I: DoubleEndedIterator,` | [src]

- `impl<T> DoubleEndedIterator for std::result::IntoIter<T>` | [src]

- `impl<'a, P> DoubleEndedIterator for std::str::RSplit<'a, P> where P: Pattern<'a>, <P as Pattern<'a>>::Searcher: DoubleEndedSearcher<'a>,` | [src]

- `impl<'a, P> DoubleEndedIterator for std::str::Split<'a, P> where P: Pattern<'a>, <P as Pattern<'a>>::Searcher: DoubleEndedSearcher<'a>,` | [src]

- `impl<'a, I> DoubleEndedIterator for &'a mut I where I: DoubleEndedIterator + ?Sized,` | [src]

- `impl<I> DoubleEndedIterator for Rev<I> where I: DoubleEndedIterator,` | [src]

- `impl<'a> DoubleEndedIterator for SplitAsciiWhitespace<'a>` | [src]

- `impl<I> DoubleEndedIterator for Fuse<I> where I: DoubleEndedIterator + FusedIterator,` | [src]

- `impl<A, B> DoubleEndedIterator for Chain<A, B> where A: DoubleEndedIterator, B: DoubleEndedIterator<Item = <A as Iterator>::Item>,` | [src]

- `impl<'a, P> DoubleEndedIterator for RMatches<'a, P> where P: Pattern<'a>, <P as Pattern<'a>>::Searcher: DoubleEndedSearcher<'a>,` | [src]

- `impl<'a> DoubleEndedIterator for Chars<'a>` | [src]

- `impl<'a, P> DoubleEndedIterator for SplitTerminator<'a, P> where P: Pattern<'a>, <P as Pattern<'a>>::Searcher: DoubleEndedSearcher<'a>,` | [src]

- `impl<'a, T> DoubleEndedIterator for std::slice::Iter<'a, T>` | [src]

- `impl<I, U, F> DoubleEndedIterator for FlatMap<I, U, F> where F: FnMut(<I as Iterator>::Item) -> U, I: DoubleEndedIterator, U: IntoIterator, <U as IntoIterator>::IntoIter: DoubleEndedIterator,` | [src]

- `impl<'a, A> DoubleEndedIterator for std::option::IterMut<'a, A>` | [src]

- `impl<'a, P> DoubleEndedIterator for Matches<'a, P> where P: Pattern<'a>, <P as Pattern<'a>>::Searcher: DoubleEndedSearcher<'a>,` | [src]

- `impl<'a> DoubleEndedIterator for Lines<'a>` | [src]

- `impl<'a> DoubleEndedIterator for CharIndices<'a>` | [src]

- `impl<'a> DoubleEndedIterator for Bytes<'a>` | [src]

- `impl<'a, A> DoubleEndedIterator for std::option::Iter<'a, A>` | [src]

- `impl<'a, I, T> DoubleEndedIterator for Cloned<I> where I: DoubleEndedIterator<Item = &'a T>, T: 'a + Clone,` | [src]

- `impl<'a, T> DoubleEndedIterator for std::result::Iter<'a, T>` | [src]

- `impl<'a, P> DoubleEndedIterator for MatchIndices<'a, P> where P: Pattern<'a>, <P as Pattern<'a>>::Searcher: DoubleEndedSearcher<'a>,` | [src]

- `impl<'a, T, P> DoubleEndedIterator for RSplitMut<'a, T, P> where P: FnMut(&T) -> bool,` | [src]

- `impl<'a, T> DoubleEndedIterator for Chunks<'a, T>` | [src]

- `impl<A, B> DoubleEndedIterator for Zip<A, B> where A: DoubleEndedIterator + ExactSizeIterator, B: DoubleEndedIterator + ExactSizeIterator,` | [src]

- `impl<B, I, F> DoubleEndedIterator for FilterMap<I, F> where F: FnMut(<I as Iterator>::Item) -> Option<B>, I: DoubleEndedIterator,` | [src]

- `impl<I, P> DoubleEndedIterator for Filter<I, P> where I: DoubleEndedIterator, P: FnMut(&<I as Iterator>::Item) -> bool,` | [src]

- `impl<A> DoubleEndedIterator for RangeInclusive<A> where A: Step,` | [src]

- `impl<'a, T> DoubleEndedIterator for std::slice::IterMut<'a, T>` | [src]

- `impl<A> DoubleEndedIterator for std::option::IntoIter<A>` | [src]

- `impl<'a, T> DoubleEndedIterator for std::result::IterMut<'a, T>` | [src]

- `impl<I, U> DoubleEndedIterator for Flatten<I> where I: DoubleEndedIterator, U: DoubleEndedIterator, <I as Iterator>::Item: IntoIterator, <<I as Iterator>::Item as IntoIterator>::IntoIter == U, <<I as Iterator>::Item as IntoIterator>::Item == <U as Iterator>::Item,` | [src]

- `impl<I> DoubleEndedIterator for Skip<I> where I: DoubleEndedIterator + ExactSizeIterator,` | [src]

- `impl<'a> DoubleEndedIterator for SplitWhitespace<'a>` | [src]

- `impl<'a> DoubleEndedIterator for LinesAny<'a>` | [src]

- `impl<'a, T, P> DoubleEndedIterator for std::slice::RSplit<'a, T, P> where P: FnMut(&T) -> bool,` | [src]

- `impl<'a, T> DoubleEndedIterator for ExactChunksMut<'a, T>` | [src]

- `impl<T> DoubleEndedIterator for Empty<T>` | [src]

- `impl<'a, P> DoubleEndedIterator for RMatchIndices<'a, P> where P: Pattern<'a>, <P as Pattern<'a>>::Searcher: DoubleEndedSearcher<'a>,` | [src]

- `impl<'a, K, V> DoubleEndedIterator for std::collections::btree_map::Iter<'a, K, V> where K: 'a, V: 'a,` | [src]

- `impl<I> DoubleEndedIterator for Box<I> where I: DoubleEndedIterator + ?Sized,` | [src]

- `impl<'a, T> DoubleEndedIterator for std::collections::binary_heap::Iter<'a, T>` | [src]

- `impl<'a, K, V> DoubleEndedIterator for std::collections::btree_map::IterMut<'a, K, V> where K: 'a, V: 'a,` | [src]

- `impl<'a, T> DoubleEndedIterator for std::collections::btree_set::Range<'a, T>` | [src]

- `impl<'a, I> DoubleEndedIterator for Splice<'a, I> where I: Iterator,` | [src]

- `impl<'a, K, V> DoubleEndedIterator for Keys<'a, K, V>` | [src]

- `impl<T> DoubleEndedIterator for std::vec::IntoIter<T>` | [src]

- `impl<'a, T> DoubleEndedIterator for std::collections::binary_heap::Drain<'a, T> where T: 'a,` | [src]

- `impl<'a, T> DoubleEndedIterator for std::collections::vec_deque::Drain<'a, T> where T: 'a,` | [src]

- `impl<'a, K, V> DoubleEndedIterator for std::collections::btree_map::Range<'a, K, V>` | [src]

- `impl<T> DoubleEndedIterator for std::collections::linked_list::IntoIter<T>` | [src]

- `impl<T> DoubleEndedIterator for std::collections::binary_heap::IntoIter<T>` | [src]

- `impl<'a, T> DoubleEndedIterator for std::collections::linked_list::IterMut<'a, T>` | [src]

- `impl<'a> DoubleEndedIterator for std::string::Drain<'a>` | [src]

- `impl<'a, T> DoubleEndedIterator for std::collections::vec_deque::Iter<'a, T>` | [src]

- `impl<K, V> DoubleEndedIterator for std::collections::btree_map::IntoIter<K, V>` | [src]

- `impl<'a, K, V> DoubleEndedIterator for Values<'a, K, V>` | [src]

- `impl<T> DoubleEndedIterator for std::collections::vec_deque::IntoIter<T>` | [src]

- `impl<'a, T> DoubleEndedIterator for std::collections::vec_deque::IterMut<'a, T>` | [src]

- `impl<'a, T> DoubleEndedIterator for std::collections::linked_list::Iter<'a, T>` | [src]

- `impl<'a, T> DoubleEndedIterator for std::vec::Drain<'a, T>` | [src]

- `impl<'a, K, V> DoubleEndedIterator for RangeMut<'a, K, V>` | [src]

- `impl<'a, T> DoubleEndedIterator for std::collections::btree_set::Iter<'a, T>` | [src]

- `impl<T> DoubleEndedIterator for std::collections::btree_set::IntoIter<T>` | [src]

- `impl<'a, K, V> DoubleEndedIterator for ValuesMut<'a, K, V>` | [src]

- `impl DoubleEndedIterator for Args` | [src]

- `impl DoubleEndedIterator for ArgsOs` | [src]

- `impl<'a> DoubleEndedIterator for std::path::Iter<'a>` | [src]

- `impl<'a> DoubleEndedIterator for Components<'a>` | [src]

# Help

## Keyboard Shortcuts

`?`
  Show this help dialog
`S`
  Focus the search field
`↑`
  Move up in search results
`↓`
  Move down in search results
`↹`
  Switch tab
`⏎`
  Go to active search result
`+`
  Expand all sections
`-`
  Collapse all sections

## Search Tricks

Prefix searches with a type followed by a colon (e.g. `fn:`) to restrict the search to a given type.

Accepted types are: `fn`, `mod`, `struct`, `enum`, `trait`, `type`, `macro`, and `const`.

Search functions by type signature (e.g. `vec -> usize` or `* -> vec`)

Search multiple things at once by splitting your query with comma (e.g. `str,u8` or `String,struct:Vec,test`)