Trait sp_std::iter::DoubleEndedIterator1.0.0[][src]

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

    pub fn advance_back_by(&mut self, n: usize) -> Result<(), usize> { ... }
pub fn nth_back(&mut self, n: usize) -> Option<Self::Item> { ... }
pub fn try_rfold<B, F, R>(&mut self, init: B, f: F) -> R
    where
        R: Try<Ok = B>,
        F: FnMut(B, Self::Item) -> R
, { ... }
pub fn rfold<B, F>(self, init: B, f: F) -> B
    where
        F: FnMut(B, Self::Item) -> B
, { ... }
pub 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 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

pub fn next_back(&mut self) -> Option<Self::Item>[src]

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

Remarks

The elements yielded by DoubleEndedIterator's methods may differ from the ones yielded by Iterator's methods:

let vec = vec![(1, 'a'), (1, 'b'), (1, 'c'), (2, 'a'), (2, 'b')];
let uniq_by_fst_comp = || {
    let mut seen = std::collections::HashSet::new();
    vec.iter().copied().filter(move |x| seen.insert(x.0))
};

assert_eq!(uniq_by_fst_comp().last(), Some((2, 'a')));
assert_eq!(uniq_by_fst_comp().next_back(), Some((2, 'b')));

assert_eq!(
    uniq_by_fst_comp().fold(vec![], |mut v, x| {v.push(x); v}),
    vec![(1, 'a'), (2, 'a')]
);
assert_eq!(
    uniq_by_fst_comp().rfold(vec![], |mut v, x| {v.push(x); v}),
    vec![(2, 'b'), (1, 'c')]
);
Loading content...

Provided methods

pub fn advance_back_by(&mut self, n: usize) -> Result<(), usize>[src]

🔬 This is a nightly-only experimental API. (iter_advance_by)

recently added

Advances the iterator from the back by n elements.

advance_back_by is the reverse version of advance_by. This method will eagerly skip n elements starting from the back by calling next_back up to n times until None is encountered.

advance_back_by(n) will return Ok(()) if the iterator successfully advances by n elements, or Err(k) if None is encountered, where k is the number of elements the iterator is advanced by before running out of elements (i.e. the length of the iterator). Note that k is always less than n.

Calling advance_back_by(0) does not consume any elements and always returns Ok(()).

Examples

Basic usage:

#![feature(iter_advance_by)]

let a = [3, 4, 5, 6];
let mut iter = a.iter();

assert_eq!(iter.advance_back_by(2), Ok(()));
assert_eq!(iter.next_back(), Some(&4));
assert_eq!(iter.advance_back_by(0), Ok(()));
assert_eq!(iter.advance_back_by(100), Err(1)); // only `&3` was skipped

pub fn nth_back(&mut self, n: usize) -> Option<Self::Item>1.37.0[src]

Returns the nth element from the end of the iterator.

This is essentially the reversed version of Iterator::nth(). Although like most indexing operations, the count starts from zero, so nth_back(0) returns the first value from 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);

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

This is the reverse version of Iterator::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"));

pub fn rfold<B, F>(self, init: B, f: F) -> B where
    F: FnMut(B, Self::Item) -> B, 
1.27.0[src]

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

This is the reverse version of Iterator::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)))))");

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

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...

Implementations on Foreign Types

impl DoubleEndedIterator for ArgsOs[src]

impl<'a> DoubleEndedIterator for Iter<'a>[src]

impl<'a> DoubleEndedIterator for Components<'a>[src]

impl DoubleEndedIterator for Args[src]

impl DoubleEndedIterator for EscapeDefault[src]

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

impl<'a, A> DoubleEndedIterator for Iter<'a, A>[src]

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

impl<'a, A> DoubleEndedIterator for IterMut<'a, A>[src]

impl<A> DoubleEndedIterator for IntoIter<A>[src]

impl<T, const N: usize> DoubleEndedIterator for IntoIter<T, N>[src]

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

impl<'a, T> DoubleEndedIterator for Iter<'a, T>[src]

impl<'a, T> DoubleEndedIterator for IterMut<'a, T>[src]

impl<'_> DoubleEndedIterator for Drain<'_>[src]

impl<T> DoubleEndedIterator for IntoIter<T>[src]

impl<'a, T> DoubleEndedIterator for Iter<'a, T>[src]

impl<T> DoubleEndedIterator for IntoIter<T>[src]

impl<'_, T> DoubleEndedIterator for Drain<'_, T>[src]

Loading content...

Implementors

impl<'_> DoubleEndedIterator for Bytes<'_>[src]

impl<'_, I, A> DoubleEndedIterator for Splice<'_, I, A> where
    A: Allocator,
    I: Iterator
1.21.0[src]

impl<'_, T> DoubleEndedIterator for sp_std::collections::vec_deque::Drain<'_, T>1.6.0[src]

impl<'_, T, A> DoubleEndedIterator for sp_std::vec::Drain<'_, T, A> where
    A: Allocator
1.6.0[src]

impl<'a> DoubleEndedIterator for CharIndices<'a>[src]

impl<'a> DoubleEndedIterator for Chars<'a>[src]

impl<'a> DoubleEndedIterator for Lines<'a>[src]

impl<'a> DoubleEndedIterator for LinesAny<'a>[src]

impl<'a> DoubleEndedIterator for SplitAsciiWhitespace<'a>1.34.0[src]

impl<'a> DoubleEndedIterator for SplitWhitespace<'a>1.1.0[src]

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

impl<'a, I, T> DoubleEndedIterator for Copied<I> where
    T: 'a + Copy,
    I: DoubleEndedIterator<Item = &'a T>, 
1.36.0[src]

impl<'a, K, V> DoubleEndedIterator for sp_std::collections::btree_map::Iter<'a, K, V> where
    K: 'a,
    V: 'a, 
[src]

impl<'a, K, V> DoubleEndedIterator for sp_std::collections::btree_map::IterMut<'a, K, V> where
    K: 'a,
    V: 'a, 
[src]

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

impl<'a, K, V> DoubleEndedIterator for sp_std::collections::btree_map::Range<'a, K, V>1.17.0[src]

impl<'a, K, V> DoubleEndedIterator for RangeMut<'a, K, V>1.17.0[src]

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

impl<'a, K, V> DoubleEndedIterator for ValuesMut<'a, K, V>1.10.0[src]

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

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

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

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

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

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

impl<'a, P> DoubleEndedIterator for sp_std::str::Split<'a, P> where
    P: Pattern<'a>,
    <P as Pattern<'a>>::Searcher: DoubleEndedSearcher<'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 sp_std::collections::btree_set::Iter<'a, T>[src]

impl<'a, T> DoubleEndedIterator for sp_std::collections::btree_set::Range<'a, T>1.17.0[src]

impl<'a, T> DoubleEndedIterator for sp_std::collections::vec_deque::Iter<'a, T>[src]

impl<'a, T> DoubleEndedIterator for sp_std::collections::vec_deque::IterMut<'a, T>[src]

impl<'a, T> DoubleEndedIterator for sp_std::result::Iter<'a, T>[src]

impl<'a, T> DoubleEndedIterator for sp_std::result::IterMut<'a, T>[src]

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

impl<'a, T> DoubleEndedIterator for ChunksExact<'a, T>1.31.0[src]

impl<'a, T> DoubleEndedIterator for ChunksExactMut<'a, T>1.31.0[src]

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

impl<'a, T> DoubleEndedIterator for sp_std::slice::Iter<'a, T>[src]

impl<'a, T> DoubleEndedIterator for sp_std::slice::IterMut<'a, T>[src]

impl<'a, T> DoubleEndedIterator for RChunks<'a, T>1.31.0[src]

impl<'a, T> DoubleEndedIterator for RChunksExact<'a, T>1.31.0[src]

impl<'a, T> DoubleEndedIterator for RChunksExactMut<'a, T>1.31.0[src]

impl<'a, T> DoubleEndedIterator for RChunksMut<'a, T>1.31.0[src]

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

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

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

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

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

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

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

impl<'a, T, const N: usize> DoubleEndedIterator for ArrayChunks<'a, T, N>[src]

impl<'a, T, const N: usize> DoubleEndedIterator for ArrayChunksMut<'a, T, N>[src]

impl<'a, T, const N: usize> DoubleEndedIterator for ArrayWindows<'a, T, N>[src]

impl<A> DoubleEndedIterator for Repeat<A> where
    A: Clone
[src]

impl<A> DoubleEndedIterator for sp_std::ops::Range<A> where
    A: Step
[src]

impl<A> DoubleEndedIterator for RangeInclusive<A> where
    A: Step
1.26.0[src]

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

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

impl<A, F> DoubleEndedIterator for OnceWith<F> where
    F: FnOnce() -> A, 
1.43.0[src]

impl<B, I, F> DoubleEndedIterator for FilterMap<I, F> where
    F: FnMut(<I as Iterator>::Item) -> Option<B>,
    I: DoubleEndedIterator
[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 Enumerate<I> where
    I: ExactSizeIterator + DoubleEndedIterator
[src]

impl<I> DoubleEndedIterator for Fuse<I> where
    I: DoubleEndedIterator
[src]

impl<I> DoubleEndedIterator for Peekable<I> where
    I: DoubleEndedIterator
1.38.0[src]

impl<I> DoubleEndedIterator for Rev<I> where
    I: DoubleEndedIterator
[src]

impl<I> DoubleEndedIterator for Skip<I> where
    I: DoubleEndedIterator + ExactSizeIterator
1.9.0[src]

impl<I> DoubleEndedIterator for StepBy<I> where
    I: DoubleEndedIterator + ExactSizeIterator
1.38.0[src]

impl<I> DoubleEndedIterator for Take<I> where
    I: DoubleEndedIterator + ExactSizeIterator
1.38.0[src]

impl<I, A> DoubleEndedIterator for Box<I, A> where
    A: Allocator,
    I: DoubleEndedIterator + ?Sized
[src]

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

impl<I, P> DoubleEndedIterator for Filter<I, P> where
    I: DoubleEndedIterator,
    P: FnMut(&<I as Iterator>::Item) -> bool
[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
1.29.0[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<K, V> DoubleEndedIterator for sp_std::collections::btree_map::IntoIter<K, V>[src]

impl<K, V> DoubleEndedIterator for IntoKeys<K, V>[src]

impl<K, V> DoubleEndedIterator for IntoValues<K, V>[src]

impl<T> DoubleEndedIterator for sp_std::collections::btree_set::IntoIter<T>[src]

impl<T> DoubleEndedIterator for sp_std::collections::vec_deque::IntoIter<T>[src]

impl<T> DoubleEndedIterator for Empty<T>1.2.0[src]

impl<T> DoubleEndedIterator for Once<T>1.2.0[src]

impl<T> DoubleEndedIterator for sp_std::result::IntoIter<T>[src]

impl<T, A> DoubleEndedIterator for sp_std::vec::IntoIter<T, A> where
    A: Allocator
[src]

Loading content...