Crate itertools

Available on crate feature dep_itertools only.
Expand description

itertools Extra iterator adaptors, iterator methods, functions, and macros.


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.

Modules§

__std_iter
Composable external iteration.
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.

Structs§

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.
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.
CombinationsWithReplacement
An iterator to iterate through all the n-length combinations in an iterator, with replacement.
ExactlyOneError
Iterator returned for the error case of Itertools::exactly_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
ChunkLazy 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 abitrary 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.
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.
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.
UnfoldDeprecated
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
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.

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()
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.
GroupByDeprecated
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 abitrary 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.