Text of rust.docs.kernel.org › src › core › iter › mod.rs.html as Styx crawled it on Nov 20, 2026. The page may have changed since. Only its words are kept, without pictures or layout, and only the first part of a long page.

Open the live page

mod.rs - source

Skip to main content core/iter/ mod.rs 1 //! Composable external iteration. 2 //! 3 //! If you've found yourself with a collection of some kind, and needed to 4 //! perform an operation on the elements of said collection, you'll quickly run 5 //! into 'iterators'. Iterators are heavily used in idiomatic Rust code, so 6 //! it's worth becoming familiar with them. 7 //! 8 //! Before explaining more, let's talk about how this module is structured: 9 //!

10 //! # Organization 11 //! 12 //! This module is largely organized by type: 13 //! 14 //! * [Traits] are the core portion: these traits define what kind of iterators 15 //! exist and what you can do with them. The methods of these traits are worth 16 //! putting some extra study time into. 17 //! * [Functions] provide some helpful ways to create some basic iterators. 18 //! * [Structs] are often the return types of the various methods on this 19 //! module's traits.

You'll usually want to look at the method that creates 20 //! the `struct`, rather than the `struct` itself. For more detail about why, 21 //! see '[Implementing Iterator](#implementing-iterator)'. 22 //! 23 //! [Traits]: #traits 24 //! [Functions]: #functions 25 //! [Structs]: #structs 26 //! 27 //! That's it! Let's dig into iterators. 28 //! 29 //! # Iterator 30 //! 31 //! The heart and soul of this module is the [`Iterator`] trait.

The core of 32 //! [`Iterator`] looks like this: 33 //! 34 //! ``` 35 //! trait Iterator { 36 //! type Item; 37 //! fn next(&mut self) -> Option<Self::Item>; 38 //! } 39 //! ``` 40 //! 41 //! An iterator has a method, [`next`], which when called, returns an 42 //! <code>[Option]\<Item></code>. Calling [`next`] will return [`Some(Item)`] as long as there 43 //! are elements, and once they've all been exhausted, will return `None` to 44 //! indicate that iteration is finished.

Individual iterators may choose to 45 //! resume iteration, and so calling [`next`] again may or may not eventually 46 //! start returning [`Some(Item)`] again at some point (for example, see [`TryIter`]). 47 //! 48 //! [`Iterator`]'s full definition includes a number of other methods as well, 49 //! but they are default methods, built on top of [`next`], and so you get 50 //! them for free. 51 //! 52 //! Iterators are also composable, and it's common to chain them together to do 53 //! more complex forms of processing.

See the [Adapters](#adapters) section 54 //! below for more details. 55 //! 56 //! [`Some(Item)`]: Some 57 //! [`next`]: Iterator::next 58 //! [`TryIter`]: ../../std/sync/mpsc/struct.TryIter.html 59 //! 60 //! # The three forms of iteration 61 //! 62 //! There are three common methods which can create iterators from a collection: 63 //! 64 //! * `iter()`, which iterates over `&T`. 65 //! * `iter_mut()`, which iterates over `&mut T`.

66 //! * `into_iter()`, which iterates over `T`. 67 //! 68 //! Various things in the standard library may implement one or more of the 69 //! three, where appropriate. 70 //! 71 //! # Implementing Iterator 72 //! 73 //! Creating an iterator of your own involves two steps: creating a `struct` to 74 //! hold the iterator's state, and then implementing [`Iterator`] for that `struct`. 75 //! This is why there are so many `struct`s in this module: there is one for 76 //! each iterator and iterator adapter.

77 //! 78 //! Let's make an iterator named `Counter` which counts from `1` to `5`: 79 //! 80 //! ``` 81 //! // First, the struct: 82 //! 83 //! /// An iterator which counts from one to five 84 //! struct Counter { 85 //! count: usize, 86 //! } 87 //! 88 //! // we want our count to start at one, so let's add a new() method to help. 89 //! // This isn't strictly necessary, but is convenient. Note that we start 90 //! // `count` at zero, we'll see why in `next()`'s implementation below.

91 //! impl Counter { 92 //! fn new() -> Counter { 93 //! Counter { count: 0 } 94 //! } 95 //! } 96 //! 97 //! // Then, we implement `Iterator` for our `Counter`: 98 //! 99 //! impl Iterator for Counter { 100 //! // we will be counting with usize 101 //! type Item = usize; 102 //! 103 //! // next() is the only required method 104 //! fn next(&mut self) -> Option<Self::Item> { 105 //! // Increment our count. This is why we started at zero.

106 //! self.count += 1; 107 //! 108 //! // Check to see if we've finished counting or not. 109 //! if self.count < 6 { 110 //! Some(self.count) 111 //! } else { 112 //! None 113 //! } 114 //! } 115 //! } 116 //! 117 //! // And now we can use it! 118 //! 119 //! let mut counter = Counter::new(); 120 //! 121 //! assert_eq!(counter.next(), Some(1)); 122 //! assert_eq!(counter.next(), Some(2)); 123 //! assert_eq!(counter.next(), Some(3)); 124 //! assert_eq!(counter.next(), Some(4)); 125 //! assert_eq!(counter.next(), Some(5)); 126 //! assert_eq!(counter.next(), None); 127 //! ``` 128 //!

129 //! Calling [`next`] this way gets repetitive. Rust has a construct which can 130 //! call [`next`] on your iterator, until it reaches `None`. Let's go over that 131 //! next. 132 //! 133 //! Also note that `Iterator` provides a default implementation of methods such as `nth` and `fold` 134 //! which call `next` internally. However, it is also possible to write a custom implementation of 135 //! methods like `nth` and `fold` if an iterator can compute them more efficiently without calling 136 //! `next`.

137 //! 138 //! # `for` loops and `IntoIterator` 139 //! 140 //! Rust's `for` loop syntax is actually sugar for iterators. Here's a basic 141 //! example of `for`: 142 //! 143 //! ``` 144 //! let values = vec![1, 2, 3, 4, 5]; 145 //! 146 //! for x in values { 147 //! println!("{x}"); 148 //! } 149 //! ``` 150 //! 151 //! This will print the numbers one through five, each on their own line. But 152 //! you'll notice something here: we never called anything on our vector to 153 //! produce an iterator.

What gives? 154 //! 155 //! There's a trait in the standard library for converting something into an 156 //! iterator: [`IntoIterator`]. This trait has one method, [`into_iter`], 157 //! which converts the thing implementing [`IntoIterator`] into an iterator. 158 //! Let's take a look at that `for` loop again, and what the compiler converts 159 //! it into: 160 //! 161 //! [`into_iter`]: IntoIterator::into_iter 162 //!

163 //! ``` 164 //! let values = vec![1, 2, 3, 4, 5]; 165 //! 166 //! for x in values { 167 //! println!("{x}"); 168 //! } 169 //! ``` 170 //! 171 //! Rust de-sugars this into: 172 //! 173 //! ``` 174 //! let values = vec![1, 2, 3, 4, 5]; 175 //! { 176 //! let result = match IntoIterator::into_iter(values) { 177 //! mut iter => loop { 178 //! let next; 179 //! match iter.next() { 180 //! Some(val) => next = val, 181 //!

None => break, 182 //! }; 183 //! let x = next; 184 //! let () = { println!("{x}"); }; 185 //! }, 186 //! }; 187 //! result 188 //! } 189 //! ``` 190 //! 191 //! First, we call `into_iter()` on the value. Then, we match on the iterator 192 //! that returns, calling [`next`] over and over until we see a `None`. At 193 //! that point, we `break` out of the loop, and we're done iterating. 194 //! 195 //! There's one more subtle bit here: the standard library contains an 196 //! interesting implementation of [`IntoIterator`]: 197 //!

198 //! ```ignore (only-for-syntax-highlight) 199 //! impl<I: Iterator> IntoIterator for I 200 //! ``` 201 //! 202 //! In other words, all [`Iterator`]s implement [`IntoIterator`], by just 203 //! returning themselves. This means two things: 204 //! 205 //! 1. If you're writing an [`Iterator`], you can use it with a `for` loop. 206 //! 2. If you're creating a collection, implementing [`IntoIterator`] for it 207 //! will allow your collection to be used with the `for` loop.

208 //! 209 //! # Iterating by reference 210 //! 211 //! Since [`into_iter()`] takes `self` by value, using a `for` loop to iterate 212 //! over a collection consumes that collection. Often, you may want to iterate 213 //! over a collection without consuming it. Many collection

The rest of this page is on the live site.