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