3 Let's talk about loops.
5 Remember Rust's `for` loop? Here's an example:
13 Now that you know more Rust, we can talk in detail about how this works.
14 Ranges (the `0..10`) are 'iterators'. An iterator is something that we can
15 call the `.next()` method on repeatedly, and it gives us a sequence of things.
20 let mut range = 0..10;
32 We make a mutable binding to the range, which is our iterator. We then `loop`,
33 with an inner `match`. This `match` is used on the result of `range.next()`,
34 which gives us a reference to the next value of the iterator. `next` returns an
35 `Option<i32>`, in this case, which will be `Some(i32)` when we have a value and
36 `None` once we run out. If we get `Some(i32)`, we print it out, and if we get
37 `None`, we `break` out of the loop.
39 This code sample is basically the same as our `for` loop version. The `for`
40 loop is just a handy way to write this `loop`/`match`/`break` construct.
42 `for` loops aren't the only thing that uses iterators, however. Writing your
43 own iterator involves implementing the `Iterator` trait. While doing that is
44 outside of the scope of this guide, Rust provides a number of useful iterators
45 to accomplish various tasks. But first, a few notes about limitations of ranges.
47 Ranges are very primitive, and we often can use better alternatives. Consider the
48 following Rust anti-pattern: using ranges to emulate a C-style `for` loop. Let’s
49 suppose you needed to iterate over the contents of a vector. You may be tempted
53 let nums = vec![1, 2, 3];
55 for i in 0..nums.len() {
56 println!("{}", nums[i]);
60 This is strictly worse than using an actual iterator. You can iterate over vectors
61 directly, so write this:
64 let nums = vec![1, 2, 3];
71 There are two reasons for this. First, this more directly expresses what we
72 mean. We iterate through the entire vector, rather than iterating through
73 indexes, and then indexing the vector. Second, this version is more efficient:
74 the first version will have extra bounds checking because it used indexing,
75 `nums[i]`. But since we yield a reference to each element of the vector in turn
76 with the iterator, there's no bounds checking in the second example. This is
77 very common with iterators: we can ignore unnecessary bounds checks, but still
80 There's another detail here that's not 100% clear because of how `println!`
81 works. `num` is actually of type `&i32`. That is, it's a reference to an `i32`,
82 not an `i32` itself. `println!` handles the dereferencing for us, so we don't
83 see it. This code works fine too:
86 let nums = vec![1, 2, 3];
93 Now we're explicitly dereferencing `num`. Why does `&nums` give us
94 references? Firstly, because we explicitly asked it to with
95 `&`. Secondly, if it gave us the data itself, we would have to be its
96 owner, which would involve making a copy of the data and giving us the
97 copy. With references, we're just borrowing a reference to the data,
98 and so it's just passing a reference, without needing to do the move.
100 So, now that we've established that ranges are often not what you want, let's
101 talk about what you do want instead.
103 There are three broad classes of things that are relevant here: iterators,
104 *iterator adaptors*, and *consumers*. Here's some definitions:
106 * *iterators* give you a sequence of values.
107 * *iterator adaptors* operate on an iterator, producing a new iterator with a
108 different output sequence.
109 * *consumers* operate on an iterator, producing some final set of values.
111 Let's talk about consumers first, since you've already seen an iterator, ranges.
115 A *consumer* operates on an iterator, returning some kind of value or values.
116 The most common consumer is `collect()`. This code doesn't quite compile,
117 but it shows the intention:
120 let one_to_one_hundred = (1..101).collect();
123 As you can see, we call `collect()` on our iterator. `collect()` takes
124 as many values as the iterator will give it, and returns a collection
125 of the results. So why won't this compile? Rust can't determine what
126 type of things you want to collect, and so you need to let it know.
127 Here's the version that does compile:
130 let one_to_one_hundred = (1..101).collect::<Vec<i32>>();
133 If you remember, the `::<>` syntax allows us to give a type hint,
134 and so we tell it that we want a vector of integers. You don't always
135 need to use the whole type, though. Using a `_` will let you provide
139 let one_to_one_hundred = (1..101).collect::<Vec<_>>();
142 This says "Collect into a `Vec<T>`, please, but infer what the `T` is for me."
143 `_` is sometimes called a "type placeholder" for this reason.
145 `collect()` is the most common consumer, but there are others too. `find()`
149 let greater_than_forty_two = (0..100)
152 match greater_than_forty_two {
153 Some(_) => println!("Found a match!"),
154 None => println!("No match found :("),
158 `find` takes a closure, and works on a reference to each element of an
159 iterator. This closure returns `true` if the element is the element we're
160 looking for, and `false` otherwise. `find` returns the first element satisfying
161 the specified predicate. Because we might not find a matching element, `find`
162 returns an `Option` rather than the element itself.
164 Another important consumer is `fold`. Here's what it looks like:
167 let sum = (1..4).fold(0, |sum, x| sum + x);
170 `fold()` is a consumer that looks like this:
171 `fold(base, |accumulator, element| ...)`. It takes two arguments: the first
172 is an element called the *base*. The second is a closure that itself takes two
173 arguments: the first is called the *accumulator*, and the second is an
174 *element*. Upon each iteration, the closure is called, and the result is the
175 value of the accumulator on the next iteration. On the first iteration, the
176 base is the value of the accumulator.
178 Okay, that's a bit confusing. Let's examine the values of all of these things
181 | base | accumulator | element | closure result |
182 |------|-------------|---------|----------------|
187 We called `fold()` with these arguments:
191 .fold(0, |sum, x| sum + x);
194 So, `0` is our base, `sum` is our accumulator, and `x` is our element. On the
195 first iteration, we set `sum` to `0`, and `x` is the first element of `nums`,
196 `1`. We then add `sum` and `x`, which gives us `0 + 1 = 1`. On the second
197 iteration, that value becomes our accumulator, `sum`, and the element is
198 the second element of the array, `2`. `1 + 2 = 3`, and so that becomes
199 the value of the accumulator for the last iteration. On that iteration,
200 `x` is the last element, `3`, and `3 + 3 = 6`, which is our final
201 result for our sum. `1 + 2 + 3 = 6`, and that's the result we got.
203 Whew. `fold` can be a bit strange the first few times you see it, but once it
204 clicks, you can use it all over the place. Any time you have a list of things,
205 and you want a single result, `fold` is appropriate.
207 Consumers are important due to one additional property of iterators we haven't
208 talked about yet: laziness. Let's talk some more about iterators, and you'll
209 see why consumers matter.
213 As we've said before, an iterator is something that we can call the
214 `.next()` method on repeatedly, and it gives us a sequence of things.
215 Because you need to call the method, this means that iterators
216 can be *lazy* and not generate all of the values upfront. This code,
217 for example, does not actually generate the numbers `1-99`, instead
218 creating a value that merely represents the sequence:
224 Since we didn't do anything with the range, it didn't generate the sequence.
225 Let's add the consumer:
228 let nums = (1..100).collect::<Vec<i32>>();
231 Now, `collect()` will require that the range gives it some numbers, and so
232 it will do the work of generating the sequence.
234 Ranges are one of two basic iterators that you'll see. The other is `iter()`.
235 `iter()` can turn a vector into a simple iterator that gives you each element
239 let nums = vec![1, 2, 3];
241 for num in nums.iter() {
246 These two basic iterators should serve you well. There are some more
247 advanced iterators, including ones that are infinite.
249 That's enough about iterators. Iterator adaptors are the last concept
250 we need to talk about with regards to iterators. Let's get to it!
254 *Iterator adaptors* take an iterator and modify it somehow, producing
255 a new iterator. The simplest one is called `map`:
258 (1..100).map(|x| x + 1);
261 `map` is called upon another iterator, and produces a new iterator where each
262 element reference has the closure it's been given as an argument called on it.
263 So this would give us the numbers from `2-100`. Well, almost! If you
264 compile the example, you'll get a warning:
267 warning: unused result which must be used: iterator adaptors are lazy and
268 do nothing unless consumed, #[warn(unused_must_use)] on by default
269 (1..100).map(|x| x + 1);
270 ^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
273 Laziness strikes again! That closure will never execute. This example
274 doesn't print any numbers:
277 (1..100).map(|x| println!("{}", x));
280 If you are trying to execute a closure on an iterator for its side effects,
281 just use `for` instead.
283 There are tons of interesting iterator adaptors. `take(n)` will return an
284 iterator over the next `n` elements of the original iterator. Let's try it out
285 with an infinite iterator:
288 for i in (1..).take(5) {
303 `filter()` is an adapter that takes a closure as an argument. This closure
304 returns `true` or `false`. The new iterator `filter()` produces
305 only the elements that the closure returns `true` for:
308 for i in (1..100).filter(|&x| x % 2 == 0) {
313 This will print all of the even numbers between one and a hundred.
314 (Note that because `filter` doesn't consume the elements that are
315 being iterated over, it is passed a reference to each element, and
316 thus the filter predicate uses the `&x` pattern to extract the integer
319 You can chain all three things together: start with an iterator, adapt it
320 a few times, and then consume the result. Check it out:
324 .filter(|&x| x % 2 == 0)
325 .filter(|&x| x % 3 == 0)
327 .collect::<Vec<i32>>();
330 This will give you a vector containing `6`, `12`, `18`, `24`, and `30`.
332 This is just a small taste of what iterators, iterator adaptors, and consumers
333 can help you with. There are a number of really useful iterators, and you can
334 write your own as well. Iterators provide a safe, efficient way to manipulate
335 all kinds of lists. They're a little unusual at first, but if you play with
336 them, you'll get hooked. For a full list of the different iterators and
337 consumers, check out the [iterator module documentation](../std/iter/index.html).