Trait itertools::Itertools

pub trait Itertools: Iterator {
    fn fn_map<B>(self, map: fn(Self::Item) -> B) -> FnMap<B, Self> where Self: Sized { ... }
    fn interleave<J>(self, other: J) -> Interleave<Self, J> where J: Iterator<Item=Self::Item>, Self: Sized { ... }
    fn intersperse(self, element: Self::Item) -> Intersperse<Self> where Self: Sized, Self::Item: Clone { ... }
    fn zip_longest<U>(self, other: U) -> ZipLongest<Self, U> where U: Iterator, Self: Sized { ... }
    fn dedup(self) -> Dedup<Self> where Self: Sized { ... }
    fn batching<B, F: FnMut(&mut Self) -> Option<B>>(self, f: F) -> Batching<Self, F> where Self: Sized { ... }
    fn group_by<K, F: FnMut(&Self::Item) -> K>(self, key: F) -> GroupBy<K, Self, F> where Self: Sized { ... }
    fn tee(self) -> (Tee<Self>, Tee<Self>) where Self: Sized, Self::Item: Clone { ... }
    fn slice<R>(self, range: R) -> ISlice<Self> where R: GenericRange, Self: Sized { ... }
    fn into_rc(self) -> RcIter<Self> where Self: Sized { ... }
    fn step(self, n: usize) -> Step<Self> where Self: Sized { ... }
    fn merge<J>(self, other: J) -> Merge<Self, J> where Self: Sized, Self::Item: PartialOrd, J: Iterator<Item=Self::Item> { ... }
    fn cartesian_product<J>(self, other: J) -> Product<Self, J> where Self: Sized, Self::Item: Clone, J: Clone + Iterator { ... }
    fn multipeek(self) -> MultiPeek<Self> where Self: Sized { ... }
    fn find_position<P>(&mut self, pred: P) -> Option<(usize, Self::Item)> where P: FnMut(&Self::Item) -> bool { ... }
    fn dropn(&mut self, n: usize) -> usize { ... }
    fn dropping(self, n: usize) -> Self where Self: Sized { ... }
    fn drain(&mut self) { ... }
    fn apply<F>(&mut self, f: F) where F: FnMut(Self::Item) { ... }
    fn foreach<F>(&mut self, f: F) where F: FnMut(Self::Item) { ... }
    fn collect_vec(self) -> Vec<Self::Item> where Self: Sized { ... }
    fn set_from<'a, A: 'a, J>(&mut self, from: J) -> usize where Self: Iterator<Item=&'a mut A>, J: Iterator<Item=A> { ... }
    fn to_string_join(&mut self, sep: &str) -> String where Self::Item: ToString { ... }
    fn join(&mut self, sep: &str) -> String where Self::Item: Display { ... }
    fn fold_results<A, E, B, F>(&mut self, start: B, f: F) -> Result<B, E> where Self: Iterator<Item=Result<A, E>>, F: FnMut(B, A) -> B { ... }
}

Extra iterator methods for arbitrary iterators

Provided Methods

fn fn_map<B>(self, map: fn(Self::Item) -> B) -> FnMap<B, Self> where Self: Sized

Like regular .map(), but using a simple function pointer instead, so that the resulting FnMap iterator value can be cloned.

Iterator element type is B.

fn interleave<J>(self, other: J) -> Interleave<Self, J> where J: Iterator<Item=Self::Item>, Self: Sized

Alternate elements from two iterators until both are run out

Iterator element type is Self::Item.

fn intersperse(self, element: Self::Item) -> Intersperse<Self> where Self: Sized, Self::Item: Clone

An iterator adaptor to insert a particular value between each element of the adapted iterator.

Iterator element type is Self::Item.

fn zip_longest<U>(self, other: U) -> ZipLongest<Self, U> where U: Iterator, Self: Sized

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

Example

use itertools::EitherOrBoth::{Both, Right};
use itertools::Itertools;
let mut it = (0..1).zip_longest(1..3);
assert_eq!(it.next(), Some(Both(0, 1)));
assert_eq!(it.next(), Some(Right(2)));
assert_eq!(it.next(), None);

Iterator element type is EitherOrBoth<Self::Item, B>.

fn dedup(self) -> Dedup<Self> where Self: Sized

Remove duplicates from sections of consecutive identical elements. If the iterator is sorted, all elements will be unique.

Iterator element type is Self::Item.

fn batching<B, F: FnMut(&mut Self) -> Option<B>>(self, f: F) -> Batching<Self, F> where Self: Sized

A “meta iterator adaptor”. Its closure recives a reference to the iterator and may pick off as many elements as it likes, to produce the next iterator element.

Iterator element type is B.

Example

use itertools::Itertools;
// An adaptor that gathers elements up in pairs
let mut pit = (0..4).batching(|mut it| {
           match it.next() {
               None => None,
               Some(x) => match it.next() {
                   None => None,
                   Some(y) => Some((x, y)),
               }
           }
       });
assert_eq!(pit.next(), Some((0, 1)));
assert_eq!(pit.next(), Some((2, 3)));
assert_eq!(pit.next(), None);

fn group_by<K, F: FnMut(&Self::Item) -> K>(self, key: F) -> GroupBy<K, Self, F> where Self: Sized

Group iterator elements. Consecutive elements that map to the same key (“runs”), are returned as the iterator elements of GroupBy.

Iterator element type is (K, Vec<Self::Item>)

fn tee(self) -> (Tee<Self>, Tee<Self>) where Self: Sized, Self::Item: Clone

Split into an iterator pair that both yield all elements from the original iterator.

Iterator element type is Self::Item.

Example

use itertools::Itertools;
let xs = vec![0, 1, 2, 3];

let (mut t1, mut t2) = xs.into_iter().tee();
assert_eq!(t1.next(), Some(0));
assert_eq!(t1.next(), Some(1));
assert_eq!(t2.next(), Some(0));
assert_eq!(t1.next(), Some(2));
assert_eq!(t1.next(), Some(3));
assert_eq!(t1.next(), None);
assert_eq!(t2.next(), Some(1));

fn slice<R>(self, range: R) -> ISlice<Self> where R: GenericRange, Self: Sized

Return a sliced iterator.

Note: slicing an iterator is not constant time, and much less efficient than slicing for example a vector.

Iterator element type is Self::Item.

Example

use std::iter::repeat;
use itertools::Itertools;

let mut it = repeat('a').slice(..3);
assert_eq!(it.count(), 3);

fn into_rc(self) -> RcIter<Self> where Self: Sized

Return an iterator inside a Rc<RefCell<_>> wrapper.

The returned RcIter can be cloned, and each clone will refer back to the same original iterator.

RcIter allows doing interesting things like using .zip() on an iterator with itself, at the cost of runtime borrow checking. (If it is not obvious: this has a performance penalty.)

Iterator element type is Self::Item.

Example

use itertools::Itertools;

let mut rit = (0..9).into_rc();
let mut z = rit.clone().zip(rit.clone());
assert_eq!(z.next(), Some((0, 1)));
assert_eq!(z.next(), Some((2, 3)));
assert_eq!(z.next(), Some((4, 5)));
assert_eq!(rit.next(), Some(6));
assert_eq!(z.next(), Some((7, 8)));
assert_eq!(z.next(), None);

Panics in iterator methods if a borrow error is encountered, but it can only happen if the RcIter is reentered in for example .next(), i.e. if it somehow participates in an "iterator knot" where it is an adaptor of itself.

fn step(self, n: usize) -> Step<Self> where Self: Sized

Return an iterator adaptor that steps n elements in the base iterator for each iteration.

The iterator steps by yielding the next element from the base iterator, then skipping forward n - 1 elements.

Iterator element type is Self::Item.

Panics if the step is 0.

Example

use itertools::Itertools;

let mut it = (0..8).step(3);
assert_eq!(it.next(), Some(0));
assert_eq!(it.next(), Some(3));
assert_eq!(it.next(), Some(6));
assert_eq!(it.next(), None);

fn merge<J>(self, other: J) -> Merge<Self, J> where Self: Sized, Self::Item: PartialOrd, J: Iterator<Item=Self::Item>

Return an iterator adaptor that merges the two base iterators in ascending order. If both base iterators are sorted (ascending), the result is sorted.

Iterator element type is Self::Item.

Example

use itertools::Itertools;

let a = (0..10).step(2);
let b = (1..10).step(3);
let mut it = a.merge(b);
assert_eq!(it.next(), Some(0));
assert_eq!(it.next(), Some(1));
assert_eq!(it.next(), Some(2));
assert_eq!(it.next(), Some(4));
assert_eq!(it.next(), Some(4));
assert_eq!(it.next(), Some(6));

fn cartesian_product<J>(self, other: J) -> Product<Self, J> where Self: Sized, Self::Item: Clone, J: Clone + Iterator

Return an iterator adaptor that iterates over the cartesian product of the element sets of two iterators self and J.

Iterator element type is (Self::Item, J::Item).

use itertools::Itertools;

let mut it = (0..2).cartesian_product("αβ".chars());
assert_eq!(it.next(), Some((0, 'α')));
assert_eq!(it.next(), Some((0, 'β')));
assert_eq!(it.next(), Some((1, 'α')));
assert_eq!(it.next(), Some((1, 'β')));
assert_eq!(it.next(), None);

fn multipeek(self) -> MultiPeek<Self> where Self: Sized

Returns an iterator adapter that allows peeking multiple values.

After a call to .next() the peeking cursor gets resetted.

Example

use itertools::Itertools;

let nums = vec![1u8,2,3,4,5];
let mut peekable = nums.into_iter().multipeek();
assert_eq!(peekable.peek(), Some(&1));
assert_eq!(peekable.peek(), Some(&2));
assert_eq!(peekable.peek(), Some(&3));
assert_eq!(peekable.next(), Some(1));
assert_eq!(peekable.peek(), Some(&2));

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

Find the position and value of the first element satisfying a predicate.

fn dropn(&mut self, n: usize) -> usize

Consume the first n elements of the iterator eagerly.

Return actual number of elements consumed, until done or reaching the end.

fn dropping(self, n: usize) -> Self where Self: Sized

Consume the first n elements from the iterator eagerly, and return the same iterator again.

It works similarly to .skip(n) except it is eager and preserves the iterator type.

fn drain(&mut self)

Deprecated: because of a name clash, use .count() or .foreach() instead as appropriate.

Run the iterator, eagerly, to the end and consume all its elements.

Example

use itertools::Itertools;

let mut cnt = 0;
"hi".chars().map(|c| cnt += 1).drain();

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

Deprecated: Use .foreach() instead.

Run the closure f eagerly on each element of the iterator.

Consumes the iterator until its end.

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

Run the closure f eagerly on each element of the iterator.

Consumes the iterator until its end.

fn collect_vec(self) -> Vec<Self::Item> where Self: Sized

.collect_vec() is simply a type specialization of .collect(), for convenience.

fn set_from<'a, A: 'a, J>(&mut self, from: J) -> usize where Self: Iterator<Item=&'a mut A>, J: Iterator<Item=A>

Assign to each reference in self from the from iterator, stopping at the shortest of the two iterators.

Return the number of elements written.

Example

use itertools::Itertools;

let mut xs = [0; 4];
xs.iter_mut().set_from(1..);
assert_eq!(xs, [1, 2, 3, 4]);

fn to_string_join(&mut self, sep: &str) -> String where Self::Item: ToString

Deprecated: Use .join() instead, it's more efficient..

Convert each element to String before joining them all together.

Like .join(), but converts each element to String explicitly first.

Example

use itertools::Itertools;

assert_eq!([1, 2, 3].iter().to_string_join(", "), "1, 2, 3");

fn join(&mut self, sep: &str) -> String where Self::Item: Display

Combine all iterator elements into one String, seperated by sep.

Use the Display implementation of each element.

Example

use itertools::Itertools;

assert_eq!(["a", "b", "c"].iter().join(", "), "a, b, c");
assert_eq!([1, 2, 3].iter().join(", "), "1, 2, 3");

fn fold_results<A, E, B, F>(&mut self, start: B, f: F) -> Result<B, E> where Self: Iterator<Item=Result<A, E>>, F: FnMut(B, A) -> B

Fold Result values from an iterator.

Only Ok values are folded. If no error is encountered, the folded value is returned inside Ok. Otherwise and the operation terminates and returns the first error it encounters. No iterator elements are consumed after the first error.

Example

use std::ops::Add;
use itertools::Itertools;

let values = [1, 2, -2, -1, 2, 1];
assert_eq!(
    values.iter()
        .map(Ok::<_, ()>)
        .fold_results(0, Add::add),
    Ok(3)
);
assert!(
    values.iter()
        .map(|&x| if x >= 0 { Ok(x) } else { Err("Negative number") })
        .fold_results(0, Add::add)
        .is_err()
);

Implementors

• impl<T: ?Sized> Itertools for T where T: Iterator