Trait std::iter::IteratorExperimental [-]  [+] [src]

pub trait Iterator<A> {
    fn next(&mut self) -> Option<A>;

    fn size_hint(&self) -> (uint, Option<uint>) { ... }
    fn chain<U: Iterator<A>>(self, other: U) -> Chain<Self, U> { ... }
    fn zip<B, U: Iterator<B>>(self, other: U) -> Zip<Self, U> { ... }
    fn map<B>(self, f: |A| -> B) -> Map<'r, A, B, Self> { ... }
    fn filter(self, predicate: |&A| -> bool) -> Filter<'r, A, Self> { ... }
    fn filter_map<B>(self, f: |A| -> Option<B>) -> FilterMap<'r, A, B, Self> { ... }
    fn enumerate(self) -> Enumerate<Self> { ... }
    fn peekable(self) -> Peekable<A, Self> { ... }
    fn skip_while(self, predicate: |&A| -> bool) -> SkipWhile<'r, A, Self> { ... }
    fn take_while(self, predicate: |&A| -> bool) -> TakeWhile<'r, A, Self> { ... }
    fn skip(self, n: uint) -> Skip<Self> { ... }
    fn take(self, n: uint) -> Take<Self> { ... }
    fn scan<St, B>(self, initial_state: St, f: |&mut St, A| -> Option<B>) -> Scan<'r, A, B, Self, St> { ... }
    fn flat_map<B, U: Iterator<B>>(self, f: |A| -> U) -> FlatMap<'r, A, Self, U> { ... }
    fn fuse(self) -> Fuse<Self> { ... }
    fn inspect(self, f: |&A|) -> Inspect<'r, A, Self> { ... }
    fn by_ref(&'r mut self) -> ByRef<'r, Self> { ... }
    fn collect<B: FromIterator<A>>(&mut self) -> B { ... }
    fn nth(&mut self, n: uint) -> Option<A> { ... }
    fn last(&mut self) -> Option<A> { ... }
    fn fold<B>(&mut self, init: B, f: |B, A| -> B) -> B { ... }
    fn count(&mut self) -> uint { ... }
    fn all(&mut self, f: |A| -> bool) -> bool { ... }
    fn any(&mut self, f: |A| -> bool) -> bool { ... }
    fn find(&mut self, predicate: |&A| -> bool) -> Option<A> { ... }
    fn position(&mut self, predicate: |A| -> bool) -> Option<uint> { ... }
    fn max_by<B: Ord>(&mut self, f: |&A| -> B) -> Option<A> { ... }
    fn min_by<B: Ord>(&mut self, f: |&A| -> B) -> Option<A> { ... }
}

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.

Required Methods

fn next(&mut self) -> Option<A>

Advance the iterator and return the next value. Return None when the end is reached.

Provided Methods

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

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

fn chain<U: Iterator<A>>(self, other: U) -> Chain<Self, U>

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

Example

fn main() { let a = [0i]; let b = [1i]; let mut it = a.iter().chain(b.iter()); assert_eq!(it.next().unwrap(), &0); assert_eq!(it.next().unwrap(), &1); assert!(it.next().is_none()); }
let a = [0i];
let b = [1i];
let mut it = a.iter().chain(b.iter());
assert_eq!(it.next().unwrap(), &0);
assert_eq!(it.next().unwrap(), &1);
assert!(it.next().is_none());

fn zip<B, U: Iterator<B>>(self, other: U) -> Zip<Self, U>

Creates an iterator which 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.

Example

fn main() { let a = [0i]; let b = [1i]; let mut it = a.iter().zip(b.iter()); let (x0, x1) = (0i, 1i); assert_eq!(it.next().unwrap(), (&x0, &x1)); assert!(it.next().is_none()); }
let a = [0i];
let b = [1i];
let mut it = a.iter().zip(b.iter());
let (x0, x1) = (0i, 1i);
assert_eq!(it.next().unwrap(), (&x0, &x1));
assert!(it.next().is_none());

fn map<B>(self, f: |A| -> B) -> Map<'r, A, B, Self>

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

Example

fn main() { let a = [1i, 2]; let mut it = a.iter().map(|&x| 2 * x); assert_eq!(it.next().unwrap(), 2); assert_eq!(it.next().unwrap(), 4); assert!(it.next().is_none()); }
let a = [1i, 2];
let mut it = a.iter().map(|&x| 2 * x);
assert_eq!(it.next().unwrap(), 2);
assert_eq!(it.next().unwrap(), 4);
assert!(it.next().is_none());

fn filter(self, predicate: |&A| -> bool) -> Filter<'r, A, Self>

Creates an iterator which applies the predicate to each element returned by this iterator. Only elements which have the predicate evaluate to true will be yielded.

Example

fn main() { let a = [1i, 2]; let mut it = a.iter().filter(|&x| *x > 1); assert_eq!(it.next().unwrap(), &2); assert!(it.next().is_none()); }
let a = [1i, 2];
let mut it = a.iter().filter(|&x| *x > 1);
assert_eq!(it.next().unwrap(), &2);
assert!(it.next().is_none());

fn filter_map<B>(self, f: |A| -> Option<B>) -> FilterMap<'r, A, B, Self>

Creates an iterator which 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.

Example

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

fn enumerate(self) -> Enumerate<Self>

Creates an iterator which yields a pair of the value returned by this iterator plus the current index of iteration.

Example

fn main() { let a = [100i, 200]; let mut it = a.iter().enumerate(); let (x100, x200) = (100i, 200i); assert_eq!(it.next().unwrap(), (0, &x100)); assert_eq!(it.next().unwrap(), (1, &x200)); assert!(it.next().is_none()); }
let a = [100i, 200];
let mut it = a.iter().enumerate();
let (x100, x200) = (100i, 200i);
assert_eq!(it.next().unwrap(), (0, &x100));
assert_eq!(it.next().unwrap(), (1, &x200));
assert!(it.next().is_none());

fn peekable(self) -> Peekable<A, Self>

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

Example

fn main() { let xs = [100i, 200, 300]; let mut it = xs.iter().map(|x| *x).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()); }
let xs = [100i, 200, 300];
let mut it = xs.iter().map(|x| *x).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(self, predicate: |&A| -> bool) -> SkipWhile<'r, A, Self>

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

Example

fn main() { let a = [1i, 2, 3, 2, 1]; let mut it = a.iter().skip_while(|&a| *a < 3); assert_eq!(it.next().unwrap(), &3); assert_eq!(it.next().unwrap(), &2); assert_eq!(it.next().unwrap(), &1); assert!(it.next().is_none()); }
let a = [1i, 2, 3, 2, 1];
let mut it = a.iter().skip_while(|&a| *a < 3);
assert_eq!(it.next().unwrap(), &3);
assert_eq!(it.next().unwrap(), &2);
assert_eq!(it.next().unwrap(), &1);
assert!(it.next().is_none());

fn take_while(self, predicate: |&A| -> bool) -> TakeWhile<'r, A, Self>

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

Example

fn main() { let a = [1i, 2, 3, 2, 1]; let mut it = a.iter().take_while(|&a| *a < 3); assert_eq!(it.next().unwrap(), &1); assert_eq!(it.next().unwrap(), &2); assert!(it.next().is_none()); }
let a = [1i, 2, 3, 2, 1];
let mut it = a.iter().take_while(|&a| *a < 3);
assert_eq!(it.next().unwrap(), &1);
assert_eq!(it.next().unwrap(), &2);
assert!(it.next().is_none());

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

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

Example

fn main() { let a = [1i, 2, 3, 4, 5]; let mut it = a.iter().skip(3); assert_eq!(it.next().unwrap(), &4); assert_eq!(it.next().unwrap(), &5); assert!(it.next().is_none()); }
let a = [1i, 2, 3, 4, 5];
let mut it = a.iter().skip(3);
assert_eq!(it.next().unwrap(), &4);
assert_eq!(it.next().unwrap(), &5);
assert!(it.next().is_none());

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

Creates an iterator which yields the first n elements of this iterator, and then it will always return None.

Example

fn main() { let a = [1i, 2, 3, 4, 5]; let mut it = a.iter().take(3); assert_eq!(it.next().unwrap(), &1); assert_eq!(it.next().unwrap(), &2); assert_eq!(it.next().unwrap(), &3); assert!(it.next().is_none()); }
let a = [1i, 2, 3, 4, 5];
let mut it = a.iter().take(3);
assert_eq!(it.next().unwrap(), &1);
assert_eq!(it.next().unwrap(), &2);
assert_eq!(it.next().unwrap(), &3);
assert!(it.next().is_none());

fn scan<St, B>(self, initial_state: St, f: |&mut St, A| -> Option<B>) -> Scan<'r, A, B, Self, St>

Creates a new iterator which 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.

Example

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

fn flat_map<B, U: Iterator<B>>(self, f: |A| -> U) -> FlatMap<'r, A, Self, U>

Creates an iterator that maps each element to an iterator, and yields the elements of the produced iterators

Example

fn main() { use std::iter::count; let xs = [2u, 3]; let ys = [0u, 1, 0, 1, 2]; let mut it = xs.iter().flat_map(|&x| count(0u, 1).take(x)); // Check that `it` has the same elements as `ys` let mut i = 0; for x in it { assert_eq!(x, ys[i]); i += 1; } }
use std::iter::count;

let xs = [2u, 3];
let ys = [0u, 1, 0, 1, 2];
let mut it = xs.iter().flat_map(|&x| count(0u, 1).take(x));
// Check that `it` has the same elements as `ys`
let mut i = 0;
for x in it {
    assert_eq!(x, ys[i]);
    i += 1;
}

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.

Example

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

fn inspect(self, f: |&A|) -> Inspect<'r, A, Self>

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.

Example

fn main() { use std::iter::AdditiveIterator; let xs = [1u, 4, 2, 3, 8, 9, 6]; let sum = xs.iter() .map(|&x| x) .inspect(|&x| println!("filtering {}", x)) .filter(|&x| x % 2 == 0) .inspect(|&x| println!("{} made it through", x)) .sum(); println!("{}", sum); }
use std::iter::AdditiveIterator;

let xs = [1u, 4, 2, 3, 8, 9, 6];
let sum = xs.iter()
            .map(|&x| x)
            .inspect(|&x| println!("filtering {}", x))
            .filter(|&x| x % 2 == 0)
            .inspect(|&x| println!("{} made it through", x))
            .sum();
println!("{}", sum);

fn by_ref(&'r mut self) -> ByRef<'r, 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.

Example

fn main() { let mut xs = range(0u, 10); // sum the first five values let partial_sum = xs.by_ref().take(5).fold(0, |a, b| a + b); assert!(partial_sum == 10); // xs.next() is now `5` assert!(xs.next() == Some(5)); }
let mut xs = range(0u, 10);
// sum the first five values
let partial_sum = xs.by_ref().take(5).fold(0, |a, b| a + b);
assert!(partial_sum == 10);
// xs.next() is now `5`
assert!(xs.next() == Some(5));

fn collect<B: FromIterator<A>>(&mut self) -> B

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

Example

fn main() { let a = [1i, 2, 3, 4, 5]; let b: Vec<int> = a.iter().map(|&x| x).collect(); assert!(a.as_slice() == b.as_slice()); }
let a = [1i, 2, 3, 4, 5];
let b: Vec<int> = a.iter().map(|&x| x).collect();
assert!(a.as_slice() == b.as_slice());

fn nth(&mut self, n: uint) -> Option<A>

Loops through n iterations, returning the nth element of the iterator.

Example

fn main() { let a = [1i, 2, 3, 4, 5]; let mut it = a.iter(); assert!(it.nth(2).unwrap() == &3); assert!(it.nth(2) == None); }
let a = [1i, 2, 3, 4, 5];
let mut it = a.iter();
assert!(it.nth(2).unwrap() == &3);
assert!(it.nth(2) == None);

fn last(&mut self) -> Option<A>

Loops through the entire iterator, returning the last element of the iterator.

Example

fn main() { let a = [1i, 2, 3, 4, 5]; assert!(a.iter().last().unwrap() == &5); }
let a = [1i, 2, 3, 4, 5];
assert!(a.iter().last().unwrap() == &5);

fn fold<B>(&mut self, init: B, f: |B, A| -> B) -> B

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

Example

fn main() { let a = [1i, 2, 3, 4, 5]; assert!(a.iter().fold(0, |a, &b| a + b) == 15); }
let a = [1i, 2, 3, 4, 5];
assert!(a.iter().fold(0, |a, &b| a + b) == 15);

fn count(&mut self) -> uint

Counts the number of elements in this iterator.

Example

fn main() { let a = [1i, 2, 3, 4, 5]; let mut it = a.iter(); assert!(it.count() == 5); assert!(it.count() == 0); }
let a = [1i, 2, 3, 4, 5];
let mut it = a.iter();
assert!(it.count() == 5);
assert!(it.count() == 0);

fn all(&mut self, f: |A| -> bool) -> bool

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

Example

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

fn any(&mut self, f: |A| -> bool) -> bool

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

Example

fn main() { let a = [1i, 2, 3, 4, 5]; let mut it = a.iter(); assert!(it.any(|x| *x == 3)); assert!(!it.any(|x| *x == 3)); }
let a = [1i, 2, 3, 4, 5];
let mut it = a.iter();
assert!(it.any(|x| *x == 3));
assert!(!it.any(|x| *x == 3));

fn find(&mut self, predicate: |&A| -> bool) -> Option<A>

Return the first element satisfying the specified predicate

fn position(&mut self, predicate: |A| -> bool) -> Option<uint>

Return the index of the first element satisfying the specified predicate

fn max_by<B: Ord>(&mut self, f: |&A| -> B) -> Option<A>

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

Example

fn main() { let xs = [-3i, 0, 1, 5, -10]; assert_eq!(*xs.iter().max_by(|x| x.abs()).unwrap(), -10); }
let xs = [-3i, 0, 1, 5, -10];
assert_eq!(*xs.iter().max_by(|x| x.abs()).unwrap(), -10);

fn min_by<B: Ord>(&mut self, f: |&A| -> B) -> Option<A>

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

Example

fn main() { let xs = [-3i, 0, 1, 5, -10]; assert_eq!(*xs.iter().min_by(|x| x.abs()).unwrap(), 0); }
let xs = [-3i, 0, 1, 5, -10];
assert_eq!(*xs.iter().min_by(|x| x.abs()).unwrap(), 0);

Implementors