Crate itertools

Available on crate feature dep_itertools only.

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.