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::IntoIter> where J: IntoIterator<Item=Self::Item>, Self: Sized { ... }
    fn intersperse(self, element: Self::Item) -> Intersperse<Self> where Self: Sized, Self::Item: Clone { ... }
    fn zip_longest<J>(self, other: J) -> ZipLongest<Self, J::IntoIter> where J: IntoIterator, 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) -> MergeAscend<Self, J::IntoIter, Self::Item> where Self: Sized, Self::Item: PartialOrd, J: IntoIterator<Item=Self::Item> { ... }
    fn merge_by<J, F>(self, other: J, cmp: F) -> Merge<Self, J::IntoIter, F> where Self: Sized, J: IntoIterator<Item=Self::Item>, F: FnMut(&Self::Item, &Self::Item) -> Ordering { ... }
    fn cartesian_product<J>(self, other: J) -> Product<Self, J::IntoIter> where Self: Sized, Self::Item: Clone, J: IntoIterator, J::IntoIter: Clone { ... }
    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 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: IntoIterator<Item=A> { ... }
    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::IntoIter> where J: IntoIterator<Item=Self::Item>, Self: Sized

Alternate elements from two iterators until both run out.

Iterator element type is Self::Item.

Example

use itertools::Itertools;

let it = (0..3).interleave(vec![7, 7]);
assert!(itertools::equal(it, vec![0, 7, 1, 7, 2]));

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<J>(self, other: J) -> ZipLongest<Self, J::IntoIter> where J: IntoIterator, Self: Sized

Create an iterator which iterates over both this and the specified iterator 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 it = (0..1).zip_longest(1..3);
assert!(itertools::equal(it, vec![Both(0, 1), Right(2)]));

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 pit = (0..4).batching(|mut it| {
           match it.next() {
               None => None,
               Some(x) => match it.next() {
                   None => None,
                   Some(y) => Some((x, y)),
               }
           }
       });

assert!(itertools::equal(pit, vec![(0, 1), (2, 3)]));

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 it = (0..8).step(3);
assert!(itertools::equal(it, vec![0, 3, 6]));

fn merge<J>(self, other: J) -> MergeAscend<Self, J::IntoIter, Self::Item> where Self: Sized, Self::Item: PartialOrd, J: IntoIterator<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..11).step(3);
let b = (0..11).step(5);
let it = a.merge(b);
assert!(itertools::equal(it, vec![0, 0, 3, 5, 6, 9, 10]));

fn merge_by<J, F>(self, other: J, cmp: F) -> Merge<Self, J::IntoIter, F> where Self: Sized, J: IntoIterator<Item=Self::Item>, F: FnMut(&Self::Item, &Self::Item) -> Ordering

Return an iterator adaptor that merges the two base iterators in order. This is much like .merge() but allows for a custom ordering.

This can be especially useful for sequences of tuples.

Iterator element type is Self::Item.

Example

use itertools::Itertools;

let a = (0..).zip("bc".chars());
let b = (0..).zip("ad".chars());
let it = a.merge_by(b, |x, y| x.1.cmp(&y.1));
assert!(itertools::equal(it, vec![(0, 'a'), (0, 'b'), (1, 'c'), (1, 'd')]));

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

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 it = (0..2).cartesian_product("αβ".chars());
assert!(itertools::equal(it, vec![(0, 'α'), (0, 'β'), (1, 'α'), (1, 'β')]));

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 is reset.

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 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: IntoIterator<Item=A>

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

The from iterator is queried for its next element before the self iterator, and if either is exhausted the method is done.

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 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, the operation terminates and returns the first Err value it encounters. No iterator elements are consumed after the first error.

The first accumulator value is the start parameter. Each iteration passes the accumulator value and the next value inside Ok to the fold function f and its return value becomes the new accumulator value.

For example the sequence Ok(1), Ok(2), Ok(3) will result in a computation like this:

let mut accum = start;
accum = f(accum, 1);
accum = f(accum, 2);
accum = f(accum, 3);

With a start value of 0 and an addition as folding function, this effetively results in ((0 + 1) + 2) + 3

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