Trait std::iter::IteratorExtUnstable
[-]
[+]
[src]
pub trait IteratorExt<A>: Iterator<A> { 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, F: FnMut(A) -> B>(self, f: F) -> Map<A, B, Self, F> { ... } fn filter<P>(self, predicate: P) -> Filter<A, Self, P> { ... } fn filter_map<B, F>(self, f: F) -> FilterMap<A, B, Self, F> { ... } fn enumerate(self) -> Enumerate<Self> { ... } fn peekable(self) -> Peekable<A, Self> { ... } fn skip_while<P>(self, predicate: P) -> SkipWhile<A, Self, P> { ... } fn take_while<P>(self, predicate: P) -> TakeWhile<A, Self, P> { ... } fn skip(self, n: uint) -> Skip<Self> { ... } fn take(self, n: uint) -> Take<Self> { ... } fn scan<St, B, F>(self, initial_state: St, f: F) -> Scan<A, B, Self, St, F> { ... } fn flat_map<B, U, F>(self, f: F) -> FlatMap<A, B, Self, U, F> { ... } fn fuse(self) -> Fuse<Self> { ... } fn inspect<F>(self, f: F) -> Inspect<A, Self, F> { ... } fn by_ref(&'r mut self) -> ByRef<'r, Self> { ... } fn collect<B: FromIterator<A>>(self) -> B { ... } fn partition<B, F>(self, f: F) -> (B, B) { ... } fn nth(&mut self, n: uint) -> Option<A> { ... } fn last(self) -> Option<A> { ... } fn fold<B, F>(self, init: B, f: F) -> B { ... } fn count(self) -> uint { ... } fn all<F>(self, f: F) -> bool { ... } fn any<F>(&mut self, f: F) -> bool { ... } fn find<P>(&mut self, predicate: P) -> Option<A> { ... } fn position<P>(&mut self, predicate: P) -> Option<uint> { ... } fn max_by<B: Ord, F>(self, f: F) -> Option<A> { ... } fn min_by<B: Ord, F>(self, f: F) -> Option<A> { ... } }
An extension trait providing numerous methods applicable to all iterators.
Provided Methods
fn chain<U: Iterator<A>>(self, other: U) -> Chain<Self, U>
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.
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 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.
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, F: FnMut(A) -> B>(self, f: F) -> Map<A, B, Self, F>
Creates a new iterator that 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<P>(self, predicate: P) -> Filter<A, Self, P>
Creates an iterator that applies the predicate to each element returned
by this iterator. Only elements that 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, F>(self, f: F) -> FilterMap<A, B, Self, F>
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.
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 that 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<P>(self, predicate: P) -> SkipWhile<A, Self, P>
Creates an iterator that 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<P>(self, predicate: P) -> TakeWhile<A, Self, P>
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.
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 that skips the first n
elements of this iterator,
and then 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 that yields the first n
elements of this
iterator, and then 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, F>(self, initial_state: St, f: F) -> Scan<A, B, Self, St, F>
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.
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, F>(self, f: F) -> FlatMap<A, B, Self, U, F>
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<F>(self, f: F) -> Inspect<A, Self, F>
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>>(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 partition<B, F>(self, f: F) -> (B, B)
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.
fn main() { let vec = vec![1i, 2i, 3i, 4i]; let (even, odd): (Vec<int>, Vec<int>) = vec.into_iter().partition(|&n| n % 2 == 0); assert_eq!(even, vec![2, 4]); assert_eq!(odd, vec![1, 3]); }let vec = vec![1i, 2i, 3i, 4i]; let (even, odd): (Vec<int>, Vec<int>) = vec.into_iter().partition(|&n| n % 2 == 0); assert_eq!(even, vec![2, 4]); assert_eq!(odd, vec![1, 3]);
fn nth(&mut self, n: uint) -> Option<A>
Loops through n
iterations, returning the n
th 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(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, F>(self, init: B, f: F) -> 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(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); }let a = [1i, 2, 3, 4, 5]; let mut it = a.iter(); assert!(it.count() == 5);
fn all<F>(self, f: F) -> 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<F>(&mut self, f: F) -> 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<P>(&mut self, predicate: P) -> Option<A>
Returns the first element satisfying the specified predicate.
Does not consume the iterator past the first found element.
fn position<P>(&mut self, predicate: P) -> Option<uint>
Return the index of the first element satisfying the specified predicate
fn max_by<B: Ord, F>(self, f: F) -> Option<A>
Return the element that gives the maximum value from the specified function.
Example
fn main() { use core::num::SignedInt; let xs = [-3i, 0, 1, 5, -10]; assert_eq!(*xs.iter().max_by(|x| x.abs()).unwrap(), -10); }use core::num::SignedInt; let xs = [-3i, 0, 1, 5, -10]; assert_eq!(*xs.iter().max_by(|x| x.abs()).unwrap(), -10);
fn min_by<B: Ord, F>(self, f: F) -> Option<A>
Return the element that gives the minimum value from the specified function.
Example
fn main() { use core::num::SignedInt; let xs = [-3i, 0, 1, 5, -10]; assert_eq!(*xs.iter().min_by(|x| x.abs()).unwrap(), 0); }use core::num::SignedInt; let xs = [-3i, 0, 1, 5, -10]; assert_eq!(*xs.iter().min_by(|x| x.abs()).unwrap(), 0);
Implementors
impl<A, I> IteratorExt<A> for I