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 &mut &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.

{…} { … } is used to represent a lazily computed sequence; i.e. an iterator.

{…}:{T} { … } : { T } indicates an iterator where each element is of type T .

a a and b b are used as input sequences (with subscripted letters denoting individual elements).

c c is used to represent the output sequence in cases where there is no direct mapping of input elements to output elements.

i i , j j , and k k are used to denote specific, but arbitrary, points within sequences.

n n , m m , and l l are used to denote the length of different sequences.

[…] [ … ] 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 f is a function which transforms elements.

p p is a predicate which determines some logical property of elements.

∘ ∘ is an arbitrary binary function.

⟨…⟩ ⟨ … ⟩ is used to indicate a generic type argument contains relevant information.

wh. wh. is an abbreviation for "where".

Generators

Lib Function Input Output Std empty empty { } { } Std once once a a { a } { a } Std repeat repeat a a { a , a , … } { a , a , … }

Sequences

Lib Method Input Output Std chain chain { a 0 , … , a n − 1 } { a 0 , … , a n − 1 } , { b 0 , … , b m − 1 } { b 0 , … , b m − 1 } { a 0 , … , a n − 1 , b 0 , … , b m − 1 } { a 0 , … , a n − 1 , b 0 , … , b m − 1 } Std cmp cmp { a 0 , … , a i } { a 0 , … , a i } , { b 0 , … , b i , b i + 1 , … − − − } { b 0 , … , b i , b i + 1 , … _ } cmp ( a 0 , b 0 ) then … then cmp ( a i , b i ) then Less cmp ( a 0 , b 0 ) then … then cmp ( a i , b i ) then Less { a 0 , … , a i } { a 0 , … , a i } , { b 0 , … , b i } { b 0 , … , b i } cmp ( a 0 , b 0 ) then … then cmp ( a i , b i ) then Equal cmp ( a 0 , b 0 ) then … then cmp ( a i , b i ) then Equal { a 0 , … , a i , a i + 1 , … − − − } { a 0 , … , a i , a i + 1 , … _ } , { b 0 , … , b i } { b 0 , … , b i } cmp ( a 0 , b 0 ) then … then cmp ( a i , b i ) then Greater cmp ( a 0 , b 0 ) then … then cmp ( a i , b i ) then Greater Std collect collect { a 0 , … } { a 0 , … } [ a 0 , … ] [ a 0 , … ] Std cycle cycle { a 0 , … , a n − 1 } { a 0 , … , a n − 1 } { a 0 , … , a n − 1 , a 0 , … , a n − 1 , … } { a 0 , … , a n − 1 , a 0 , … , a n − 1 , … } Std enumerate enumerate { a 0 , a 1 , … } { a 0 , a 1 , … } { ( 0 , a 0 ) , ( 1 , a 1 ) , … } { ( 0 , a 0 ) , ( 1 , a 1 ) , … } Std eq eq { a 0 , … , a n − 1 } { a 0 , … , a n − 1 } , { b 0 , … , b m − 1 } { b 0 , … , b m − 1 } false wh. n ≠ m false wh. n ≠ m ( a 0 = b 0 ) ∧ … ∧ ( a n − 1 = b n − 1 ) ( a 0 = b 0 ) ∧ … ∧ ( a n − 1 = b n − 1 ) Std filter filter { a 0 , a 1 , … } { a 0 , a 1 , … } , p : & T → bool p : & T → bool { a i for all i wh. p ( & a i ) } { a i for all i wh. p ( & a i ) } Std filter_map filter_map { a 0 , a 1 , … } { a 0 , a 1 , … } , f : T → Some ( U ) | None f : T → Some ( U ) | None { x i for all i where f ( a i ) = Some ( x i ) } { x i for all i where f ( a i ) = Some ( x i ) } Std flat_map flat_map { a 0 , a 1 , … } { a 0 , a 1 , … } , f : T → { U } f : T → { U } { x 0 , x 1 , …            x = f ( a 0 ) , y 0 , y 1 , …          y = f ( a 1 ) , … } { x 0 , x 1 , … ⏟ x = f ( a 0 ) , y 0 , y 1 , … ⏟ y = f ( a 1 ) , … } Std ge ge { a 0 , … , a n − 1 } { a 0 , … , a n − 1 } , { b 0 , … , b m − 1 } { b 0 , … , b m − 1 } false wh. n < m false wh. n < m ( a 0 ≥ b 0 ) ∧ … ∧ ( a n − 1 ≥ b n − 1 ) ( a 0 ≥ b 0 ) ∧ … ∧ ( a n − 1 ≥ b n − 1 ) Std gt gt { a 0 , … , a n − 1 } { a 0 , … , a n − 1 } , { b 0 , … , b m − 1 } { b 0 , … , b m − 1 } false wh. n < m false wh. n < m ( a 0 > b 0 ) ∧ … ∧ ( a n − 1 > b n − 1 ) ( a 0 > b 0 ) ∧ … ∧ ( a n − 1 > b n − 1 ) Std map map { a 0 , a 1 , … } { a 0 , a 1 , … } , f : T → U f : T → U { f ( a 0 ) , f ( a 1 ) , … } { f ( a 0 ) , f ( a 1 ) , … } Std partial_cmp partial_cmp { a 0 , … , a i } { a 0 , … , a i } , { b 0 , … , b i , b i + 1 , … − − − } { b 0 , … , b i , b i + 1 , … _ } pcmp ( a 0 , b 0 ) then … then pcmp ( a i , b i ) then Less pcmp ( a 0 , b 0 ) then … then pcmp ( a i , b i ) then Less { a 0 , … , a i } { a 0 , … , a i } , { b 0 , … , b i } { b 0 , … , b i } pcmp ( a 0 , b 0 ) then … then pcmp ( a i , b i ) then Equal pcmp ( a 0 , b 0 ) then … then pcmp ( a i , b i ) then Equal { a 0 , … , a i , a i + 1 , … − − − } { a 0 , … , a i , a i + 1 , … _ } , { b 0 , … , b i } { b 0 , … , b i } pcmp ( a 0 , b 0 ) then … then pcmp ( a i , b i ) then Greater pcmp ( a 0 , b 0 ) then … then pcmp ( a i , b i ) then Greater Std partition partition { a 0 , a 1 , … } { a 0 , a 1 , … } , f : & T → bool f : & T → bool ( [ a i for all i wh. f ( & a i ) = true ] , [ a i for all i wh. f ( & a i ) = false ] ) ( [ a i for all i wh. f ( & a i ) = true ] , [ a i for all i wh. f ( & a i ) = false ] ) Std rev rev { a 0 , a 1 , … , a n − 2 , a n − 1 } { a 0 , a 1 , … , a n − 2 , a n − 1 } { a n − 1 , a n − 2 , … , a 1 , a 0 } { a n − 1 , a n − 2 , … , a 1 , a 0 } Std scan scan { a 0 , a 1 , … } { a 0 , a 1 , … } , s : &mut S s : &mut S , f : ( &mut S , T ) → Some ( U ) | None f : ( &mut S , T ) → Some ( U ) | None { x i for all i wh. f ( s , a i ) = S o m e ( x i ) } { x i for all i wh. f ( s , a i ) = S o m e ( x i ) } Std skip skip { a 0 , … , a i − 1 , a i , … } { a 0 , … , a i − 1 , a i , … } , i i { a i , … } { a i , … } { a 0 , … , a n − 1 } { a 0 , … , a n − 1 } , i wh. i ≥ n i wh. i ≥ n { } { } Std skip_while skip_while { a 0 , … , a i , … } { a 0 , … , a i , … } , p : & T → bool p : & T → bool { a i , … } wh. i is first wh. p ( & a i ) { a i , … } wh. i is first wh. p ( & a i ) Std take take { a 0 , … , a i − 1 , a i , … − − − − − } { a 0 , … , a i − 1 , a i , … _ } , i i { a 0 , … , a i − 1 } { a 0 , … , a i − 1 } { a 0 , … , a n − 1 } { a 0 , … , a n − 1 } , i wh. i ≥ n i wh. i ≥ n { a 0 , … , a n − 1 } { a 0 , … , a n − 1 } Std take_while take_while { a 0 , … , a i − 1 , a i , … − − − } { a 0 , … , a i − 1 , a i , … _ } , p : & T → bool p : & T → bool { a 0 , … , a i − 1 } wh. i is first wh. p ( & a i ) = false { a 0 , … , a i − 1 } wh. i is first wh. p ( & a i ) = false Std unzip unzip { ( a 0 , b 0 ) , ( a 1 , b 1 ) , … } { ( a 0 , b 0 ) , ( a 1 , b 1 ) , … } ( [ a 0 , a 1 , … ] , [ b 0 , b 1 , … ] ) ( [ a 0 , a 1 , … ] , [ b 0 , b 1 , … ] ) Std zip zip { a 0 , … , a i } { a 0 , … , a i } , { b 0 , … , b i , b i + 1 , … − − − − − − } { b 0 , … , b i , b i + 1 , … _ } { ( a 0 , b 0 ) , … , ( a i , b i ) } { ( a 0 , b 0 ) , … , ( a i , b i ) } { a 0 , … , a i , a i + 1 , … − − − } { a 0 , … , a i , a i + 1 , … _ } , { b 0 , … , b i } { b 0 , … , b i }

Free-Standing Sequences

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

Lib Function Input Output

Values

Lib Method Input Output Std all all &mut { a 0 , … , a i − 1 , a i , … − − − } &mut { a 0 , … , a i − 1 , a i , … _ } p : T → bool p : T → bool p ( a 0 ) ∧ … ∧ p ( a i − 1 ) wh. i is first wh. p ( a i ) = false p ( a 0 ) ∧ … ∧ p ( a i − 1 ) wh. i is first wh. p ( a i ) = false &mut { } &mut { } true true Std all_equal all_equal &mut { a 0 , … , a i − 1 , a i , … − − − } &mut { a 0 , … , a i − 1 , a i , … _ } ( a 0 = a 1 ) ∧ … ∧ ( a i − 1 = a i ) wh. i is first wh. a i − 1 ≠ a i ( a 0 = a 1 ) ∧ … ∧ ( a i − 1 = a i ) wh. i is first wh. a i − 1 ≠ a i &mut { a 0 } &mut { a 0 } true true &mut { } &mut { } true true Std any any &mut { a 0 , … , a i − 1 , a i , … − − − } &mut { a 0 , … , a i − 1 , a i , … _ } p : T → bool p : T → bool p ( a 0 ) ∨ … ∨ p ( a i − 1 ) wh. i is first wh. p ( a i ) p ( a 0 ) ∨ … ∨ p ( a i − 1 ) wh. i is first wh. p ( a i ) &mut { } &mut { } false false Std count count { …    n } { … ⏟ n } n n Std find find &mut { a 0 , … , a i , … − − − } &mut { a 0 , … , a i , … _ } , p : T → bool p : T → bool Some ( a i ) None wh. i is first wh. p ( & a i ) otherwise Some ( a i ) wh. i is first wh. p ( & a i ) None otherwise Std fold fold { a 0 , a 1 , … } { a 0 , a 1 , … } , i n i t : U i n i t : U , ∘ : ( U , T ) → U ∘ : ( U , T ) → U ( ( ( i n i t ∘ a 0 ) ∘ a 1 ) ∘ … ) ( ( ( i n i t ∘ a 0 ) ∘ a 1 ) ∘ … ) { } { } i n i t i n i t Std last last { … , a n − 1 } { … , a n − 1 } Some ( a n − 1 ) Some ( a n − 1 ) { } { } None None Std le le { a 0 , … , a n − 1 } { a 0 , … , a n − 1 } , { b 0 , … , b m − 1 } { b 0 , … , b m − 1 } false wh. n > m false wh. n > m ( a 0 ≤ b 0 ) ∧ … ∧ ( a n − 1 ≤ b n − 1 ) ( a 0 ≤ b 0 ) ∧ … ∧ ( a n − 1 ≤ b n − 1 ) Std lt lt { a 0 , … , a n − 1 } { a 0 , … , a n − 1 } , { b 0 , … , b m − 1 } { b 0 , … , b m − 1 } false wh. n > m false wh. n > m ( a 0 < b 0 ) ∧ … ∧ ( a n − 1 < b n − 1 ) ( a 0 < b 0 ) ∧ … ∧ ( a n − 1 < b n − 1 ) Std max max { a 0 , a 1 , a 2 , … } { a 0 , a 1 , a 2 , … } Some ( m a x ( m a x ( m a x ( a 0 , a 1 ) , a 2 ) , … ) ) Some ( m a x ( m a x ( m a x ( a 0 , a 1 ) , a 2 ) , … ) ) { a 0 } { a 0 } Some ( a 0 ) Some ( a 0 ) { } { } None None Std max_by max_by { a 0 , … } { a 0 , … } ∘ : ( & T , & T ) → Ordering ∘ : ( & T , & T ) → Ordering Some ( a j ) wh. … ∘ a i ∘ a j Some ( a j ) wh. … ∘ a i ∘ a j { a 0 } { a 0 } Some ( a 0 ) Some ( a 0 ) { } { } None None Std max_by_key max_by_key { a 0 , … } { a 0 , … } f : & T → B f : & T → B Some ( a i ) wh. b = m a x ( { f ( a 0 ) , … } ) , i is the last wh. f ( a i ) = b Some ( a i ) wh. b = m a x ( { f ( a 0 ) , … } ) , i is the last wh. f ( a i ) = b { a 0 } { a 0 } Some ( a 0 ) Some ( a 0 ) { } { } None None Std min min { a 0 , a 1 , a 2 , … } { a 0 , a 1 , a 2 , … } Some ( m i n ( m i n ( m i n ( a 0 , a 1 ) , a 2 ) , … ) ) Some ( m i n ( m i n ( m i n ( a 0 , a 1 ) , a 2 ) , … ) ) { a 0 } { a 0 } Some ( a 0 ) Some ( a 0 ) { } { } None None Std min_by min_by { a 0 , … } { a 0 , … } ∘ : ( & T , & T ) → Ordering ∘ : ( & T , & T ) → Ordering Some ( a i ) wh. a i ∘ a j ∘ … Some ( a i ) wh. a i ∘ a j ∘ … { a 0 } { a 0 } Some ( a 0 ) Some ( a 0 ) { } { } None None Std min_by_key min_by_key { a 0 , … } { a 0 , … } f : & T → B f : & T → B Some ( a i ) wh. b = m i n ( { f ( a 0 ) , … } ) , i is the last wh. f ( a i ) = b Some ( a i ) wh. b = m i n ( { f ( a 0 ) , … } ) , i is the last wh. f ( a i ) = b { a 0 } { a 0 } Some ( a 0 ) Some ( a 0 ) { } { } None None Std ne ne { a 0 , … , a n − 1 } { a 0 , … , a n − 1 } , { b 0 , … , b m − 1 } { b 0 , … , b m − 1 } , true wh. n ≠ m true wh. n ≠ m ( a 0 ≠ b 0 ) ∧ … ∧ ( a n − 1 ≠ b n − 1 ) ( a 0 ≠ b 0 ) ∧ … ∧ ( a n − 1 ≠ b n − 1 ) Std nth nth &mut { …    i − 1 , a i , … − − − } &mut { … ⏟ i − 1 , a i , … _ } , i i Some ( a i ) Some ( a i ) &mut { …    < i } &mut { … ⏟ < i } , i i None None Std position position &mut { a 0 , … , a i , … − − − } &mut { a 0 , … , a i , … _ } , p : T → bool p : T → bool Some ( i ) None wh. i is first wh. p ( & a i ) otherwise Some ( i ) wh. i is first wh. p ( & a i ) None otherwise Std product product { a 0 , a 1 , … } { a 0 , a 1 , … } ( ( a 0 × a 1 ) × … ) ( ( a 0 × a 1 ) × … ) { a 0 } { a 0 } a 0 a 0 { } { } 1 1 Std rposition rposition &mut { a 0 , … − − − − − , a i , … } &mut { a 0 , … _ , a i , … } , p : T → bool p : T → bool Some ( i ) None wh. i is last wh. p ( & a i ) otherwise Some ( i ) wh. i is last wh. p ( & a i ) None otherwise Std sum sum { a 0 , a 1 , … } { a 0 , a 1 , … } ( ( a 0 + a 1 ) + … ) ( ( a 0 + a 1 ) + … ) { a 0 } { a 0 } a 0 a 0 { } { } 0 0

Other

Lib Method Description Std by_ref 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 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 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> . Std fuse fuse Guarantees that once the input returns None None , it will always return None None . Std inspect inspect Calls a closure for each element in a sequence, without modifying the sequence in any way. Std peekable peekable Allows you to preview (peek at) the next item in the sequence without removing it.

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.