Crate itertools

Extra iterator adaptors, functions and macros.

To extend Iterator with methods in this crate, import the Itertools trait:

use itertools::Itertools;

Now, new methods like interleave are available on all iterators:

use itertools::Itertools;

let it = (1..3).interleave(vec![-1, -2]);
itertools::assert_equal(it, vec![1, -1, 2, -2]);

Most iterator methods are also provided as functions (with the benefit that they convert parameters using IntoIterator):

use itertools::interleave;

for elt in interleave(&[1, 2, 3], &[2, 3, 4]) {
    /* loop body */
}

Crate Features

• use_std
  • Enabled by default.
  • Disable to compile itertools using #![no_std]. This disables any item that depend on allocations (see the use_alloc feature) and hash maps (like unique, counts, into_grouping_map and more).
• use_alloc
  • Enabled by default.
  • Enables any item that depend on allocations (like chunk_by, kmerge, join and many more).

Rust Version

This version of itertools requires Rust 1.43.1 or later.

Re-exports

• pub use crate::structs::*;

Modules

• structs
  The concrete iterator types.
• traits
  Traits helpful for using certain Itertools methods in generic contexts.

Macros

• chain
  Chain zero or more iterators together into one sequence.
• iproduct
  Create an iterator over the “cartesian product” of iterators.
• izip
  Create an iterator running multiple iterators in lockstep.

Enums

• Diff
  A type returned by the diff_with function.
• Either
  The enum Either with variants Left and Right is a general purpose sum type with two cases.
• EitherOrBoth
  Value that either holds a single A or B, or both.
• FoldWhile
  An enum used for controlling the execution of fold_while.
• MinMaxResult
  MinMaxResult is an enum returned by minmax.
• Position
  The first component of the value yielded by WithPosition. Indicates the position of this element in the iterator results.

Traits

• Itertools
  An Iterator blanket implementation that provides extra adaptors and methods.
• MultiUnzip
  An iterator that can be unzipped into multiple collections.
• PeekingNext
  An iterator that allows peeking at an element before deciding to accept it.

Functions

• all
  Test whether the predicate holds for all elements in the iterable.
• any
  Test whether the predicate holds for any elements in the iterable.
• assert_equal
  Assert that two iterables produce equal sequences, with the same semantics as equal(a, b).
• chain
  Takes two iterables and creates a new iterator over both in sequence.
• cloned
  Create an iterator that clones each element from &T to T.
• concat
  Combine all an iterator’s elements into one element by using Extend.
• cons_tuples
  Create an iterator that maps for example iterators of ((A, B), C) to (A, B, C).
• diff_with
  Compares every element yielded by both i and j with the given function in lock-step and returns a Diff which describes how j differs from i.
• enumerate
  Iterate iterable with a running index.
• equal
  Return true if both iterables produce equal sequences (elements pairwise equal and sequences of the same length), false otherwise.
• fold
  Perform a fold operation over the iterable.
• interleave
  Create an iterator that interleaves elements in i and j.
• intersperse
  Iterate iterable with a particular value inserted between each element.
• intersperse_with
  Iterate iterable with a particular value created by a function inserted between each element.
• iterate
  Creates a new iterator that infinitely applies function to value and yields results.
• join
  Combine all iterator elements into one String, separated by sep.
• kmerge
  Create an iterator that merges elements of the contained iterators using the ordering function.
• kmerge_by
  Create an iterator that merges elements of the contained iterators.
• max
  Return the maximum value of the iterable.
• merge
  Create an iterator that merges elements in i and j.
• merge_join_by
  Return an iterator adaptor that merge-joins items from the two base iterators in ascending order.
• min
  Return the minimum value of the iterable.
• multipeek
  An iterator adaptor that allows the user to peek at multiple .next() values without advancing the base iterator.
• multiunzip
  Converts an iterator of tuples into a tuple of containers.
• multizip
  An iterator that generalizes .zip() and allows running multiple iterators in lockstep.
• partition
  Partition a sequence using predicate pred so that elements that map to true are placed before elements which map to false.
• peek_nth
  A drop-in replacement for std::iter::Peekable which adds a peek_nth method allowing the user to peek at a value several iterations forward without advancing the base iterator.
• process_results
  “Lift” a function of the values of an iterator so that it can process an iterator of Result values instead.
• put_back
  Create an iterator where you can put back a single item
• put_back_n
  Create an iterator where you can put back multiple values to the front of the iteration.
• rciter
  Return an iterator inside a Rc<RefCell<_>> wrapper.
• repeat_n
  Create an iterator that produces n repetitions of element.
• rev
  Iterate iterable in reverse.
• sorted
  Sort all iterator elements into a new iterator in ascending order.
• sorted_unstable
  Sort all iterator elements into a new iterator in ascending order. This sort is unstable (i.e., may reorder equal elements).
• unfoldDeprecated
  Creates a new unfold source with the specified closure as the “iterator function” and an initial state to eventually pass to the closure
• zipDeprecated
  Converts the arguments to iterators and zips them.
• zip_eq
  Zips two iterators but panics if they are not of the same length.