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 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 interchangable 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 rfind<P>(&mut self, predicate: P) -> Option<Self::Item> where
P: FnMut(&Self::Item) -> bool,`

🔬 This is a nightly-only experimental API. (`iter_rfind` #39480)

Searches for an element of an iterator from the right 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:

    #![feature(iter_rfind)]

    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`:

    #![feature(iter_rfind)]

    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> DoubleEndedIterator for SplitWhitespace<'a>`
- `impl<'a, K, V> DoubleEndedIterator for std::collections::btree_map::Range<'a, K, V>`
- `impl<'a, T> DoubleEndedIterator for std::collections::linked_list::Iter<'a, T>`
- `impl<'a, T> DoubleEndedIterator for std::collections::vec_deque::IterMut<'a, T>`
- `impl<'a, T> DoubleEndedIterator for std::collections::vec_deque::Iter<'a, T>`
- `impl<'a, T> DoubleEndedIterator for std::collections::btree_set::Range<'a, T>`
- `impl<T> DoubleEndedIterator for std::collections::linked_list::IntoIter<T>`
- `impl<'a, T> DoubleEndedIterator for std::collections::binary_heap::Drain<'a, T> where
  T: 'a,`
- `impl<'a> DoubleEndedIterator for std::string::Drain<'a>`
- `impl<'a, K, V> DoubleEndedIterator for Values<'a, K, V>`
- `impl<T> DoubleEndedIterator for std::collections::binary_heap::IntoIter<T>`
- `impl<'a, K, V> DoubleEndedIterator for std::collections::btree_map::Iter<'a, K, V> where
  K: 'a,
  V: 'a,`
- `impl<K, V> DoubleEndedIterator for std::collections::btree_map::IntoIter<K, V>`
- `impl<'a, K, V> DoubleEndedIterator for Keys<'a, K, V>`
- `impl<'a, T> DoubleEndedIterator for std::collections::binary_heap::Iter<'a, T>`
- `impl<'a, T> DoubleEndedIterator for std::collections::linked_list::IterMut<'a, T>`
- `impl<I> DoubleEndedIterator for Box<I> where
  I: DoubleEndedIterator + ?Sized,`
- `impl<'a, K, V> DoubleEndedIterator for std::collections::btree_map::IterMut<'a, K, V> where
  K: 'a,
  V: 'a,`
- `impl<'a, 'b> DoubleEndedIterator for std::string::Splice<'a, 'b>`
- `impl<'a, T> DoubleEndedIterator for std::vec::Drain<'a, T>`
- `impl<T> DoubleEndedIterator for std::collections::vec_deque::IntoIter<T>`
- `impl<T> DoubleEndedIterator for std::vec::IntoIter<T>`
- `impl<'a, K, V> DoubleEndedIterator for RangeMut<'a, K, V>`
- `impl<'a, T> DoubleEndedIterator for std::collections::vec_deque::Drain<'a, T> where
  T: 'a,`
- `impl<'a, T> DoubleEndedIterator for std::collections::btree_set::Iter<'a, T>`
- `impl<T> DoubleEndedIterator for std::collections::btree_set::IntoIter<T>`
- `impl<'a, I> DoubleEndedIterator for std::vec::Splice<'a, I> where
  I: Iterator,`
- `impl<'a, K, V> DoubleEndedIterator for ValuesMut<'a, K, V>`
- `impl<'a, I> DoubleEndedIterator for &'a mut I where
  I: DoubleEndedIterator + ?Sized,`
- `impl<A> DoubleEndedIterator for std::option::IntoIter<A>`
- `impl<'a, T> DoubleEndedIterator for std::slice::IterMut<'a, T>`
- `impl<'a> DoubleEndedIterator for LinesAny<'a>`
- `impl<'a, T> DoubleEndedIterator for ChunksMut<'a, T>`
- `impl<'a> DoubleEndedIterator for Chars<'a>`
- `impl<T> DoubleEndedIterator for Once<T>`
- `impl<A, B> DoubleEndedIterator for Chain<A, B> where
  A: DoubleEndedIterator,
  B: DoubleEndedIterator<Item = <A as Iterator>::Item>,`
- `impl<A> DoubleEndedIterator for std::ops::Range<A> where
  A: Step,`
- `impl<'a, T, P> DoubleEndedIterator for RSplitMut<'a, T, P> where
  P: FnMut(&T) -> bool,`
- `impl<T> DoubleEndedIterator for std::result::IntoIter<T>`
- `impl<I> DoubleEndedIterator for Skip<I> where
  I: DoubleEndedIterator + ExactSizeIterator,`
- `impl<'a, I, T> DoubleEndedIterator for Cloned<I> where
  I: DoubleEndedIterator<Item = &'a T>,
  T: 'a + Clone,`
- `impl<B, I, F> DoubleEndedIterator for Map<I, F> where
  F: FnMut(<I as Iterator>::Item) -> B,
  I: DoubleEndedIterator,`
- `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,`
- `impl<'a> DoubleEndedIterator for Bytes<'a>`
- `impl<'a> DoubleEndedIterator for CharIndices<'a>`
- `impl<I> DoubleEndedIterator for Enumerate<I> where
  I: ExactSizeIterator + DoubleEndedIterator,`
- `impl<'a, P> DoubleEndedIterator for SplitTerminator<'a, P> where
  P: Pattern<'a>,
  <P as Pattern<'a>>::Searcher: DoubleEndedSearcher<'a>,`
- `impl<'a, T, P> DoubleEndedIterator for std::slice::Split<'a, T, P> where
  P: FnMut(&T) -> bool,`
- `impl<T> DoubleEndedIterator for Empty<T>`
- `impl<A> DoubleEndedIterator for Repeat<A> where
  A: Clone,`
- `impl<'a, P> DoubleEndedIterator for std::str::Split<'a, P> where
  P: Pattern<'a>,
  <P as Pattern<'a>>::Searcher: DoubleEndedSearcher<'a>,`
- `impl<'a, T> DoubleEndedIterator for std::result::IterMut<'a, T>`
- `impl<'a, A> DoubleEndedIterator for std::option::Iter<'a, A>`
- `impl<I> DoubleEndedIterator for Fuse<I> where
  I: DoubleEndedIterator,`
- `impl<A, B> DoubleEndedIterator for Zip<A, B> where
  A: DoubleEndedIterator + ExactSizeIterator,
  B: DoubleEndedIterator + ExactSizeIterator,`
- `impl<'a, P> DoubleEndedIterator for MatchIndices<'a, P> where
  P: Pattern<'a>,
  <P as Pattern<'a>>::Searcher: DoubleEndedSearcher<'a>,`
- `impl<'a, T> DoubleEndedIterator for std::result::Iter<'a, T>`
- `impl<'a, T, P> DoubleEndedIterator for SplitMut<'a, T, P> where
  P: FnMut(&T) -> bool,`
- `impl<A> DoubleEndedIterator for RangeInclusive<A> where
  A: Step,`
- `impl<I, P> DoubleEndedIterator for Filter<I, P> where
  I: DoubleEndedIterator,
  P: FnMut(&<I as Iterator>::Item) -> bool,`
- `impl<'a, T, P> DoubleEndedIterator for std::slice::RSplit<'a, T, P> where
  P: FnMut(&T) -> bool,`
- `impl<I> DoubleEndedIterator for Fuse<I> where
  I: DoubleEndedIterator + FusedIterator,`
- `impl<'a, T> DoubleEndedIterator for std::slice::Iter<'a, T>`
- `impl<'a> DoubleEndedIterator for Lines<'a>`
- `impl<'a, A> DoubleEndedIterator for std::option::IterMut<'a, A>`
- `impl<'a, P> DoubleEndedIterator for Matches<'a, P> where
  P: Pattern<'a>,
  <P as Pattern<'a>>::Searcher: DoubleEndedSearcher<'a>,`
- `impl<'a, P> DoubleEndedIterator for RMatchIndices<'a, P> where
  P: Pattern<'a>,
  <P as Pattern<'a>>::Searcher: DoubleEndedSearcher<'a>,`
- `impl<I, F> DoubleEndedIterator for Inspect<I, F> where
  F: FnMut(&<I as Iterator>::Item) -> (),
  I: DoubleEndedIterator,`
- `impl<'a, T> DoubleEndedIterator for Chunks<'a, T>`
- `impl<'a, P> DoubleEndedIterator for std::str::RSplit<'a, P> where
  P: Pattern<'a>,
  <P as Pattern<'a>>::Searcher: DoubleEndedSearcher<'a>,`
- `impl<B, I, F> DoubleEndedIterator for FilterMap<I, F> where
  F: FnMut(<I as Iterator>::Item) -> Option<B>,
  I: DoubleEndedIterator,`
- `impl<I> DoubleEndedIterator for Rev<I> where
  I: DoubleEndedIterator,`
- `impl<'a, T> DoubleEndedIterator for Windows<'a, T>`
- `impl<'a, P> DoubleEndedIterator for RSplitTerminator<'a, P> where
  P: Pattern<'a>,
  <P as Pattern<'a>>::Searcher: DoubleEndedSearcher<'a>,`
- `impl<'a, P> DoubleEndedIterator for RMatches<'a, P> where
  P: Pattern<'a>,
  <P as Pattern<'a>>::Searcher: DoubleEndedSearcher<'a>,`
- `impl DoubleEndedIterator for EscapeDefault`
- `impl DoubleEndedIterator for Args`
- `impl DoubleEndedIterator for ArgsOs`
- `impl<'a> DoubleEndedIterator for std::path::Iter<'a>`
- `impl<'a> DoubleEndedIterator for Components<'a>`

# Help

## Keyboard Shortcuts

?
  Show this help dialog
S
  Focus the search field
⇤
  Move up in search results
⇥
  Move down in search results
⏎
  Go to active search result
+
  Collapse/expand 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`)