Rust Iterator Cheat Sheet

Last updated: Rust 1.17.0, Itertools 0.6.0.

To-do:

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:

Additional filtering options:

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

  1. You know what an iterator method is called, but you want a quick summary of what it does.
  2. You know what you want to do with an iterator, but not what it's called.
  3. 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:

Generators

Lib Function Input Output
Std empty {}
IT iterate x:T f:&TT {x,f(x),f(f(x)),}
Std once a {a}
Std repeat a {a,a,}
IT repeat_call f:()T {f(),f(),}
IT repeat_n a, n {a,a,,an}
IT unfold s:S, f:&mut SSome(T) | None {c0,,cl1} wh.  Some(c0)=f(&mut s),  ,  Some(cl1)=f(&mut s),  None=f(&mut s)

Sequences

Lib Method Input Output
IT batching {a0,,ai,,}:{T}, batch:&mut {T}U {c0batch({a0,}),c1batch({ai,}),}:{U}
IT cartesian_product {a0,a1,,an1}, {b0,b1,,bm1} {(a0,b0),(a0,b1),,(a0,bm1),  (a1,b0),(a1,b1),,(a1,bm1)  ,  (an1,b0),(an1,b1),,(an1,bm1)}
Std chain {a0,,an1}, {b0,,bm1} {a0,,an1,b0,,bm1}
IT chunks {a0,}, m {{a0,,am1},{am,,a2m1},}
Std cmp {a0,,ai}, {b0,,bi,bi+1,_} cmp(a0,b0) then  then cmp(ai,bi) then Less
{a0,,ai}, {b0,,bi} cmp(a0,b0) then  then cmp(ai,bi) then Equal
{a0,,ai,ai+1,_}, {b0,,bi} cmp(a0,b0) then  then cmp(ai,bi) then Greater
IT coalesce {a0,a1,a2,} f:(T,T)Ok(T) | Err((T,T)) {x0,}wh.{f(a0,a1)=Ok(x0),or{a0,x1,}wh.{f(a0,a1)=Err((a0,a1)),f(a1,a2)=Ok(x1),or{a0,a1,}wh.{f(a0,a1)=Err((a0,a1)),f(a1,a2)=Err(a1,a2),
Std collect {a0,} [a0,]
IT collect_vec {a0,} [a0,]:VecT
Std cycle {a0,,an1} {a0,,an1,a0,,an1,}
IT dedup {a0,a0,,a1,a1,,} {a0,a1,}
IT dropping {a0,,ai1consumed,ai,} i wh. i<n {ai,} (consumes a0ai1 immediately)
{a0,,an1consumed} i wh. in {} (consumes a0an1 immediately)
IT dropping_back {a0,,ani1,ani,,an1consumed} i wh. i<n {a0,,ani1} (consumes anian immediately)
{a0,,an1consumed} i wh. in {} (consumes a0an immediately)
Std enumerate {a0,a1,} {(0,a0),(1,a1),}
Std eq {a0,,an1}, {b0,,bm1} false wh. nm
(a0=b0)(an1=bn1)
Std filter {a0,a1,}, p:&Tbool {ai for all i wh. p(&ai)}
Std filter_map {a0,a1,}, f:TSome(U) | None {xi for all i where f(ai)=Some(xi)}
Std flat_map {a0,a1,}, f:T{U} {x0,x1,x=f(a0),y0,y1,y=f(a1),}
IT flatten {{a0,},{b0,},}, {a0,,b0,}
Std ge {a0,,an1}, {b0,,bm1} false wh. n<m
(a0b0)(an1bn1)
IT group_by {a0,,ai1g(ax)=g0,ai,,aj1g(ay)=g1g0,aj,,ak1g(az)=g2g1,}, g:&TG {(g0,{a0,,ai1}),  (g1,{ai,,aj1}),  (g2,{aj,,ak1}),}
Std gt {a0,,an1}, {b0,,bm1} false wh. n<m
(a0>b0)(an1>bn1)
IT interleave {a0,a1,,ai1,ai,}, {b0,b1,,bi1} {a0,b0,a1,b1,,ai1,bi1,ai,}
{a0,a1,,ai1}, {b0,b1,,bi1} {a0,b0,a1,b1,,ai1,bi1}
{a0,a1,,ai1}, {b0,b1,,bi1,bi,} {a0,b0,a1,b1,,ai1,bi1,bi,}
IT interleave_shortest {a0,a1,,ai1,ai,_}, {b0,b1,,bi1} {a0,b0,a1,b1,,ai1,bi1,ai}
{a0,a1,,ai1} {b0,b1,,bi1,bi,_} {a0,b0,a1,b1,,ai1,bi1}
IT intersperse {a0,a1,,an1} b {a0,b,a1,b,,b,an1}
IT kmerge {{a0,},{b0,},} wh.  sorted(a), sorted(b), {c0,c1,} wh. c0c1,  ac,bc,
IT kmerge_by {{a0,},{b0,},} wh.  sorted_by(a,), sorted_by(b,),, :(&T,&T)bool {c0,c1,} wh. c0c1,  ac,bc,
Std map {a0,a1,}, f:TU {f(a0),f(a1),}
IT map_fn {a0,a1,}, f:fn(T)U {f(a0),f(a1),}
IT map_results {a0,}:{Ok(T) | Err(E)}, f:(T)U {a0.map(f),}:{Ok(U) | Err(E)}
IT merge {a0,a1,} wh. a0a1, {b0,b1,} wh. b0b1 {c0,c1,} wh. c0c1,ac,bc
IT merge_by {a0,a1,} wh. a0a1, {b0,b1,} wh. b0b1, :(&T,&T)Ordering {c0,c1,} wh. c0c1,ac,bc
IT pad_using {a0,,an1}, m,    f:iT {a0,,an1} wh. n>=m{a0,,an1,f(n),,f(m1)} otherwise
Std partial_cmp {a0,,ai}, {b0,,bi,bi+1,_} pcmp(a0,b0) then  then pcmp(ai,bi) then Less
{a0,,ai}, {b0,,bi} pcmp(a0,b0) then  then pcmp(ai,bi) then Equal
{a0,,ai,ai+1,_}, {b0,,bi} pcmp(a0,b0) then  then pcmp(ai,bi) then Greater
Std partition {a0,a1,}, f:&Tbool ([ai for all i wh. f(&ai)=true],  [ai for all i wh. f(&ai)=false])
IT partition_map {a0,a1,}, f:TLeft(L) | Right(R) ([xi for all i wh. f(ai)=Left(xi)],  [xi for all i wh. f(ai)=Right(xi)])
Std rev {a0,a1,,an2,an1} {an1,an2,,a1,a0}
Std scan {a0,a1,}, s:&mut S, f:(&mut S,T)Some(U) | None {xi for all i wh. f(s,ai)=Some(xi)}
Std skip {a0,,ai1,ai,}, i {ai,}
{a0,,an1}, i wh. in {}
Std skip_while {a0,,ai,}, p:&Tbool {ai,} wh. i is first wh. p(&ai)
IT sorted {a0,} [c0,]:VecT wh. c0c1
IT sorted_by {a0,} :(&T,&T)Ordering [c0,]:VecT wh. c0c1
IT step {a0,,am,,a2m,}, m {a0,am,a2m,}
Std take {a0,,ai1,ai,_}, i {a0,,ai1}
{a0,,an1}, i wh. in {a0,,an1}
Std take_while {a0,,ai1,ai,_}, p:&Tbool {a0,,ai1} wh. i is first wh. p(&ai)=false
IT take_while_ref &mut {a0,,ai1,ai,_}, p:&Tbool {a0,,ai1} wh. i is first wh. p(&ai)=false
IT tee {a0,a1,} ({a0,a1,},{a0,a1,})
IT tuple_windows {a0,} (_,_,n) {(a0,,an1),(a1,,an),}
IT tuples {a0,} (_,_,n) {(a0,,an1),(an,,a2n1),}
IT unique {a0,} {ai for all i wh. ai{a0,,ai1}}
IT unique_by {a0,}, f:&TU {ai for all i wh. f(ai){f(a0),,f(ai1)}}
Std unzip {(a0,b0),(a1,b1),} ([a0,a1,],[b0,b1,])
IT while_some {a0,,ai1,ai,_}, {xj for all j<i wh. aj=Some(xj)} wh. i is the first wh. ai=None
IT with_position {a0} {Only(a0)}
{a0,a1,,an2,an1} {First(a0),Middle(a1),,  Middle(an2),Last(an1)}
Std zip {a0,,ai}, {b0,,bi,bi+1,_} {(a0,b0),,(ai,bi)}
{a0,,ai,ai+1,_}, {b0,,bi}
IT zip_eq {a0,,an1}, {b0,,bm1} {(a0,b0),,(an1,bn1)},  panic wh. nm
IT zip_longest {a0,,ai1,ai,}, {b0,,bi1} {Both(a0,b0),,Both(ai1,bi1),Left(ai),}
{a0,,ai1}, {b0,,bi1} {Both(a0,b0),,Both(ai1,bi1)}
{a0,,ai1}, {b0,,bi1,bi,} {Both(a0,b0),,Both(ai1,bi1),Right(bi),}

Free-Standing Sequences

Note: these adaptors are only available as free-standing functions, not as methods on Iterators.

Lib Function Input Output
IT cons_tuples {((a00,a01,),a0n),((a10,a11,),a1n),} {(a00,a01,,a0n),(a10,a11,,a1n),}
IT iproduct!
{a0,a1,},
{b0,b1,},
{(a0,b0,),,(a0,b1,),,  (a1,b0,),,(a1,b1,),}
IT izip!
{a0,a1,},
{b0,b1,},
{(a0,b0,),(a1,b1,),}

Values

Lib Method Input Output
Std all &mut {a0,,ai1,ai,_} p:Tbool p(a0)p(ai1) wh. i is first wh. p(ai)=false
&mut {} true
Std all_equal &mut {a0,,ai1,ai,_} (a0=a1)(ai1=ai) wh. i is first wh. ai1ai
&mut {a0} true
&mut {} true
Std any &mut {a0,,ai1,ai,_} p:Tbool p(a0)p(ai1) wh. i is first wh. p(ai)
&mut {} false
Std count {n} n
Std find &mut {a0,,ai,_}, p:Tbool Some(ai)wh. i is first wh. p(&ai)Noneotherwise
IT find_position &mut {a0,,ai,_}, p:Tbool Some((i,ai))wh. i is first wh. p(&ai)Noneotherwise
Std fold {a0,a1,}, init:U, :(U,T)U (((inita0)a1))
{} init
IT fold1 {a0,a1,a2,}, :(T,T)T Some(((a0a1)a2))
{a0} Some(a0)
{} None
IT fold_options &mut {a0,}, start:U, :(U,T)U Some(fold(x,)) wh. x={xi wh. all ai=Some(xi)}
&mut {,ai,_} wh. ai=None, None wh. i is first wh. ai=None
&mut {} Some(start)
IT fold_results &mut {a0,}, start:U, :(U,T)U Ok(fold(x,)) wh. x={xi wh. all ai=Ok(xi)}
&mut {,ai,_} wh. ai=Err(..), Err(e) wh. i is first wh. ai=Err(e)
&mut {} Ok(start)
IT fold_while {a0,,an1}, init:U, :(U,T)Continue(U) | Done(U), ((initx0))xn1 wh. aj=Continue(xj)
{a0,,aj,_}, ((initx0))xi wh.   ai=Done(xi),  aj=Continue(xj) for all j<i
{} init
IT join {a0,a1,,an1}, sep:&str d(a0)sepd(a1)sepd(an1) wh.  d is Display::fmt,  is string concatenation
Std last {,an1} Some(an1)
{} None
Std le {a0,,an1}, {b0,,bm1} false wh. n>m
(a0b0)(an1bn1)
Std lt {a0,,an1}, {b0,,bm1} false wh. n>m
(a0<b0)(an1<bn1)
Std max {a0,a1,a2,} Some(max(max(max(a0,a1),a2),))
{a0} Some(a0)
{} None
Std max_by {a0,} :(&T,&T)Ordering Some(aj) wh. aiaj
{a0} Some(a0)
{} None
Std max_by_key {a0,} f:&TB Some(ai) wh.  b=max({f(a0),}),i is the last wh. f(ai)=b
{a0} Some(a0)
{} None
Std min {a0,a1,a2,} Some(min(min(min(a0,a1),a2),))
{a0} Some(a0)
{} None
IT minmax {} NoElements
{a0} OneElement(a0)
{a0,} MinMax(min(a),max(a))
IT minmax_by {}, :(&T,&T)Ordering NoElements
{a0} OneElement(a0)
{a0,} MinMax(min_by(a,),max_by(a,))
IT minmax_by_key {}, f:&TK NoElements
{a0} OneElement(a0)
{a0,} MinMax(min_by_key(a,f),max_by_key(a,f))
Std min_by {a0,} :(&T,&T)Ordering Some(ai) wh. aiaj
{a0} Some(a0)
{} None
Std min_by_key {a0,} f:&TB Some(ai) wh.  b=min({f(a0),}),i is the last wh. f(ai)=b
{a0} Some(a0)
{} None
Std ne {a0,,an1}, {b0,,bm1}, true wh. nm
(a0b0)(an1bn1)
IT next_tuple &mut {a0,,an1} (_,_,m) None wh. n<m
&mut {a0,,am1,am,_} Some((a0,,am1))
Std nth &mut {i1,ai,_}, i Some(ai)
&mut {<i}, i None
Std position &mut {a0,,ai,_}, p:Tbool Some(i)wh. i is first wh. p(&ai)Noneotherwise
Std product {a0,a1,} ((a0×a1)×)
{a0} a0
{} 1
Std rposition &mut {a0,_,ai,}, p:Tbool Some(i)wh. i is last wh. p(&ai)Noneotherwise
IT set_from &mut {a0,,ai1,ai,_}:{&mut T} {b0,,bi1}:{T} i, with side effect: aj=bj
&mut {a0,,ai1}:{&mut T} {b0,,bi1}:{T}
&mut {a0,,ai1}:{&mut T} {b0,,bi1,bi,_}:{T}
Std sum {a0,a1,} ((a0+a1)+)
{a0} a0
{} 0

Other

Lib Method Description
IT assert_equal Ensures the items in two iterators match exactly, panicking with a descriptive message on how and where they differ.
Std by_ref Lets you act on a sequence by reference; i.e. calls that would normally consume the iterator will no longer do so. Note that this can have slightly unintuitive effects depending on what iterator methods are used on the result. e.g. take_while must necessarily consume one more element than is returned in order to detect the termination condition; this element is consumed and does not remain in the underlying sequence.
Std cloned Returns an iterator which calls Clone::clone on each element of the input. This is commonly used to turn an Iterator<Item=&T> into an Iterator<Item=T>.
IT combinations Returns all in-order, unique combinations of length n without replacement. Each combination is a Vec of length n.
IT diff_with Determines where and how two iterators differ.
IT foreach Eagerly executes a closure f on each element of the sequence.
IT format Returns a thunk which formats each item in the iterator, separated by sep.
IT format_with Like format, except that it also accepts a callable used to customise the formatting for each item.
Std fuse Guarantees that once the input returns None, it will always return None.
Std inspect Calls a closure for each element in a sequence, without modifying the sequence in any way.
IT multipeek Allows you to preview (peek at) an unbounded number of future items in the sequence without removing them.
IT multizip Generalises zip for up to 8 iterators.
Std peekable Allows you to preview (peek at) the next item in the sequence without removing it.
IT peeking_take_while Like take_while_ref, but works on peekable iterators rather than cloneable ones.
IT put_back Creates an iterator where you can "put back" one item.
IT put_back_n Creates an iterator where you can "put back" an arbitrary number of items.
IT rciter Wraps an iterator such that it can be iterated by multiple handles.
IT tuple_combinations Returns all in-order, unique combinations of length n without replacement. Each combination is a tuple of length n.

Notes

Q: Who is the audience for this?

Definitely not absolute beginners!

The problem is that beginner-friendly descriptions of the available iterator methods are long and wordy, which makes them difficult to quickly scan through. Summarising them requires notation, and there are enough different kinds of behaviours that the notation needs to be relatively extensive.

I've tried to keep the notation used as simple as possible, but that can only go so far. My primary concern with this is creating a summary that can be skimmed relatively quickly, not to make iterators accessible to beginners.

This work is licensed under the Creative Commons Attribution-ShareAlike 4.0 International License.