Rust Iterator Cheat Sheet

Last updated: Rust 1.17.0, Itertools 0.6.0.

To-do:

Improve formatting.
Try to fix display bugs (lines through cells).
Add sorting... somehow

How you can help:

I need feedback on what does and doesn't work. Can you understand the summaries? Do they mesh with how you perceive the methods in question work? What other information could/should be included?

If you have any corrections or suggestions, you can file them on the GitHub repository. The canonical source for this page is src/itercheat/itercheat.html.

Jump to: Generators, Sequences, Free-Standing Sequences, Values, Other, Notes.

This summarises the iterator-related methods defined by the following Rust libraries:

Std: the Rust standard library. Methods are defined on the std::iter::Iterator trait.
IT: the itertools library. Methods are defined on the itertools::Itertools trait.

Additional filtering options:

Unstable: show unstable methods.

This is intended to be used in one of a few ways:

You know what an iterator method is called, but you want a quick summary of what it does.
You know what you want to do with an iterator, but not what it's called.
You just want to browse through a summary of the available methods because you're bored.

To keep the summary as compact as possible, various bits of notation and convention are used. An incomplete list is:

Most iterator methods take their first input by-value; those that don't are marked with a $\text{&mut}$ out the front of their first argument.
Elements are underlined to indicate that the method will not compute those elements during the course of its own evaluation.
$\{\ldots\}$ is used to represent a lazily computed sequence; i.e. an iterator.
$\{\ldots\}:\{T\}$ indicates an iterator where each element is of type T.
$a$ and $b$ are used as input sequences (with subscripted letters denoting individual elements).
$c$ is used to represent the output sequence in cases where there is no direct mapping of input elements to output elements.
$i$ , $j$ , and $k$ are used to denote specific, but arbitrary, points within sequences.
$n$ , $m$ , and $l$ are used to denote the length of different sequences.
$[\ldots]$ is used to represent a collection of arbitrary type. Typically, the exact type is inferred from context, and can be anything that implements the FromIterator trait.
$f$ is a function which transforms elements.
$p$ is a predicate which determines some logical property of elements.
$\circ$ is an arbitrary binary function.
$\langle \ldots\rangle$ is used to indicate a generic type argument contains relevant information.
$\text{wh.}$ is an abbreviation for "where".

Generators

Lib	Function	Input		Output
Std	$\text{empty}$			$\{\}$
IT	$\text{iterate}$	$x : T$	$f : \text{&}T \rightarrow T$	$\{x, f(x), f(f(x)), \ldots\}$
Std	$\text{once}$	$a$		$\{a\}$
Std	$\text{repeat}$	$a$		$\{a, a, \ldots\}$
IT	$\text{repeat_call}$	$f: () \rightarrow T$		$\{f(), f(), \ldots\}$
IT	$\text{repeat_n}$	$a$ ,	$n$	$\{\underbrace{a, a, \ldots, a}_{n}\}$
IT	$\text{unfold}$	$s:S$ ,	$f: \text{&mut } S \rightarrow \text{Some}(T) ~\|~ \text{None}$	$\{c_0, \ldots, c_{l-1}\} \text{ wh.} \\~~ \text{Some}(c_0) = f(\text{&mut } s), \\~~ \ldots, \\~~ \text{Some}(c_{l-1}) = f(\text{&mut } s), \\~~ \text{None} = f(\text{&mut } s)$

Sequences

Lib	Method	Input		Output
IT	$\text{batching}$	$\{\underbrace{a_0, \ldots}, \underbrace{a_i,\ldots}, \ldots\}:\{T\}$ ,	$batch : \text{&mut }\{T\} \rightarrow U$	$\{\underbrace{c_0}_{batch(\{a_0, \ldots\})}, \underbrace{c_1}_{batch(\{a_i, \ldots\})}, \ldots\}:\{U\}$
IT	$\text{cartesian_product}$	$\{a_0, a_1, \ldots, a_{n-1}\}$ ,	$\{b_0, b_1, \ldots, b_{m-1}\}$	$\{(a_0, b_0), (a_0, b_1), \ldots, (a_0, b_{m-1}),\\~~ (a_1, b_0), (a_1, b_1), \ldots, (a_1, b_{m-1})\\~~ \ldots,\\~~ (a_{n-1}, b_0), (a_{n-1}, b_1), \ldots, (a_{n-1}, b_{m-1})\}$
Std	$\text{chain}$	$\{a_0, \ldots, a_{n-1}\}$ ,	$\{b_0, \ldots, b_{m-1}\}$	$\{a_0, \ldots, a_{n-1}, b_0, \ldots, b_{m-1}\}$
IT	$\text{chunks}$	$\{a_0, \ldots\}$ ,	$m$	$\{ \{a_0, \ldots, a_{m-1}\}, \{a_m, \ldots, a_{2m-1}\}, \ldots \}$
Std	$\text{cmp}$	$\{a_0, \ldots, a_{i}\}$ ,	$\{b_0, \ldots, b_{i}, b_{i+1}, \underline{\ldots}\}$	$\text{cmp}(a_0, b_0) \text{ then } \ldots \text{ then } \text{cmp}(a_i, b_i) \text{ then } \text{Less}$
		$\{a_0, \ldots, a_{i}\}$ ,	$\{b_0, \ldots, b_{i}\}$	$\text{cmp}(a_0, b_0) \text{ then } \ldots \text{ then } \text{cmp}(a_i, b_i) \text{ then } \text{Equal}$
		$\{a_0, \ldots, a_{i}, a_{i+1}, \underline{\ldots}\}$ ,	$\{b_0, \ldots, b_{i}\}$	$\text{cmp}(a_0, b_0) \text{ then } \ldots \text{ then } \text{cmp}(a_i, b_i) \text{ then } \text{Greater}$
IT	$\text{coalesce}$	$\{a_0, a_1, a_2, \ldots\}$	$f : (T,T) \rightarrow \text{Ok}(T) ~\|~ \text{Err}((T, T))$	$\begin{array}{llcl} & \{x_0, \ldots\} &\text{wh.}& \left\{\begin{array}{l} f(a_0, a_1) = \text{Ok}(x_0), \\ \ldots \end{array}\right. \\ \text{or} & \{a'_0, x_1, \ldots\} &\text{wh.}& \left\{\begin{array}{l} f(a_0, a_1) = \text{Err}((a'_0, a'_1)), \\ f(a'_1, a_2) = \text{Ok}(x_1), \\ \ldots \end{array}\right. \\ \text{or} & \{a'_0, a''_1, \ldots\} &\text{wh.}& \left\{\begin{array}{l} f(a_0, a_1) = \text{Err}((a'_0, a'_1)), \\ f(a'_1, a_2) = \text{Err}(a''_1, a'_2), \\ \ldots \end{array}\right. \end{array}$
Std	$\text{collect}$	$\{a_0, \ldots\}$		$[a_0, \ldots]$
IT	$\text{collect_vec}$	$\{a_0, \ldots\}$		$[a_0, \ldots] : \text{Vec}\langle T\rangle$
Std	$\text{cycle}$	$\{a_0, \ldots, a_{n-1}\}$		$\{a_0, \ldots, a_{n-1}, a_0, \ldots, a_{n-1}, \ldots\}$
IT	$\text{dedup}$	$\{\underbrace{a_0, a_0, \ldots}, \underbrace{a_1, a_1, \ldots}, \ldots\}$		$\{a_0, a_1, \ldots\}$
IT	$\text{dropping}$	$\{\underbrace{a_0, \ldots, a_{i-1}}_{\text{consumed}}, a_i, \ldots\}$	$i \text{ wh. } i \lt n$	$\{a_i, \ldots\}$ (consumes $a_0 \ldots a_{i-1}$ immediately)
IT	$\text{dropping}$	$\{\underbrace{a_0, \ldots, a_{n-1}}_{\text{consumed}}\}$	$i \text{ wh. } i \ge n$	$\{\}$ (consumes $a_0 \ldots a_{n-1}$ immediately)
IT	$\text{dropping_back}$	$\{a_0, \ldots, a_{n-i-1}, \underbrace{a_{n-i}, \ldots, a_{n-1}}_{\text{consumed}}\}$	$i \text{ wh. } i \lt n$	$\{a_0, \ldots, a_{n-i-1}\}$ (consumes $a_{n-i} \ldots a_n$ immediately)
IT	$\text{dropping_back}$	$\{\underbrace{a_0, \ldots, a_{n-1}}_{\text{consumed}}\}$	$i \text{ wh. } i \ge n$	$\{\}$ (consumes $a_0 \ldots a_n$ immediately)
Std	$\text{enumerate}$	$\{a_0, a_1, \ldots\}$		$\{(0, a_0), (1, a_1), \ldots\}$
Std	$\text{eq}$	$\{a_0, \ldots, a_{n-1}\}$ ,	$\{b_0, \ldots, b_{m-1}\}$	$\text{false} \text{ wh. } n \neq m$
Std	$\text{eq}$	$\{a_0, \ldots, a_{n-1}\}$ ,	$\{b_0, \ldots, b_{m-1}\}$	$(a_0 = b_0) \land \ldots \land (a_{n-1} = b_{n-1})$
Std	$\text{filter}$	$\{a_0, a_1, \ldots\}$ ,	$p : \text{&}T \rightarrow \text{bool}$	$\{a_i \text{ for all } i \text{ wh. } p(\text{&}a_i)\}$
Std	$\text{filter_map}$	$\{a_0, a_1, \ldots\}$ ,	$f : T \rightarrow \text{Some}(U) ~\|~ \text{None}$	$\{x_i \text{ for all } i \text { where } f(a_i) = \text{Some}(x_i)\}$
Std	$\text{flat_map}$	$\{a_0, a_1, \ldots\}$ ,	$f : T \rightarrow \{U\}$	$\{\underbrace{x_0, x_1, \ldots}_{x = f(a_0)}, \underbrace{y_0, y_1, \ldots}_{y = f(a_1)}, \ldots\}$
IT	$\text{flatten}$	$\{\{a_0, \ldots\}, \{b_0, \ldots\}, \ldots\}$ ,		$\{a_0, \ldots, b_0, \ldots\}$
Std	$\text{ge}$	$\{a_0, \ldots, a_{n-1}\}$ ,	$\{b_0, \ldots, b_{m-1}\}$	$\text{false} \text{ wh. } n < m$
Std	$\text{ge}$	$\{a_0, \ldots, a_{n-1}\}$ ,	$\{b_0, \ldots, b_{m-1}\}$	$(a_0 \geq b_0) \land \ldots \land (a_{n-1} \geq b_{n-1})$
IT	$\text{group_by}$	$\{\underbrace{a_0, \ldots, a_{i-1}}_{g(a_x) = g_0}, \underbrace{a_i, \ldots, a_{j-1}}_{g(a_y) = g_1 \ne g_0}, \underbrace{a_j, \ldots, a_{k-1}}_{g(a_z) = g_2 \ne g_1}, \ldots\}$ ,	$g : \text{&}T \rightarrow G$	$\{ (g_0, \{a_0, \ldots, a_{i-1}\}),\\~~ (g_1, \{a_i, \ldots, a_{j-1}\}),\\~~ (g_2, \{a_j, \ldots, a_{k-1}\}), \ldots \}$
Std	$\text{gt}$	$\{a_0, \ldots, a_{n-1}\}$ ,	$\{b_0, \ldots, b_{m-1}\}$	$\text{false} \text{ wh. } n < m$
Std	$\text{gt}$	$\{a_0, \ldots, a_{n-1}\}$ ,	$\{b_0, \ldots, b_{m-1}\}$	$(a_0 > b_0) \land \ldots \land (a_{n-1} > b_{n-1})$
IT	$\text{interleave}$	$\{a_0, a_1, \ldots, a_{i-1}, a_i, \ldots\}$ ,	$\{b_0, b_1, \ldots, b_{i-1}\}$	$\{a_0, b_0, a_1, b_1, \ldots, a_{i-1}, b_{i-1}, a_i, \ldots\}$
		$\{a_0, a_1, \ldots, a_{i-1}\}$ ,	$\{b_0, b_1, \ldots, b_{i-1}\}$	$\{a_0, b_0, a_1, b_1, \ldots, a_{i-1}, b_{i-1}\}$
		$\{a_0, a_1, \ldots, a_{i-1}\}$ ,	$\{b_0, b_1, \ldots, b_{i-1}, b_i, \ldots\}$	$\{a_0, b_0, a_1, b_1, \ldots, a_{i-1}, b_{i-1}, b_i, \ldots\}$
IT	$\text{interleave_shortest}$	$\{a_0, a_1, \ldots, a_{i-1}, a_i, \underline{\ldots}\}$ ,	$\{b_0, b_1, \ldots, b_{i-1}\}$	$\{a_0, b_0, a_1, b_1, \ldots, a_{i-1}, b_{i-1}, a_i\}$
IT	$\text{interleave_shortest}$	$\{a_0, a_1, \ldots, a_{i-1}\}$	$\{b_0, b_1, \ldots, b_{i-1}, \underline{b_i, \ldots}\}$	$\{a_0, b_0, a_1, b_1, \ldots, a_{i-1}, b_{i-1}\}$
IT	$\text{intersperse}$	$\{a_0, a_1, \ldots, a_{n-1}\}$	$b$	$\{a_0, b, a_1, b, \ldots, b, a_{n-1}\}$
IT	$\text{kmerge}$	$\{ \{a_0, \ldots\}, \{b_0, \ldots\}, \ldots \} \text{ wh.} \\~~ \text{sorted}(a), \text{ sorted}(b), \ldots$		$\{ c_0, c_1, \ldots \} \text{ wh. } c_0 \le c_1 \le \ldots, \\~~ a \subseteq c, b \subseteq c, \ldots$
IT	$\text{kmerge_by}$	$\{ \{a_0, \ldots\}, \{b_0, \ldots\}, \ldots \} \text{ wh.} \\~~ \text{sorted_by}(a, {}\circ{}), \text{ sorted_by}(b, {}\circ{}), \ldots$ ,	${}\circ{} : (\text{&}T,\text{&}T) \rightarrow \text{bool}$	$\{ c_0, c_1, \ldots \} \text{ wh. } c_0 \circ c_1 \circ \ldots, \\~~ a \subseteq c, b \subseteq c, \ldots$
Std	$\text{map}$	$\{a_0, a_1, \ldots\}$ ,	$f : T \rightarrow U$	$\{f(a_0), f(a_1), \ldots\}$
IT	$\text{map_fn}$	$\{a_0, a_1, \ldots\}$ ,	$f : \text{fn}(T) \rightarrow U$	$\{f(a_0), f(a_1), \ldots\}$
IT	$\text{map_results}$	$\{a_0, \ldots\} : \{\text{Ok}(T) ~\|~ \text{Err}(E)\}$ ,	$f : (T) \rightarrow U$	$\{ a_0.\text{map}(f), \ldots \} : \{\text{Ok}(U) ~\|~ \text{Err}(E)\}$
IT	$\text{merge}$	$\{a_0, a_1, \ldots\} \text{ wh. } a_0 \le a_1 \le \ldots$ ,	$\{b_0, b_1, \ldots\} \text{ wh. } b_0 \le b_1 \le \ldots$	$\{c_0, c_1, \ldots\} \text{ wh. } c_0 \le c_1 \le \ldots, a \subseteq c, b \subseteq c$
IT	$\text{merge_by}$	$\{a_0, a_1, \ldots\} \text{ wh. } a_0 \circ a_1 \circ \ldots$ ,	$\{b_0, b_1, \ldots\} \text{ wh. } b_0 \circ b_1 \circ \ldots$ , ${}\circ{} : (\text{&}T,\text{&}T) \rightarrow \text{Ordering}$	$\{c_0, c_1, \ldots\} \text{ wh. } c_0 \circ c_1 \circ \ldots, a \subseteq c, b \subseteq c$
IT	$\text{pad_using}$	$\{a_0, \ldots, a_{n-1}\}$ ,	$m$ , $~~$ $f : i \rightarrow T$	$\{a_0, \ldots, a_{n-1}\} \text{ wh. } n >= m \\ \{a_0, \ldots, a_{n-1}, f(n), \ldots, f(m-1)\} \text{ otherwise}$
Std	$\text{partial_cmp}$	$\{a_0, \ldots, a_{i}\}$ ,	$\{b_0, \ldots, b_{i}, b_{i+1}, \underline{\ldots}\}$	$\text{pcmp}(a_0, b_0) \text{ then } \ldots \text{ then } \text{pcmp}(a_i, b_i) \text{ then } \text{Less}$
		$\{a_0, \ldots, a_{i}\}$ ,	$\{b_0, \ldots, b_{i}\}$	$\text{pcmp}(a_0, b_0) \text{ then } \ldots \text{ then } \text{pcmp}(a_i, b_i) \text{ then } \text{Equal}$
		$\{a_0, \ldots, a_{i}, a_{i+1}, \underline{\ldots}\}$ ,	$\{b_0, \ldots, b_{i}\}$	$\text{pcmp}(a_0, b_0) \text{ then } \ldots \text{ then } \text{pcmp}(a_i, b_i) \text{ then } \text{Greater}$
Std	$\text{partition}$	$\{a_0, a_1, \ldots\}$ ,	$f: \text{&}T \rightarrow \text{bool}$	$([a_i \text{ for all } i \text{ wh. } f(\text{&}a_i) = \text{true}], \\~~ [a_i \text{ for all } i \text{ wh. } f(\text{&}a_i) = \text{false}])$
IT	$\text{partition_map}$	$\{a_0, a_1, \ldots\}$ ,	$f: T \rightarrow \text{Left}(L) ~\|~ \text{Right}(R)$	$([x_i \text{ for all } i \text{ wh. } f(a_i) = \text{Left}(x_i)], \\~~ [x_i \text{ for all } i \text{ wh. } f(a_i) = \text{Right}(x_i)])$
Std	$\text{rev}$	$\{a_0, a_1, \ldots, a_{n-2}, a_{n-1}\}$		$\{a_{n-1}, a_{n-2}, \ldots, a_1, a_0\}$
Std	$\text{scan}$	$\{a_0, a_1, \ldots\}$ ,	$s : \text{&mut }S$ , $f : (\text{&mut }S, T) \rightarrow \text{Some}(U) ~\|~ \text{None}$	$\{x_i \text{ for all } i \text{ wh. } f(s, a_i) = Some(x_i)\}$
Std	$\text{skip}$	$\{a_0, \ldots, a_{i-1}, a_{i}, \ldots\}$ ,	$i$	$\{a_{i}, \ldots\}$
Std	$\text{skip}$	$\{a_0, \ldots, a_{n-1}\}$ ,	$i \text{ wh. } i \ge n$	$\{\}$
Std	$\text{skip_while}$	$\{a_0, \ldots, a_i, \ldots\}$ ,	$p : \text{&}T \rightarrow \text{bool}$	$\{a_i, \ldots\} \text{ wh. } i \text{ is first wh. } p(\text{&}a_i)$
IT	$\text{sorted}$	$\{a_0, \ldots\}$		$[c_0, \ldots] : \text{Vec}\langle T\rangle \text { wh. } c_0 \leq c_1 \leq \ldots$
IT	$\text{sorted_by}$	$\{a_0, \ldots\}$	${}\circ{} : (\text{&}T,\text{&}T) \rightarrow \text{Ordering}$	$[c_0, \ldots] : \text{Vec}\langle T\rangle \text { wh. } c_0 \circ c_1 \circ \ldots$
IT	$\text{step}$	$\{a_0, \ldots, a_m, \ldots, a_{2m}, \ldots\}$ ,	m	$\{a_0, a_m, a_{2m}, \ldots\}$
Std	$\text{take}$	$\{a_0, \ldots, a_{i-1}, \underline{a_{i}, \ldots}\}$ ,	$i$	$\{a_0, \ldots, a_{i-1}\}$
Std	$\text{take}$	$\{a_0, \ldots, a_{n-1}\}$ ,	$i \text{ wh. } i \ge n$	$\{a_0, \ldots, a_{n-1}\}$
Std	$\text{take_while}$	$\{a_0, \ldots, a_{i-1}, a_i, \underline{\ldots}\}$ ,	$p : \text{&}T \rightarrow \text{bool}$	${a_{0}, \dots, a_{i - 1}} wh. i is first wh. p (& a_{i}) = false$