Crate `itertools`

Extra iterator adaptors, functions and macros.

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

# #[allow(unused_imports)]
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 */
    # let _ = elt;
}

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.

Modules

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

Structs

AllEqualValueError Value returned for the error case of Itertools::all_equal_value.
ArrayWindows An iterator over all contiguous windows of the input iterator, producing arrays of a specific size.
Batching A “meta iterator adaptor”. Its closure receives a reference to the iterator and may pick off as many elements as it likes, to produce the next iterator element.
Chunk An iterator for the elements in a single chunk.
ChunkBy ChunkBy is the storage for the lazy grouping operation.
Chunks An iterator that yields the Chunk iterators.
CircularArrayWindows An iterator over all windows, wrapping back to the first elements when the window would otherwise exceed the length of the iterator, producing arrays of a specific size.
CircularTupleWindows An iterator over all windows, wrapping back to the first elements when the window would otherwise exceed the length of the iterator, producing tuples of a specific size.
ExactlyOneError Iterator returned for the error case of Itertools exactly_one() and at_most_one(). This iterator yields exactly the same elements as the input iterator.
FilterMapOk An iterator adapter to filter and apply a transformation on values within a nested Result::Ok.
FilterOk An iterator adapter to filter values within a nested Result::Ok.
FlattenOk An iterator adaptor that flattens Result::Ok values and allows Result::Err values through unchanged.
Format Format all iterator elements lazily, separated by sep.
FormatWith Format all iterator elements lazily, separated by sep.
Group An iterator for the elements in a single group.
GroupingMap GroupingMap is an intermediate struct for efficient group-and-fold operations. It groups elements by their key and at the same time fold each group using some aggregating operation.
Groups An iterator that yields the Group iterators.
Interleave An iterator adaptor that alternates elements from two iterators until both run out.
InterleaveShortest An iterator adaptor that alternates elements from the two iterators until one of them runs out.
IntersperseWith An iterator adaptor to insert a particular value created by a function between each element of the adapted iterator.
IntoChunks IntoChunks is the storage for a lazy chunking operation.
Iterate An iterator that infinitely applies function to value and yields results.
KMergeBy An iterator adaptor that merges an arbitrary number of base iterators according to an ordering function.
MergeBy An iterator adaptor that merges the two base iterators in ascending order. If both base iterators are sorted (ascending), the result is sorted.
MultiPeek See [multipeek()] for more information.
MultiProduct An iterator adaptor that iterates over the cartesian product of multiple iterators of type I.
PadUsing An iterator adaptor that pads a sequence to a minimum length by filling missing elements using a closure.
PeekNth See [peek_nth()] for more information.
PeekingTakeWhile An iterator adaptor that takes items while a closure returns true.
Permutations An iterator adaptor that iterates through all the k-permutations of the elements from an iterator.
Position The first component of the value yielded by WithPosition. Indicates the position of this element in the iterator results.
Positions An iterator adapter to get the positions of each element that matches a predicate.
Powerset An iterator to iterate through the powerset of the elements from an iterator.
ProcessResults An iterator that produces only the T values as long as the inner iterator produces Ok(T).
Product An iterator adaptor that iterates over the cartesian product of the element sets of two iterators I and J.
PutBack An iterator adaptor that allows putting back a single item to the front of the iterator.
PutBackN An iterator adaptor that allows putting multiple items in front of the iterator.
RcIter A wrapper for Rc<RefCell<I>>, that implements the Iterator trait.
RepeatN An iterator that produces n repetitions of an element.
StripPrefixError The error returned by Itertools::strip_prefix and Itertools::strip_prefix_by when the iterator does not start with the requested prefix.
TakeWhileInclusive An iterator adaptor that consumes elements while the given predicate is true, including the element for which the predicate first returned false.
TakeWhileRef An iterator adaptor that borrows from a Clone-able iterator to only pick off elements while the predicate returns true.
Tee One half of an iterator pair where both return the same elements.
TupleBuffer An iterator over a incomplete tuple.
TupleCombinations An iterator to iterate through all combinations in a Clone-able iterator that produces tuples of a specific size.
TupleWindows An iterator over all contiguous windows that produces tuples of a specific size.
Tuples An iterator that groups the items in tuples of a specific size.
Unfold See unfold for more information.
Unique An iterator adapter to filter out duplicate elements.
UniqueBy An iterator adapter to filter out duplicate elements.
Update An iterator adapter to apply a mutating function to each element before yielding it.
WhileSome An iterator adaptor that filters Option<A> iterator elements and produces A. Stops on the first None encountered.
WithPosition An iterator adaptor that wraps each element in an Position.
Zip See multizip for more information.
ZipEq An iterator which iterates two other iterators simultaneously and panic if they have different lengths.
ZipLongest An iterator which iterates two other iterators simultaneously and wraps the elements in EitherOrBoth.

Enums

Diff A type returned by the diff_with function.
Either
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.

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

assert_equal Assert that two iterables produce equal sequences, with the same semantics as equal(a, b).
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.
equal Return true if both iterables produce equal sequences (elements pairwise equal and sequences of the same length), false otherwise.
iterate Creates a new iterator that infinitely applies function to value and yields results.
kmerge_by Create an iterator that merges elements of the contained iterators.
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.
process_results “Lift” a function of the values of an iterator so that it can process an iterator of Result values instead.
repeat_n Create an iterator that produces n repetitions of element.
unfold Creates a new unfold source with the specified closure as the "iterator function" and an initial state to eventually pass to the closure

Type Aliases

ArrayCombinations Iterator for const generic combinations returned by .array_combinations()
Coalesce An iterator adaptor that may join together adjacent elements.
Combinations Iterator for Vec valued combinations returned by .combinations()
CombinationsWithReplacement Iterator for Box<[I]> valued combinations_with_replacement returned by .combinations_with_replacement()
ConsTuples An iterator that maps an iterator of tuples like ((A, B), C) to an iterator of (A, B, C).
Dedup An iterator adaptor that removes repeated duplicates.
DedupBy An iterator adaptor that removes repeated duplicates, determining equality using a comparison function.
DedupByWithCount An iterator adaptor that removes repeated duplicates, while keeping a count of how many repeated elements were present. This will determine equality using a comparison function.
DedupWithCount An iterator adaptor that removes repeated duplicates, while keeping a count of how many repeated elements were present.
Duplicates An iterator adapter to filter out duplicate elements.
DuplicatesBy An iterator adapter to filter for duplicate elements.
GroupBy See ChunkBy.
GroupingMapBy GroupingMapBy is an intermediate struct for efficient group-and-fold operations.
Intersperse An iterator adaptor to insert a particular value between each element of the adapted iterator.
KMerge An iterator adaptor that merges an arbitrary number of base iterators in ascending order. If all base iterators are sorted (ascending), the result is sorted.
MapInto An iterator adapter to apply Into conversion to each element.
MapOk An iterator adapter to apply a transformation within a nested Result::Ok.
Merge An iterator adaptor that merges the two base iterators in ascending order. If both base iterators are sorted (ascending), the result is sorted.
MergeJoinBy An iterator adaptor that merge-joins items from the two base iterators in ascending order.

Macros

chain [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.