By the time you walk out of here, you should understand what iterators are good for, how they work internally, and how to create your own!

Iterators are a fairly central concept to Rust. If you're looping over something, you're very likely already using an iterator. If you're transforming collections, you probably 

 using them. If your function returns a lazily evaluated sequence of things, you should consider returning an iterator - especially if that sequence could be lazily evaluated.

We'll take a look at how iterators are implemented, how to iterate over a collection, what sorts of iterators exist in the standard library, usage and common patterns for transforming data, and finally a few examples of useful crates that provide their functionality via powerful iterators.

Skill-wise, you'll ideally have an understanding of

I highly recommend having some sort of environment to run snippets of code in. The simplest thing to use is the 

. If you'd like a local environment, refer to 

Essentially, an iterator is a thing that allows you to traverse some sort of a sequence. Note that since Rust's iterators are lazy, this sequence could be generated on the fly - you could just as well traverse an existing array of finite length or create an iterator that keeps spewing out random numbers infinitely.

In Rust, iterators are typically implemented using the 

 trait. All we need to implement that trait for our custom type is provide an associated type 

 (this is the type of the elements of the sequence, returned by the iterator) and the 

Let's try and implement an iterator over numbers from 1 to 10.

/// An iterator that returns numbers from 1 to 10.
struct OneToTen {
    current: u32,
}

impl OneToTen {
    /// Constructor for OneToTen.
    fn new() -> Self {
        Self {
            current: 0,
        }
    }
}

impl Iterator for OneToTen {
    type Item = u32;
    
    fn next(&mut self) -> Option<Self::Item> {
        None // we'll change this in a second...
    }
}

 method is expected to yield the next element of the sequence. It takes a mutable reference to 

 in case we need to keep track of some state between 

 calls, which is normally the case. We'll soon find it useful.

. If an iterator is finite, it needs to return 

 to indicate it has no more elements to return. Right now, this iterator will immediately finish, not yielding any items. Let's fix this.

impl Iterator for OneToTen {
    type Item = u32;
    
    fn next(&mut self) -> Option<Self::Item> {
        if self.current < 10 {
            self.current += 1;
            return Some(self.current);
        }
        
        None
    }
}

This should be pretty self-explanatory. Every call to 

So we have an iterator. Let's use it. The most basic thing we can do is simply loop over all of its elements:

fn main() {
    for i in OneToTen::new() {
        println!("{}", i);
    }
}

 is what you get when you type something like 

. Instead of writing the above custom iterator, we could have simply done this:

fn main() {
    for i in 1..11 {
        println!("{}", i);
    }
}

Sometimes you'll want to provide the user of your code the ability to iterate over your type, but without that type itself being an iterator. This will be the case with collections. If you implement your own vector type, you probably don't want that type to needlessly hold an extra iteration variable just in case someone wants to iterate over it.

What we want is a way to create an iterator out of the collection. There are three mechanisms you'll typically see.

If we want to iterate over a vector of chars, we could do something like this:

fn main() {
    let v = vec!('a', 'b', 'c');
    
    for c in v.into_iter() {
        println!("{}", c);
    }
}

 call, Rust will call that method implicitly anyway.

fn main() {
    let v = vec!('a', 'b', 'c');
    
    for c in v {
        println!("{}", c);
    }
}

This implicit call is important to keep in mind. Since 

 consumes the data, we cannot use the original vector later.

fn main() {
    let v = vec!('a', 'b', 'c');
    
    for c in v {
        println!("{}", c);
    }
    
    println!("{:?}", v);
    // error: borrow of moved value: `v`
}

One solution would be to explicitly call 

 so that the iterator is borrowing instead. Another is to provide a reference to 

fn main() {
    let v = vec!('a', 'b', 'c');
    
    for c in &v {
        println!("{}", c);
    }
    
    println!("{:?}", v);
}

This way, the compiler can no longer implicitly call 

 since it doesn't get an owned value. It gets an immutable reference, so the best it can do is implicitly call 

Then there's mutability. Following the same pattern, here Rust will implicitly call 

 and give us an iterator that is mutably borrowing.

fn main() {
    let mut v = vec!('a', 'b', 'c');
    
    for c in &mut v {
        *c = 'z';
    }
    
    println!("{:?}", v);
}

If all you could do with iterators was loop over them with the 

 keyword, they wouldn't be all that useful. But there is a plethora of adapters that transform an iterator into another kind of iterator, altering its behavior.

Most adapters you'll work with are in the standard library and exist as 

methods provided for the implementers of the 

. There are some crates out there (such as 

) that provide extra adapters via extensions.

We're going to go through a few useful adapters, but I highly recommend taking a look at the full list in 

We can construct an infinite iterator using 

. It would be a bad idea to iterate over it directly.

fn main() {  
  	// brace for timeout!
    for i in std::iter::repeat(1) {
        println!("{}", i);
    }
}

If we wanted to print only a few 1s, however, we can use the 

fn main() {  
    for i in std::iter::repeat(1).take(5) {
        println!("{}", i);
    }
}

 is also an iterator, but this one finishes after returning a set number of elements.

A very typical feature of functional programming is the ability to 

, that is to apply a function to every element of a sequence.

fn main() {  
    let pairs = [(1, 2), (3, 4), (5, 6)].iter();
    
    /// Provides the sum of a pair.
    fn sum_tuple((x, y): &(u32, u32)) -> u32 {
        x + y
    }
    
    /// Iterate over sums of our pairs.
    for sum in pairs.map(sum_tuple) {
        println!("{}", sum);
    }
}

If we wanted to find only elements that fulfill a certain criterion, we can use the 

fn main() {  
    let numbers = [9, 3, 8, 25].iter();
    
    for num in numbers.filter(|x| **x > 8) {
        println!("{}", num);
    }
}

We know how to turn a collection into an iterator. How do we turn an iterator into a collection? Enter the 

We could try to convert from a vector to an iterator and back.

fn main() {
    // Create a vector and turn it into an iterator.
    let vec_iter = vec!('a', 'b', 'c').into_iter();
    // Collect the elements into a vector again.
    let new_vec = vec_iter.collect();
    
    println!("{:?}", new_vec);
}

error[E0282]: type annotations needed
 --> src/main.rs:5:9
  |
5 |     let new_vec = vec_iter.collect();
  |         ^^^^^^^ consider giving `new_vec` a type

What Rust is telling us here is that it doesn't know what we're trying to collect into. 

 has a generic return type and could give you a number of things: a vector, a linked list, a string, etc. You could even create a custom type that can be collected into.

To let Rust know what concrete type we want 

let new_vec = vec_iter.collect::<Vec<char>>();

We can make this slightly shorter. The compiler should be able to figure out that we want a vector of chars, specifically, and not a vector of integers. When filling out type parameters, we can use an underscore to tell Rust, "Figure this part out yourself!"

In a case like this, you might find it tidier to add a type annotation to the variable declaration instead. The whole thing will then look like this:

fn main() {
    // Create a vector and turn it into an iterator.
    let vec_iter = vec!('a', 'b', 'c').into_iter();
    // Collect the elements into a vector again.
    let new_vec: Vec<_> = vec_iter.collect();
    
    println!("{:?}", new_vec);
}

, we can convert an array of chars into a string.

fn main() {
    let s: String = ['a', 'b', 'c'].iter()
        .collect();
    
    println!("{}", s);
}

We could also collect an iterator of tuples (where the first element needs to be hashable) into a 

use std::collections::HashMap;

fn main() {
    let tuples = vec![("abc", 5), ("def", 11)].into_iter();
    let hash_map: HashMap<_, _> = tuples.collect();
    
    println!("{:?}", hash_map);
}

Things that can be collected into implement the 

 trait. That means this behavior is extendable! Check out the 

 to see which types can be collected into and how to implement new ones.

We now have some idea of how iterators work and some operations we can perform on them. Let's put it together and see some typical use cases.

 structs, which include a customer's name, e-mail address, and how much they owe us.

struct Customer<'e> {
    email: &'e str,
    owed: f64,
}

impl<'e> Customer<'e> {
    fn new(email: &'e str, owed: f64) -> Self {
        Self {
            email,
            owed,
        }
    }
}

Then let's say we have a list of such customers. We're tasked with producing a vector of all debtor e-mails so we can send them a generic reminder.

fn main() {
    let customers = vec![
        Customer::new("andrew@stuff.eu", 0.0),
        Customer::new("brandy@stuff.eu", 4.23),
        Customer::new("chevonne@stuff.eu", 23.33),
    ];
    
    let debtor_emails: Vec<&str>; // Transform the data here!
    println!("{:?}", debtor_emails);
}

How do we do it? The nice, idiomatic way is to get an iterator over 

, apply some adapters that will filter and transform the data, and then collect that back into a vector.

fn main() {
    let customers = vec![
        Customer::new("andrew@stuff.eu", 0.0),
        Customer::new("brandy@stuff.eu", 4.23),
        Customer::new("chevonne@stuff.eu", 23.33),
    ];
    
    let debtor_emails: Vec<&str> = customers.iter()
        .filter(|c| c.owed > 0.0) // only debtors
        .map(|c| c.email) // get the e-mails
        .collect(); // collect into a vector
    println!("{:?}", debtor_emails);
}

 struct as above, and the same vector of customers, we can search the customer data for a specific person. There's no useful method defined directly on the 

    let brandy = customers.iter()
        .find(|c| c.email == "brandy@stuff.eu")
        .unwrap();
    
    println!("{:?}", brandy);

What if we'd like to get the position of an element in the vector? Things get a little trickier, but create an iterator.

 will wrap every element in a tuple of formthe the  

 closure a little to account for the items now being tuples.

we still have to extract the position component of the tuple, which is the 0th one.

    let brandy_pos = customers.iter()
        .enumerate()
        .find(|(_, c)| c.email == "brandy@stuff.eu")
        .unwrap()
        .0;
        
    println!("{}", brandy_pos);

 method that yields an iterator over chunks of that string. All you have to provide is a pattern to split by - commonly a 

For example, you could get all the words of a phrase this way:

fn main() {
    let s = "fe fi fo fum";
    let words = s.split(' ');
  
    for word in words {
        println!("{}", word);
    }
}

And then you could transform them and collect them into a new 

fn main() {
    let s = "fe fi fo fum";
    let new_s: String = s.split(' ')
        .rev()
        .collect();
        
    println!("{}", new_s);
}

These are some examples of third-party libraries providing some functionality via iterators.

This just about exhausts the core concepts and basic usage. Hopefully, you should now be able to not only effectively transform collections, but (with some practice) also identify where providing iterators would make sense in your code.

AUTHOR

Tomasz Kurcz

Rust Iterators: A Guide 

The Rust Map Function - A Gateway to Iterators

This post looks at the Map function in the Rust programming language as one of the basic tools to use and interact with collections and iterators.

Arguably one of the main reasons the Rust language has become so popular is because the entire ecosystem builds upon a consistent experience. From toolchains to documentation and language specifications, almost every aspect of the language adheres to a certain level of consistency. Getting into the Rust mindset allows us, developers, to intuitively discover aspects of the language and gain the ability to write better and more consistent code.

In this article, we are going to focus on Iterators - one of the key language tools enabling us to write idiomatic Rust code. This may surprise you at first, especially if you are coming from other programming languages (for example Swift or JavaScript), where working with types like lists and arrays does not immediately expose the concept of Iterators. The opposite is valid for Rust. Iterators cover a very large number of applications and as such, being comfortable with their use greatly facilitates becoming a better Rust developer.

In order to follow along, you will need at least some familiarity with the Rust programming language. To make things easier, this article includes detailed code samples and links to the Rust playground where you can execute and study the provided code snippets. 

After reading this article, you will know:

A core concept for Functional programming, Map is also commonly used as a tool for dealing with lists and collections in Rust and is one of the most essential methods for working with Iterators.

 method offers a way to apply a function (or a closure) on each element from a list. This is key in functional programming methodologies and offers a way to transform a collection of type A, to a collection of elements of type B. In Rust, the 

 method is frequently used to interact with 

 and any other types which can be represented as an 

Let's illustrate this with an example. Imagine a list of numbers (a vector of numbers) and we would like to multiply each number by 10.

let numbers = vec![3, 6, 9, 12];
let result: Vec<i32> = numbers
    .iter()
    .map(|n| n * 10)
    .collect();
// result is now [30, 60, 90, 120]

 doesn't work directly on the vector of numbers.

The answer lies with the fact Rust makes it very easy to use iterators for almost everything. In the ergonomics of the language, it is generally preferred to use iterators instead of directly interacting with a vector. 

In the example above we actually have two iterators at play - the first which we obtain through the use of 

 in order to get the elements of the vector and a second one which happens to be the return type of the 

This may be a bit surprising at first, especially if you have a background in other programming languages (for example Swift or JavaScript) but indeed, in Rust 

 also returns an iterator. Let's have a closer look at the syntax we need in order to use Map.

, we can find the exact signature of the Map method:

fn map<B, F>(self, f: F) -> Map<Self, F> where F: FnMut(Self::Item) -> B

With this we can focus on several key takeaways.

 can only be applied to iterators. This means that we first need to convert a collection type to an iterator before we can transform its elements.

To obtain an iterator from a vector, the standard library provides 

let str_numbers: Vec<&str> = vec!["1", "2", "3", "4"];
let str_numbers_iterator = str_numbers.iter();

 is also an iterator. This can be very useful in cases when multiple transformations need to be chained one after the other. 

Let's illustrate this by extending the example with a second transformation of the vector of numbers. After multiplying by 10, let's divide each element by 3:

let numbers = vec![3, 6, 9, 12];
let result: Vec<i32> = numbers
    .iter()
    .map(|n| n * 10)
    .map(|n| n / 3)
    .collect();
// result is now [10, 20, 30, 40]

Since the Map function returns an Iterator, the result of the first transformation 

 will be used as input for the second transformation 

You probably notice by now that despite the return type of Map being Iterator, we somehow manage to get back a vector of results. 

 method. It acts as a consumer to the iterator, acquiring all elements and storing them into a vector.

, meaning the execution of the closure provided to Map is delayed until the values produced by the Map iterator are actually requested. To demonstrate this, let's modify the example so that we count the number of times the closure of the map method is invoked:

let numbers = vec![3, 6, 9, 12];
let mut number_of_times = 0;
let result: Vec<i32> = numbers
    .iter()
    .map(|n| {
        number_of_times += 1;
        return n * 10
    })
    .collect();
// result is now [30, 60, 90, 120]
// number_of_times equals 4

 runs, it first increments the counter and then applies the transformation of multiplying the number by 10, similar to what we did in the previous example. As expected, the counter equals 4 because this is the total number of elements on which the map function was applied.

Now let's modify this snippet by not calling 

let numbers = vec![3, 6, 9, 12];
let mut number_of_times = 0;
let result = numbers
    .iter()
    .map(|n| {
        number_of_times += 1;
        return n * 10
    });
// result is now Map { iter: Iter([3, 6, 9, 12]) }
// number_of_times equals 0

 variable, we see that what we get back is the actual Map iterator, the results of which are not materialized yet. We can prove this further by looking at the value of the counter variable which is now 0. This means the function inside the 

 gives us the opportunity to control when the transformation will be executed. You can imagine this can be significant in cases of large data sets where performance is important.

Let's have a look at several examples in which the Map function can be a good solution.

Transform a vector of strings to lowercase 

fn main() {
    let words: Vec<&str> = vec!["Hello", "from", "Rust", "!"];
    println!("Words before map: {:?}", words);
    let lowercased_words: Vec<String> = words // using String as the return type of `to_lowercase`
        .iter()
        .map(|word| word.to_lowercase())
        .collect();
    println!("Words after map: {:?}", lowercased_words);
}

Starting from a vector of string values (or "words"), we can use the Map function in order to get the lowercased equivalent of each word.

As before, we begin by accessing an iterator over the collection words. The 

 method produces an iterator which yields every element (that is, every word) of the collection.

Then we can use Map to define a closure which applies 

 the results into a new vector of String values.

Count the number of times a character occurs in a String

Let's define a string value and use Map in order to determine the number of occurrences of each character within the string.

let text = String::from("hello from rust!");

We expect an output giving the number of times each character is used, similar to the following:

The result looks like a dictionary where every key is a character and the value of that key is the number of occurrences. Let's use the 

fn main() {
    let text = String::from("hello from rust!");
    let result = "abcdefghijklmnopqrstuvwxyz"
        .chars()
        .map(|c| (c, text.matches(c).count()))
        .collect::<std::collections::HashMap<_, _>>();
    println!("{:?}", result);
}

 method in order to obtain an iterator over every letter of the alphabet. Then we count how many times each letter matches the text input. 

For example, how many times "a" appears in "hello from rust!", then how many times "b" appears in "hello from rust!" etc.

Finally, we collect the results from the mapping into a HashMap.

So far we've used examples where the mapping function always succeeds. In reality, we have to take into account the circumstances when this is not going to be the case. Such cases include transformations that have an optional return type like 

Let's illustrate the case of using Map with an operation that can potentially fail. 

For example, converting a vector of string values to a vector of numeric values of type 

. Applying what we've seen so far, we may attempt to solve the problem with the following snippet:

fn main() {
    let str_numbers: Vec<&str> = vec!["1", "2", "3", "I am not a number"];
    let numbers: Vec<u32> = str_numbers
        .iter()
        .map(|str_number| str_number.parse::<u32>())
        .collect();
}

For each element of the vector, we use the 

 method in order to convert the string value to a number. 

We realize quickly that this will not compile. 

The reason lies with the fact that Parse returns a 

 which indicates that the operation can either succeed returning a value of type 

 function is not equipped to deal with this situation directly.

, essentially forcing the fact that we are certain the parsing will never fail. If it does, the program will panic and exit:

fn main() {
    let str_numbers: Vec<&str> = vec!["1", "2", "3"];
    let numbers: Vec<u32> = str_numbers
        .iter()
        .map(|str_number| str_number.parse::<u32>().unwrap())
        .collect();
    print!("{:?}", numbers)
}

This works because all string values in the source vector can be converted to a number.

But what if we have a vector where some elements can't be expressed as a number?

fn main() {
    let str_numbers: Vec<&str> = vec!["1", "2", "3", "I am not a string"];
    let numbers: Vec<u32> = str_numbers
        .iter()
        .map(|str_number| str_number.parse::<u32>().unwrap())
        .collect();
    print!("{:?}", numbers)
}

The unwrap fails and causes the program to panic.

Luckily, the standard library provides an alternative that can handle the situation where the Map function can produce one or zero results. Meet 

fn main() {
    let str_numbers: Vec<&str> = vec!["1", "2", "3", "I am not a number"];
    let numbers: Vec<u32> = str_numbers
        .iter()
        .flat_map(|str_number| str_number.parse::<u32>())
        .collect();
    println!("{:?}", numbers);
	// [1, 2, 3]
}

 uses an iterator over the result of the mapping and as a consequence, it will skip over elements for which the mapping closure returns empty or unsuccessful values (like 

. In other words, we have a mechanism to skip over the failing elements and end up with a resulting vector of numbers for which the operation succeeded.

A note of caution regarding side effects when using the Map function.

Side effects refer to the fact that during the execution of a Map closure or a function, our program may modify state and variables which are external. We already saw an example of this, when we defined a counter which increments every time the Map function is executed:

let numbers = vec![3, 6, 9, 12];
let mut number_of_times = 0; // external state
let result: Vec<i32> = numbers
    .iter()
    .map(|n| {
        number_of_times += 1;
        return n * 10
    })
    .collect();

While this produces exactly the result we expect in this situation, it may not always be the case. Let's modify the example so that instead of transforming the numbers in the vector, we map the order in which they are processed:

let numbers = vec![3, 6, 9, 12];
let mut number_of_times = 0;
let result: Vec<(i32, i32)> = numbers
    .into_iter()
    .map(|n| {
        number_of_times += 1;
        return (n, number_of_times)
    })
    .collect();
println!("{:?}", result);

This results in the Map function to first be applied to the number 3 on position 1, followed by the number 6 on position 2, etc. 

 returns an iterator, we could choose to modify its output. For example, let's reverse the order of the Map operation:

Learn

The newline Guide to Building Your First GraphQL Server with Node and TypeScript

Teach

Amelia Wattenberger

Author of Fullstack D3

Community

Tutorials on Iterators

Rust Iterators: A Guide

The Rust Map Function - A Gateway to Iterators

This has been a really good investment!

Advance your career with newline Pro.

Email Newsletter

Popular Topics

Masterclasses

Tutorials

Fullstack React with TypeScript