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,,ai</