Rust Iterator overview
Iterators are a powerful concept in Rust. This website gives an overview and helps you select the best method.
For an introduction, read the chapter in the book. Remember: Iterators (and adapters) are lazy. Creating an iterator does nothing, so you need to consume it to perform the iteration.
Constructors
I want to create an iterator from...
a function
from_fn(next)§
Creates an iterator with the provided closure as its next method.
once(element)§
Creates an iterator that yields an element exactly once.
once_with(make)§
Creates an iterator that lazily generates a value exactly once by invoking the provided closure.
repeat(element)§
Creates a new iterator that endlessly repeats a single element.
repeat_n(element, count)§
Creates a new iterator that repeats a single element a given number of times.
repeat_with(repeater)§
Creates a new iterator that repeats elements endlessly by applying the provided closure.
successors(first, next)§
Creates an iterator which, starting from an initial item, computes each successive item from the preceding one.
an array/slice/collection
iter()§
An iterator that borrows the elements
iter_mut()§
An iterator that mutably borrows the elements
into_iter()§
Moves the array/slice/collection, returning an owned iterator over its elements.
a string
char_indices()§
Returns an iterator over the chars of a string slice, and their positions.
split(pattern)§
Returns an iterator over substrings of this string slice, separated by characters matched by a pattern.
Also see split_whitespace,
split_ascii_whitespace,
split_inclusive,
rsplit, etc.
matches()§
Returns an iterator over the disjoint matches of a pattern within the given string slice.
Also see rmatches,
match_indices,
rmatch_indices
a HashMap/BTreeMap
into_keys()§
Moves the HashMap, returning an iterator over the owned keys in arbitrary order.
into_values()§
Moves the HashMap, returning an iterator over the owned values in arbitrary order.
values_mut()§
An iterator visiting all values mutably in arbitrary order.
CLI arguments
environment variables
a file path
ancestors()§
Produces an iterator over Path and its ancestors.
components()§
Produces an iterator over the Components of the path.
read_dir()§
Returns an iterator over the entries within a directory.
Read/BufRead
TcpListener
incoming()§
Returns an iterator over the connections being received on this listener.
Adapters
Filter Remove items from the iterator
filter(predicate)§
Creates an iterator which uses a closure to determine if an element should be yielded.
See also: filter_map
step_by(step)§
Creates an iterator starting at the same point, but stepping by the given amount at each iteration.
skip_while(predicate)§
Creates an iterator that skips elements based on a predicate.
take(n)§
Creates an iterator that yields the first n elements, or fewer if the underlying iterator ends sooner.
take_while(predicate)§
Creates an iterator that yields elements while the given predicate returns true.
Expand Add items to the iterator
chain(iterator)§
Takes two iterators and creates a new iterator over both in sequence.
Transform Modify the items in the iterator
enumerate()§
Creates an iterator which gives the current iteration count as well as the next value.
map(transform)§
Takes a closure and creates an iterator which calls that closure on each element.
flat_map(transform)§
Creates an iterator that works like map, but flattens nested structure.
See also: map
map_while(transform)§
Creates an iterator that both yields elements based on a predicate and maps.
See also: take_while
scan(init, accumulate)§
An iterator adapter which, like fold, holds internal state, but unlike fold, produces a new iterator.
See also: fold
Misc.
inspect(function)§
Does something with each element of an iterator, passing the value on.
peekable()§
Creates an iterator which can use the peek and peek_mut methods to look at the next element of the iterator without consuming it.
Consumers
Select Pick an item from the iterator
Search Find an item matching a predicate
find(predicate)§
Searches for an element of an iterator that satisfies a predicate.
find_map(transform)§
Applies a function to the elements of the iterator and returns the first non-none result.
See also: map
position(predicate)§
Searches for an element in an iterator, returning its index.
rposition(predicate)§
Searches for an element in an iterator from the right, returning its index.
See also: rev
Validate Check if the iterator meets a certain condition
all(predicate)§
Tests if every element of the iterator matches a predicate.
any(predicate)§
Tests if any element of the iterator matches a predicate.
is_sorted()§
Checks if the elements of this iterator are sorted.
is_sorted_by(compare)§
Checks if the elements of this iterator are sorted using the given comparator function.
is_sorted_by_key(extract_key)§
Checks if the elements of this iterator are sorted using the given key extraction function.
Accumulate Condense the iterator into a single value
fold(init, accumulate)§
Folds every element into an accumulator by applying an operation, returning the final result.
reduce(reducer)§
Reduces the elements to a single one, by repeatedly applying a reducing operation.
See also: try_reduce
collect::<Collection>()§
Transforms an iterator into a collection.
max_by(compare)§
Returns the element that gives the maximum value with respect to the specified comparison function.
max_by_key(extract_key)§
Returns the element that gives the maximum value from the specified key extraction function.
min_by(compare)§
Returns the element that gives the minimum value with respect to the specified comparison function.
min_by_key(extract_key)§
Returns the element that gives the minimum value from the specified key extraction function.
try_fold(predicate)§
An iterator method that applies a function as long as it returns successfully, producing a single, final value.
See also: fold
try_reduce(reducer)§
Reduces the elements to a single one by repeatedly applying a reducing operation. If the closure returns a failure, the failure is propagated back to the caller immediately.
See also: reduce
partition(predicate)§
Consumes an iterator, creating two collections from it.
Compare Lexicographically compare two iterators
cmp(iterable)§
Lexicographically compares the elements of this Iterator with those of another.
partial_cmp(iterable)§
Lexicographically compares the PartialOrd elements of this Iterator with those of another. The comparison works like short-circuit evaluation.
eq(iterable)§
Determines if the elements of this Iterator are equal to those of another.
ne(iterable)§
Determines if the elements of this Iterator are not equal to those of another.
ge(iterable)§
Determines if the elements of this Iterator are lexicographically greater than or equal to those of another.
gt(iterable)§
Determines if the elements of this Iterator are lexicographically greater than those of another.
le(iterable)§
Determines if the elements of this Iterator are lexicographically less or equal to those of another.
lt(iterable)§
Determines if the elements of this Iterator are lexicographically less than those of another.
Misc.
for_each(function)§
Calls a closure on each element of an iterator.
try_for_each(function)§
An iterator method that applies a fallible function to each item in the iterator, stopping at the first error and returning that error.
See also: for_each
Other
size_hint()§
Returns the bounds on the remaining length of the iterator.