Trait std::iter::DoubleEndedIterator

Overview

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 = [1, 2, 3, 4, 5, 6];

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

Methods

fn next_back(value: any) -> Option

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

Returns None when there are no more elements.

Examples

Basic usage:

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

let 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());
fn nth_back(value: any, value1: u64) -> Option

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 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 rev(value: any) -> Rev

Reverses an iterator's direction.

Usually, iterators iterate from left to right. After using rev(), an iterator will instead iterate from right to left.

This is only possible if the iterator has an end, so rev() only works on double-ended iterators.

Examples

let a = [1, 2, 3];

let iter = a.iter().rev();

assert_eq!(iter.next(), Some(3));
assert_eq!(iter.next(), Some(2));
assert_eq!(iter.next(), Some(1));

assert_eq!(iter.next(), None);