Trait redox::iter::Iterator [−] [src]

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

    fn size_hint(&self) -> (usize, Option<usize>) { ... }
    fn count(self) -> usize { ... }
    fn last(self) -> Option<Self::Item> { ... }
    fn nth(&mut self, n: usize) -> Option<Self::Item> { ... }
    fn chain<U>(self, other: U) -> Chain<Self, U::IntoIter> where U: IntoIterator<Item=Self::Item> { ... }
    fn zip<U>(self, other: U) -> Zip<Self, U::IntoIter> where U: IntoIterator { ... }
    fn map<B, F>(self, f: F) -> Map<Self, F> where F: FnMut(Self::Item) -> B { ... }
    fn filter<P>(self, predicate: P) -> Filter<Self, P> where P: FnMut(&Self::Item) -> bool { ... }
    fn filter_map<B, F>(self, f: F) -> FilterMap<Self, F> where F: FnMut(Self::Item) -> Option<B> { ... }
    fn enumerate(self) -> Enumerate<Self> { ... }
    fn peekable(self) -> Peekable<Self> { ... }
    fn skip_while<P>(self, predicate: P) -> SkipWhile<Self, P> where P: FnMut(&Self::Item) -> bool { ... }
    fn take_while<P>(self, predicate: P) -> TakeWhile<Self, P> where P: FnMut(&Self::Item) -> bool { ... }
    fn skip(self, n: usize) -> Skip<Self> { ... }
    fn take(self, n: usize) -> Take<Self> { ... }
    fn scan<St, B, F>(self, initial_state: St, f: F) -> Scan<Self, St, F> where F: FnMut(&mut St, Self::Item) -> Option<B> { ... }
    fn flat_map<U, F>(self, f: F) -> FlatMap<Self, U, F> where F: FnMut(Self::Item) -> U, U: IntoIterator { ... }
    fn fuse(self) -> Fuse<Self> { ... }
    fn inspect<F>(self, f: F) -> Inspect<Self, F> where F: FnMut(&Self::Item) -> () { ... }
    fn by_ref(&mut self) -> &mut Self { ... }
    fn collect<B>(self) -> B where B: FromIterator<Self::Item> { ... }
    fn partition<B, F>(self, f: F) -> (B, B) where B: Default + Extend<Self::Item>, F: FnMut(&Self::Item) -> bool { ... }
    fn fold<B, F>(self, init: B, f: F) -> B where F: FnMut(B, Self::Item) -> B { ... }
    fn all<F>(&mut self, f: F) -> bool where F: FnMut(Self::Item) -> bool { ... }
    fn any<F>(&mut self, f: F) -> bool where F: FnMut(Self::Item) -> bool { ... }
    fn find<P>(&mut self, predicate: P) -> Option<Self::Item> where P: FnMut(&Self::Item) -> bool { ... }
    fn position<P>(&mut self, predicate: P) -> Option<usize> where P: FnMut(Self::Item) -> bool { ... }
    fn rposition<P>(&mut self, predicate: P) -> Option<usize> where Self: ExactSizeIterator + DoubleEndedIterator, P: FnMut(Self::Item) -> bool { ... }
    fn max(self) -> Option<Self::Item> where Self::Item: Ord { ... }
    fn min(self) -> Option<Self::Item> where Self::Item: Ord { ... }
    fn max_by<B, F>(self, f: F) -> Option<Self::Item> where B: Ord, F: FnMut(&Self::Item) -> B { ... }
    fn min_by<B, F>(self, f: F) -> Option<Self::Item> where F: FnMut(&Self::Item) -> B, B: Ord { ... }
    fn rev(self) -> Rev<Self> where Self: DoubleEndedIterator { ... }
    fn unzip<A, B, FromA, FromB>(self) -> (FromA, FromB) where FromA: Default + Extend<A>, Self: Iterator<Item=(A, B)>, FromB: Default + Extend<B> { ... }
    fn cloned<'a, T>(self) -> Cloned<Self> where T: 'a + Clone, Self: Iterator<Item=&'a T> { ... }
    fn cycle(self) -> Cycle<Self> where Self: Clone { ... }
    fn sum<S = Self::Item>(self) -> S where S: Add<Self::Item, Output=S> + Zero { ... }
    fn product<P = Self::Item>(self) -> P where P: Mul<Self::Item, Output=P> + One { ... }
    fn cmp<I>(self, other: I) -> Ordering where I: IntoIterator<Item=Self::Item>, Self::Item: Ord { ... }
    fn partial_cmp<I>(self, other: I) -> Option<Ordering> where I: IntoIterator, Self::Item: PartialOrd<I::Item> { ... }
    fn eq<I>(self, other: I) -> bool where I: IntoIterator, Self::Item: PartialEq<I::Item> { ... }
    fn ne<I>(self, other: I) -> bool where I: IntoIterator, Self::Item: PartialEq<I::Item> { ... }
    fn lt<I>(self, other: I) -> bool where I: IntoIterator, Self::Item: PartialOrd<I::Item> { ... }
    fn le<I>(self, other: I) -> bool where I: IntoIterator, Self::Item: PartialOrd<I::Item> { ... }
    fn gt<I>(self, other: I) -> bool where I: IntoIterator, Self::Item: PartialOrd<I::Item> { ... }
    fn ge<I>(self, other: I) -> bool where I: IntoIterator, Self::Item: PartialOrd<I::Item> { ... }
}

An interface for dealing with "external iterators". These types of iterators can be resumed at any time as all state is stored internally as opposed to being located on the call stack.

The Iterator protocol states that an iterator yields a (potentially-empty, potentially-infinite) sequence of values, and returns None to signal that it's finished. The Iterator protocol does not define behavior after None is returned. A concrete Iterator implementation may choose to behave however it wishes, either by returning None infinitely, or by doing something else.

Associated Types

type Item

The type of the elements being iterated

Required Methods

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

Advances the iterator and returns the next value. Returns None when the end is reached.

Provided Methods

fn size_hint(&self) -> (usize, Option<usize>)

Returns a lower and upper bound on the remaining length of the iterator.

An upper bound of None means either there is no known upper bound, or the upper bound does not fit within a usize.

Examples

let it = (0..10).filter(|x| x % 2 == 0).chain(15..20);
assert_eq!((5, Some(15)), it.size_hint());

fn count(self) -> usize

Counts the number of elements in this iterator.

Overflow Behavior

The method does no guarding against overflows, so counting elements of an iterator with more than usize::MAX elements either produces the wrong result or panics. If debug assertions are enabled, a panic is guaranteed.

Panics

This functions might panic if the iterator has more than usize::MAX elements.

Examples

let a = [1, 2, 3, 4, 5];
assert_eq!(a.iter().count(), 5);

fn last(self) -> Option<Self::Item>

Loops through the entire iterator, returning the last element.

Examples

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

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

Skips the n first elements of the iterator and returns the next one.

Examples

let a = [1, 2, 3, 4, 5];
let mut it = a.iter();
assert_eq!(it.nth(2), Some(&3));
assert_eq!(it.nth(2), None);

fn chain<U>(self, other: U) -> Chain<Self, U::IntoIter> where U: IntoIterator<Item=Self::Item>

Chain this iterator with another, returning a new iterator that will finish iterating over the current iterator, and then iterate over the other specified iterator.

Examples

let a = [0];
let b = [1];
let mut it = a.iter().chain(&b);
assert_eq!(it.next(), Some(&0));
assert_eq!(it.next(), Some(&1));
assert!(it.next().is_none());

fn zip<U>(self, other: U) -> Zip<Self, U::IntoIter> where U: IntoIterator

Creates an iterator that iterates over both this and the specified iterators simultaneously, yielding the two elements as pairs. When either iterator returns None, all further invocations of next() will return None.

Examples

let a = [0];
let b = [1];
let mut it = a.iter().zip(&b);
assert_eq!(it.next(), Some((&0, &1)));
assert!(it.next().is_none());

zip can provide similar functionality to enumerate:

for pair in "foo".chars().enumerate() {
    println!("{:?}", pair);
}

for pair in (0..).zip("foo".chars()) {
    println!("{:?}", pair);
}

both produce the same output.

fn map<B, F>(self, f: F) -> Map<Self, F> where F: FnMut(Self::Item) -> B

Creates a new iterator that will apply the specified function to each element returned by the first, yielding the mapped element instead.

Examples

let a = [1, 2];
let mut it = a.iter().map(|&x| 2 * x);
assert_eq!(it.next(), Some(2));
assert_eq!(it.next(), Some(4));
assert!(it.next().is_none());

fn filter<P>(self, predicate: P) -> Filter<Self, P> where P: FnMut(&Self::Item) -> bool

Creates an iterator that applies the predicate to each element returned by this iterator. The only elements that will be yielded are those that make the predicate evaluate to true.

Examples

let a = [1, 2];
let mut it = a.iter().filter(|&x| *x > 1);
assert_eq!(it.next(), Some(&2));
assert!(it.next().is_none());

fn filter_map<B, F>(self, f: F) -> FilterMap<Self, F> where F: FnMut(Self::Item) -> Option<B>

Creates an iterator that both filters and maps elements. If the specified function returns None, the element is skipped. Otherwise the option is unwrapped and the new value is yielded.

Examples

let a = [1, 2];
let mut it = a.iter().filter_map(|&x| if x > 1 {Some(2 * x)} else {None});
assert_eq!(it.next(), Some(4));
assert!(it.next().is_none());

fn enumerate(self) -> Enumerate<Self>

Creates an iterator that yields pairs (i, val) where i is the current index of iteration and val is the value returned by the iterator.

enumerate keeps its count as a usize. If you want to count by a different sized integer, the zip function provides similar functionality.

Overflow Behavior

The method does no guarding against overflows, so enumerating more than usize::MAX elements either produces the wrong result or panics. If debug assertions are enabled, a panic is guaranteed.

Panics

The returned iterator might panic if the to-be-returned index would overflow a usize.

Examples

let a = [100, 200];
let mut it = a.iter().enumerate();
assert_eq!(it.next(), Some((0, &100)));
assert_eq!(it.next(), Some((1, &200)));
assert!(it.next().is_none());

fn peekable(self) -> Peekable<Self>

Creates an iterator that has a .peek() method that returns an optional reference to the next element.

Examples

let xs = [100, 200, 300];
let mut it = xs.iter().cloned().peekable();
assert_eq!(*it.peek().unwrap(), 100);
assert_eq!(it.next().unwrap(), 100);
assert_eq!(it.next().unwrap(), 200);
assert_eq!(*it.peek().unwrap(), 300);
assert_eq!(*it.peek().unwrap(), 300);
assert_eq!(it.next().unwrap(), 300);
assert!(it.peek().is_none());
assert!(it.next().is_none());

fn skip_while<P>(self, predicate: P) -> SkipWhile<Self, P> where P: FnMut(&Self::Item) -> bool

Creates an iterator that invokes the predicate on elements until it returns false. Once the predicate returns false, that element and all further elements are yielded.

Examples

let a = [1, 2, 3, 4, 5];
let mut it = a.iter().skip_while(|&a| *a < 3);
assert_eq!(it.next(), Some(&3));
assert_eq!(it.next(), Some(&4));
assert_eq!(it.next(), Some(&5));
assert!(it.next().is_none());

fn take_while<P>(self, predicate: P) -> TakeWhile<Self, P> where P: FnMut(&Self::Item) -> bool

Creates an iterator that yields elements so long as the predicate returns true. After the predicate returns false for the first time, no further elements will be yielded.

Examples

let a = [1, 2, 3, 4, 5];
let mut it = a.iter().take_while(|&a| *a < 3);
assert_eq!(it.next(), Some(&1));
assert_eq!(it.next(), Some(&2));
assert!(it.next().is_none());

fn skip(self, n: usize) -> Skip<Self>

Creates an iterator that skips the first n elements of this iterator, and then yields all further items.

Examples

let a = [1, 2, 3, 4, 5];
let mut it = a.iter().skip(3);
assert_eq!(it.next(), Some(&4));
assert_eq!(it.next(), Some(&5));
assert!(it.next().is_none());

fn take(self, n: usize) -> Take<Self>

Creates an iterator that yields the first n elements of this iterator.

Examples

let a = [1, 2, 3, 4, 5];
let mut it = a.iter().take(3);
assert_eq!(it.next(), Some(&1));
assert_eq!(it.next(), Some(&2));
assert_eq!(it.next(), Some(&3));
assert!(it.next().is_none());

fn scan<St, B, F>(self, initial_state: St, f: F) -> Scan<Self, St, F> where F: FnMut(&mut St, Self::Item) -> Option<B>

Creates a new iterator that behaves in a similar fashion to fold. There is a state which is passed between each iteration and can be mutated as necessary. The yielded values from the closure are yielded from the Scan instance when not None.

Examples

let a = [1, 2, 3, 4, 5];
let mut it = a.iter().scan(1, |fac, &x| {
  *fac = *fac * x;
  Some(*fac)
});
assert_eq!(it.next(), Some(1));
assert_eq!(it.next(), Some(2));
assert_eq!(it.next(), Some(6));
assert_eq!(it.next(), Some(24));
assert_eq!(it.next(), Some(120));
assert!(it.next().is_none());

fn flat_map<U, F>(self, f: F) -> FlatMap<Self, U, F> where F: FnMut(Self::Item) -> U, U: IntoIterator

Takes a function that maps each element to a new iterator and yields all the elements of the produced iterators.

This is useful for unraveling nested structures.

Examples

let words = ["alpha", "beta", "gamma"];
let merged: String = words.iter()
                          .flat_map(|s| s.chars())
                          .collect();
assert_eq!(merged, "alphabetagamma");

fn fuse(self) -> Fuse<Self>

Creates an iterator that yields None forever after the underlying iterator yields None. Random-access iterator behavior is not affected, only single and double-ended iterator behavior.

Examples

fn process<U: Iterator<Item=i32>>(it: U) -> i32 {
    let mut it = it.fuse();
    let mut sum = 0;
    for x in it.by_ref() {
        if x > 5 {
            break;
        }
        sum += x;
    }
    // did we exhaust the iterator?
    if it.next().is_none() {
        sum += 1000;
    }
    sum
}
let x = vec![1, 2, 3, 7, 8, 9];
assert_eq!(process(x.into_iter()), 6);
let x = vec![1, 2, 3];
assert_eq!(process(x.into_iter()), 1006);

fn inspect<F>(self, f: F) -> Inspect<Self, F> where F: FnMut(&Self::Item) -> ()

Creates an iterator that calls a function with a reference to each element before yielding it. This is often useful for debugging an iterator pipeline.

Examples

let a = [1, 4, 2, 3, 8, 9, 6];
let sum: i32 = a.iter()
                .map(|x| *x)
                .inspect(|&x| println!("filtering {}", x))
                .filter(|&x| x % 2 == 0)
                .inspect(|&x| println!("{} made it through", x))
                .fold(0, |sum, i| sum + i);
println!("{}", sum);

fn by_ref(&mut self) -> &mut Self

Creates a wrapper around a mutable reference to the iterator.

This is useful to allow applying iterator adaptors while still retaining ownership of the original iterator value.

Examples

let mut it = 0..10;
// sum the first five values
let partial_sum = it.by_ref().take(5).fold(0, |a, b| a + b);
assert_eq!(partial_sum, 10);
assert_eq!(it.next(), Some(5));

fn collect<B>(self) -> B where B: FromIterator<Self::Item>

Loops through the entire iterator, collecting all of the elements into a container implementing FromIterator.

Examples

let expected = [1, 2, 3, 4, 5];
let actual: Vec<_> = expected.iter().cloned().collect();
assert_eq!(actual, expected);

fn partition<B, F>(self, f: F) -> (B, B) where B: Default + Extend<Self::Item>, F: FnMut(&Self::Item) -> bool

Loops through the entire iterator, collecting all of the elements into one of two containers, depending on a predicate. The elements of the first container satisfy the predicate, while the elements of the second do not.

let vec = vec![1, 2, 3, 4];
let (even, odd): (Vec<_>, Vec<_>) = vec.into_iter().partition(|&n| n % 2 == 0);
assert_eq!(even, [2, 4]);
assert_eq!(odd, [1, 3]);

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

Performs a fold operation over the entire iterator, returning the eventual state at the end of the iteration.

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

Examples

let a = [1, 2, 3, 4, 5];
assert_eq!(a.iter().fold(0, |acc, &item| acc + item), 15);

fn all<F>(&mut self, f: F) -> bool where F: FnMut(Self::Item) -> bool

Tests whether the predicate holds true for all elements in the iterator.

Does not consume the iterator past the first non-matching element.

Examples

let a = [1, 2, 3, 4, 5];
assert!(a.iter().all(|x| *x > 0));
assert!(!a.iter().all(|x| *x > 2));

fn any<F>(&mut self, f: F) -> bool where F: FnMut(Self::Item) -> bool

Tests whether any element of an iterator satisfies the specified predicate.

Does not consume the iterator past the first found element.

Examples

let a = [1, 2, 3, 4, 5];
let mut it = a.iter();
assert!(it.any(|x| *x == 3));
assert_eq!(it.collect::<Vec<_>>(), [&4, &5]);

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

Returns the first element satisfying the specified predicate.

Does not consume the iterator past the first found element.

Examples

let a = [1, 2, 3, 4, 5];
let mut it = a.iter();
assert_eq!(it.find(|&x| *x == 3), Some(&3));
assert_eq!(it.collect::<Vec<_>>(), [&4, &5]);

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

Returns the index of the first element satisfying the specified predicate

Does not consume the iterator past the first found element.

Overflow Behavior

The method does no guarding against overflows, so if there are more than usize::MAX non-matching elements, it either produces the wrong result or panics. If debug assertions are enabled, a panic is guaranteed.

Panics

This functions might panic if the iterator has more than usize::MAX non-matching elements.

Examples

let a = [1, 2, 3, 4, 5];
let mut it = a.iter();
assert_eq!(it.position(|x| *x == 3), Some(2));
assert_eq!(it.collect::<Vec<_>>(), [&4, &5]);

fn rposition<P>(&mut self, predicate: P) -> Option<usize> where Self: ExactSizeIterator + DoubleEndedIterator, P: FnMut(Self::Item) -> bool

Returns the index of the last element satisfying the specified predicate

If no element matches, None is returned.

Does not consume the iterator before the first found element.

Examples

let a = [1, 2, 2, 4, 5];
let mut it = a.iter();
assert_eq!(it.rposition(|x| *x == 2), Some(2));
assert_eq!(it.collect::<Vec<_>>(), [&1, &2]);

fn max(self) -> Option<Self::Item> where Self::Item: Ord

Consumes the entire iterator to return the maximum element.

Returns the rightmost element if the comparison determines two elements to be equally maximum.

Examples

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

fn min(self) -> Option<Self::Item> where Self::Item: Ord

Consumes the entire iterator to return the minimum element.

Returns the leftmost element if the comparison determines two elements to be equally minimum.

Examples

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

fn max_by<B, F>(self, f: F) -> Option<Self::Item> where B: Ord, F: FnMut(&Self::Item) -> B

Unstable (iter_cmp)

: may want to produce an Ordering directly; see #15311

Returns the element that gives the maximum value from the specified function.

Returns the rightmost element if the comparison determines two elements to be equally maximum.

Examples

#![feature(iter_cmp)]

let a = [-3_i32, 0, 1, 5, -10];
assert_eq!(*a.iter().max_by(|x| x.abs()).unwrap(), -10);

fn min_by<B, F>(self, f: F) -> Option<Self::Item> where F: FnMut(&Self::Item) -> B, B: Ord

Unstable (iter_cmp)

: may want to produce an Ordering directly; see #15311

Returns the element that gives the minimum value from the specified function.

Returns the leftmost element if the comparison determines two elements to be equally minimum.

Examples

#![feature(iter_cmp)]

let a = [-3_i32, 0, 1, 5, -10];
assert_eq!(*a.iter().min_by(|x| x.abs()).unwrap(), 0);

fn rev(self) -> Rev<Self> where Self: DoubleEndedIterator

Change the direction of the iterator

The flipped iterator swaps the ends on an iterator that can already be iterated from the front and from the back.

If the iterator also implements RandomAccessIterator, the flipped iterator is also random access, with the indices starting at the back of the original iterator.

Note: Random access with flipped indices still only applies to the first std::usize::MAX elements of the original iterator.

fn unzip<A, B, FromA, FromB>(self) -> (FromA, FromB) where FromA: Default + Extend<A>, Self: Iterator<Item=(A, B)>, FromB: Default + Extend<B>

Converts an iterator of pairs into a pair of containers.

Loops through the entire iterator, collecting the first component of each item into one new container, and the second component into another.

Examples

let a = [(1, 2), (3, 4)];
let (left, right): (Vec<_>, Vec<_>) = a.iter().cloned().unzip();
assert_eq!(left, [1, 3]);
assert_eq!(right, [2, 4]);

fn cloned<'a, T>(self) -> Cloned<Self> where T: 'a + Clone, Self: Iterator<Item=&'a T>

Creates an iterator that clones the elements it yields.

This is useful for converting an Iterator<&T> to anIterator<T>, so it's a more convenient form of map(|&x| x).

Examples

let a = [0, 1, 2];
let v_cloned: Vec<_> = a.iter().cloned().collect();
let v_map: Vec<_> = a.iter().map(|&x| x).collect();
assert_eq!(v_cloned, v_map);

fn cycle(self) -> Cycle<Self> where Self: Clone

Repeats an iterator endlessly

Examples

let a = [1, 2];
let mut it = a.iter().cycle();
assert_eq!(it.next(), Some(&1));
assert_eq!(it.next(), Some(&2));
assert_eq!(it.next(), Some(&1));

fn sum<S = Self::Item>(self) -> S where S: Add<Self::Item, Output=S> + Zero

Unstable (iter_arith)

: bounds recently changed

Iterates over the entire iterator, summing up all the elements

Examples

#![feature(iter_arith)]

let a = [1, 2, 3, 4, 5];
let it = a.iter();
assert_eq!(it.sum::<i32>(), 15);

fn product<P = Self::Item>(self) -> P where P: Mul<Self::Item, Output=P> + One

Unstable (iter_arith)

: bounds recently changed

Iterates over the entire iterator, multiplying all the elements

Examples

#![feature(iter_arith)]

fn factorial(n: u32) -> u32 {
    (1..).take_while(|&i| i <= n).product()
}
assert_eq!(factorial(0), 1);
assert_eq!(factorial(1), 1);
assert_eq!(factorial(5), 120);

fn cmp<I>(self, other: I) -> Ordering where I: IntoIterator<Item=Self::Item>, Self::Item: Ord

Lexicographically compares the elements of this Iterator with those of another.

fn partial_cmp<I>(self, other: I) -> Option<Ordering> where I: IntoIterator, Self::Item: PartialOrd<I::Item>

Lexicographically compares the elements of this Iterator with those of another.

fn eq<I>(self, other: I) -> bool where I: IntoIterator, Self::Item: PartialEq<I::Item>

Determines if the elements of this Iterator are equal to those of another.

fn ne<I>(self, other: I) -> bool where I: IntoIterator, Self::Item: PartialEq<I::Item>

Determines if the elements of this Iterator are unequal to those of another.

fn lt<I>(self, other: I) -> bool where I: IntoIterator, Self::Item: PartialOrd<I::Item>

Determines if the elements of this Iterator are lexicographically less than those of another.

fn le<I>(self, other: I) -> bool where I: IntoIterator, Self::Item: PartialOrd<I::Item>

Determines if the elements of this Iterator are lexicographically less or equal to those of another.

fn gt<I>(self, other: I) -> bool where I: IntoIterator, Self::Item: PartialOrd<I::Item>

Determines if the elements of this Iterator are lexicographically greater than those of another.

fn ge<I>(self, other: I) -> bool where I: IntoIterator, Self::Item: PartialOrd<I::Item>

Determines if the elements of this Iterator are lexicographically greater than or equal to those of another.

Implementors