<!DOCTYPE html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"><meta name="generator" content="rustdoc"><meta name="description" content="API documentation for the Rust `iter` mod in crate `std`."><meta name="keywords" content="rust, rustlang, rust-lang, iter"><title>std::iter - Rust</title><link rel="stylesheet" type="text/css" href="../../normalize.css"><link rel="stylesheet" type="text/css" href="../../rustdoc.css" id="mainThemeStyle"><link rel="stylesheet" type="text/css" href="../../dark.css"><link rel="stylesheet" type="text/css" href="../../light.css" id="themeStyle"><script src="../../storage.js"></script><link rel="shortcut icon" href="https://doc.rust-lang.org/favicon.ico"></head><body class="rustdoc mod"><!--[if lte IE 8]><div class="warning">This old browser is unsupported and will most likely display funky things.</div><![endif]--><nav class="sidebar"><div class="sidebar-menu">☰</div><a href='../../std/index.html'><img src='https://www.rust-lang.org/logos/rust-logo-128x128-blk-v2.png' alt='logo' width='100'></a><p class='location'>Module iter</p><div class="sidebar-elems"><div class="block items"><ul><li><a href="#structs">Structs</a></li><li><a href="#traits">Traits</a></li><li><a href="#functions">Functions</a></li></ul></div><p class='location'><a href='../index.html'>std</a></p><script>window.sidebarCurrent = {name: 'iter', ty: 'mod', relpath: '../'};</script><script defer src="../sidebar-items.js"></script></div></nav><div class="theme-picker"><button id="theme-picker" aria-label="Pick another theme!"><img src="../../brush.svg" width="18" alt="Pick another theme!"></button><div id="theme-choices"></div></div><script src="../../theme.js"></script><nav class="sub"><form class="search-form js-only"><div class="search-container"><input class="search-input" name="search" autocomplete="off" placeholder="Click or press ‘S’ to search, ‘?’ for more options…" type="search"><a id="settings-menu" href="../../settings.html"><img src="../../wheel.svg" width="18" alt="Change settings"></a></div></form></nav><section id="main" class="content"><h1 class='fqn'><span class='in-band'>Module <a href='../index.html'>std</a>::<wbr><a class="mod" href=''>iter</a></span><span class='out-of-band'><span class='since' title='Stable since Rust version 1.0.0'>1.0.0</span><span id='render-detail'><a id="toggle-all-docs" href="javascript:void(0)" title="collapse all docs">[<span class='inner'>−</span>]</a></span><a class='srclink' href='../../src/core/lib.rs.html#197' title='goto source code'>[src]</a></span></h1><div class='docblock'><p>Composable external iteration.</p>
<p>If you've found yourself with a collection of some kind, and needed to
perform an operation on the elements of said collection, you'll quickly run
into 'iterators'. Iterators are heavily used in idiomatic Rust code, so
it's worth becoming familiar with them.</p>
<p>Before explaining more, let's talk about how this module is structured:</p>
<h1 id="organization" class="section-header"><a href="#organization">Organization</a></h1>
<p>This module is largely organized by type:</p>
<ul>
<li><a href="#traits">Traits</a> are the core portion: these traits define what kind of iterators
exist and what you can do with them. The methods of these traits are worth
putting some extra study time into.</li>
<li><a href="#functions">Functions</a> provide some helpful ways to create some basic iterators.</li>
<li><a href="#structs">Structs</a> are often the return types of the various methods on this
module's traits. You'll usually want to look at the method that creates
the <code>struct</code>, rather than the <code>struct</code> itself. For more detail about why,
see '<a href="#implementing-iterator">Implementing Iterator</a>'.</li>
</ul>
<p>That's it! Let's dig into iterators.</p>
<h1 id="iterator" class="section-header"><a href="#iterator">Iterator</a></h1>
<p>The heart and soul of this module is the <a href="trait.Iterator.html"><code>Iterator</code></a> trait. The core of
<a href="trait.Iterator.html"><code>Iterator</code></a> looks like this:</p>
<pre class="rust rust-example-rendered">
<span class="kw">trait</span> <span class="ident">Iterator</span> {
<span class="kw">type</span> <span class="ident">Item</span>;
<span class="kw">fn</span> <span class="ident">next</span>(<span class="kw-2">&</span><span class="kw-2">mut</span> <span class="self">self</span>) <span class="op">-></span> <span class="prelude-ty">Option</span><span class="op"><</span><span class="self">Self</span>::<span class="ident">Item</span><span class="op">></span>;
}<a class="test-arrow" target="_blank" href="https://play.rust-lang.org/?code=%23!%5Ballow(unused)%5D%0Afn%20main()%20%7B%0Atrait%20Iterator%20%7B%0A%20%20%20%20type%20Item%3B%0A%20%20%20%20fn%20next(%26mut%20self)%20-%3E%20Option%3CSelf%3A%3AItem%3E%3B%0A%7D%0A%7D">Run</a></pre>
<p>An iterator has a method, <a href="trait.Iterator.html#tymethod.next"><code>next</code></a>, which when called, returns an
<a href="../../std/option/enum.Option.html"><code>Option</code></a><code><Item></code>. <a href="trait.Iterator.html#tymethod.next"><code>next</code></a> will return <code>Some(Item)</code> as long as there
are elements, and once they've all been exhausted, will return <code>None</code> to
indicate that iteration is finished. Individual iterators may choose to
resume iteration, and so calling <a href="trait.Iterator.html#tymethod.next"><code>next</code></a> again may or may not eventually
start returning <code>Some(Item)</code> again at some point.</p>
<p><a href="trait.Iterator.html"><code>Iterator</code></a>'s full definition includes a number of other methods as well,
but they are default methods, built on top of <a href="trait.Iterator.html#tymethod.next"><code>next</code></a>, and so you get
them for free.</p>
<p>Iterators are also composable, and it's common to chain them together to do
more complex forms of processing. See the <a href="#adapters">Adapters</a> section
below for more details.</p>
<h1 id="the-three-forms-of-iteration" class="section-header"><a href="#the-three-forms-of-iteration">The three forms of iteration</a></h1>
<p>There are three common methods which can create iterators from a collection:</p>
<ul>
<li><code>iter()</code>, which iterates over <code>&T</code>.</li>
<li><code>iter_mut()</code>, which iterates over <code>&mut T</code>.</li>
<li><code>into_iter()</code>, which iterates over <code>T</code>.</li>
</ul>
<p>Various things in the standard library may implement one or more of the
three, where appropriate.</p>
<h1 id="implementing-iterator" class="section-header"><a href="#implementing-iterator">Implementing Iterator</a></h1>
<p>Creating an iterator of your own involves two steps: creating a <code>struct</code> to
hold the iterator's state, and then <code>impl</code>ementing <a href="trait.Iterator.html"><code>Iterator</code></a> for that
<code>struct</code>. This is why there are so many <code>struct</code>s in this module: there is
one for each iterator and iterator adapter.</p>
<p>Let's make an iterator named <code>Counter</code> which counts from <code>1</code> to <code>5</code>:</p>
<pre class="rust rust-example-rendered">
<span class="comment">// First, the struct:</span>
<span class="doccomment">/// An iterator which counts from one to five</span>
<span class="kw">struct</span> <span class="ident">Counter</span> {
<span class="ident">count</span>: <span class="ident">usize</span>,
}
<span class="comment">// we want our count to start at one, so let's add a new() method to help.</span>
<span class="comment">// This isn't strictly necessary, but is convenient. Note that we start</span>
<span class="comment">// `count` at zero, we'll see why in `next()`'s implementation below.</span>
<span class="kw">impl</span> <span class="ident">Counter</span> {
<span class="kw">fn</span> <span class="ident">new</span>() <span class="op">-></span> <span class="ident">Counter</span> {
<span class="ident">Counter</span> { <span class="ident">count</span>: <span class="number">0</span> }
}
}
<span class="comment">// Then, we implement `Iterator` for our `Counter`:</span>
<span class="kw">impl</span> <span class="ident">Iterator</span> <span class="kw">for</span> <span class="ident">Counter</span> {
<span class="comment">// we will be counting with usize</span>
<span class="kw">type</span> <span class="ident">Item</span> <span class="op">=</span> <span class="ident">usize</span>;
<span class="comment">// next() is the only required method</span>
<span class="kw">fn</span> <span class="ident">next</span>(<span class="kw-2">&</span><span class="kw-2">mut</span> <span class="self">self</span>) <span class="op">-></span> <span class="prelude-ty">Option</span><span class="op"><</span><span class="ident">usize</span><span class="op">></span> {
<span class="comment">// increment our count. This is why we started at zero.</span>
<span class="self">self</span>.<span class="ident">count</span> <span class="op">+=</span> <span class="number">1</span>;
<span class="comment">// check to see if we've finished counting or not.</span>
<span class="kw">if</span> <span class="self">self</span>.<span class="ident">count</span> <span class="op"><</span> <span class="number">6</span> {
<span class="prelude-val">Some</span>(<span class="self">self</span>.<span class="ident">count</span>)
} <span class="kw">else</span> {
<span class="prelude-val">None</span>
}
}
}
<span class="comment">// And now we can use it!</span>
<span class="kw">let</span> <span class="kw-2">mut</span> <span class="ident">counter</span> <span class="op">=</span> <span class="ident">Counter</span>::<span class="ident">new</span>();
<span class="kw">let</span> <span class="ident">x</span> <span class="op">=</span> <span class="ident">counter</span>.<span class="ident">next</span>().<span class="ident">unwrap</span>();
<span class="macro">println</span><span class="macro">!</span>(<span class="string">"{}"</span>, <span class="ident">x</span>);
<span class="kw">let</span> <span class="ident">x</span> <span class="op">=</span> <span class="ident">counter</span>.<span class="ident">next</span>().<span class="ident">unwrap</span>();
<span class="macro">println</span><span class="macro">!</span>(<span class="string">"{}"</span>, <span class="ident">x</span>);
<span class="kw">let</span> <span class="ident">x</span> <span class="op">=</span> <span class="ident">counter</span>.<span class="ident">next</span>().<span class="ident">unwrap</span>();
<span class="macro">println</span><span class="macro">!</span>(<span class="string">"{}"</span>, <span class="ident">x</span>);
<span class="kw">let</span> <span class="ident">x</span> <span class="op">=</span> <span class="ident">counter</span>.<span class="ident">next</span>().<span class="ident">unwrap</span>();
<span class="macro">println</span><span class="macro">!</span>(<span class="string">"{}"</span>, <span class="ident">x</span>);
<span class="kw">let</span> <span class="ident">x</span> <span class="op">=</span> <span class="ident">counter</span>.<span class="ident">next</span>().<span class="ident">unwrap</span>();
<span class="macro">println</span><span class="macro">!</span>(<span class="string">"{}"</span>, <span class="ident">x</span>);<a class="test-arrow" target="_blank" href="https://play.rust-lang.org/?code=%23!%5Ballow(unused)%5D%0Afn%20main()%20%7B%0A%2F%2F%20First%2C%20the%20struct%3A%0A%0A%2F%2F%2F%20An%20iterator%20which%20counts%20from%20one%20to%20five%0Astruct%20Counter%20%7B%0A%20%20%20%20count%3A%20usize%2C%0A%7D%0A%0A%2F%2F%20we%20want%20our%20count%20to%20start%20at%20one%2C%20so%20let's%20add%20a%20new()%20method%20to%20help.%0A%2F%2F%20This%20isn't%20strictly%20necessary%2C%20but%20is%20convenient.%20Note%20that%20we%20start%0A%2F%2F%20%60count%60%20at%20zero%2C%20we'll%20see%20why%20in%20%60next()%60's%20implementation%20below.%0Aimpl%20Counter%20%7B%0A%20%20%20%20fn%20new()%20-%3E%20Counter%20%7B%0A%20%20%20%20%20%20%20%20Counter%20%7B%20count%3A%200%20%7D%0A%20%20%20%20%7D%0A%7D%0A%0A%2F%2F%20Then%2C%20we%20implement%20%60Iterator%60%20for%20our%20%60Counter%60%3A%0A%0Aimpl%20Iterator%20for%20Counter%20%7B%0A%20%20%20%20%2F%2F%20we%20will%20be%20counting%20with%20usize%0A%20%20%20%20type%20Item%20%3D%20usize%3B%0A%0A%20%20%20%20%2F%2F%20next()%20is%20the%20only%20required%20method%0A%20%20%20%20fn%20next(%26mut%20self)%20-%3E%20Option%3Cusize%3E%20%7B%0A%20%20%20%20%20%20%20%20%2F%2F%20increment%20our%20count.%20This%20is%20why%20we%20started%20at%20zero.%0A%20%20%20%20%20%20%20%20self.count%20%2B%3D%201%3B%0A%0A%20%20%20%20%20%20%20%20%2F%2F%20check%20to%20see%20if%20we've%20finished%20counting%20or%20not.%0A%20%20%20%20%20%20%20%20if%20self.count%20%3C%206%20%7B%0A%20%20%20%20%20%20%20%20%20%20%20%20Some(self.count)%0A%20%20%20%20%20%20%20%20%7D%20else%20%7B%0A%20%20%20%20%20%20%20%20%20%20%20%20None%0A%20%20%20%20%20%20%20%20%7D%0A%20%20%20%20%7D%0A%7D%0A%0A%2F%2F%20And%20now%20we%20can%20use%20it!%0A%0Alet%20mut%20counter%20%3D%20Counter%3A%3Anew()%3B%0A%0Alet%20x%20%3D%20counter.next().unwrap()%3B%0Aprintln!(%22%7B%7D%22%2C%20x)%3B%0A%0Alet%20x%20%3D%20counter.next().unwrap()%3B%0Aprintln!(%22%7B%7D%22%2C%20x)%3B%0A%0Alet%20x%20%3D%20counter.next().unwrap()%3B%0Aprintln!(%22%7B%7D%22%2C%20x)%3B%0A%0Alet%20x%20%3D%20counter.next().unwrap()%3B%0Aprintln!(%22%7B%7D%22%2C%20x)%3B%0A%0Alet%20x%20%3D%20counter.next().unwrap()%3B%0Aprintln!(%22%7B%7D%22%2C%20x)%3B%0A%7D">Run</a></pre>
<p>This will print <code>1</code> through <code>5</code>, each on their own line.</p>
<p>Calling <code>next()</code> this way gets repetitive. Rust has a construct which can
call <code>next()</code> on your iterator, until it reaches <code>None</code>. Let's go over that
next.</p>
<h1 id="for-loops-and-intoiterator" class="section-header"><a href="#for-loops-and-intoiterator">for Loops and IntoIterator</a></h1>
<p>Rust's <code>for</code> loop syntax is actually sugar for iterators. Here's a basic
example of <code>for</code>:</p>
<pre class="rust rust-example-rendered">
<span class="kw">let</span> <span class="ident">values</span> <span class="op">=</span> <span class="macro">vec</span><span class="macro">!</span>[<span class="number">1</span>, <span class="number">2</span>, <span class="number">3</span>, <span class="number">4</span>, <span class="number">5</span>];
<span class="kw">for</span> <span class="ident">x</span> <span class="kw">in</span> <span class="ident">values</span> {
<span class="macro">println</span><span class="macro">!</span>(<span class="string">"{}"</span>, <span class="ident">x</span>);
}<a class="test-arrow" target="_blank" href="https://play.rust-lang.org/?code=%23!%5Ballow(unused)%5D%0Afn%20main()%20%7B%0Alet%20values%20%3D%20vec!%5B1%2C%202%2C%203%2C%204%2C%205%5D%3B%0A%0Afor%20x%20in%20values%20%7B%0A%20%20%20%20println!(%22%7B%7D%22%2C%20x)%3B%0A%7D%0A%7D">Run</a></pre>
<p>This will print the numbers one through five, each on their own line. But
you'll notice something here: we never called anything on our vector to
produce an iterator. What gives?</p>
<p>There's a trait in the standard library for converting something into an
iterator: <a href="trait.IntoIterator.html"><code>IntoIterator</code></a>. This trait has one method, <a href="trait.IntoIterator.html#tymethod.into_iter"><code>into_iter</code></a>,
which converts the thing implementing <a href="trait.IntoIterator.html"><code>IntoIterator</code></a> into an iterator.
Let's take a look at that <code>for</code> loop again, and what the compiler converts
it into:</p>
<pre class="rust rust-example-rendered">
<span class="kw">let</span> <span class="ident">values</span> <span class="op">=</span> <span class="macro">vec</span><span class="macro">!</span>[<span class="number">1</span>, <span class="number">2</span>, <span class="number">3</span>, <span class="number">4</span>, <span class="number">5</span>];
<span class="kw">for</span> <span class="ident">x</span> <span class="kw">in</span> <span class="ident">values</span> {
<span class="macro">println</span><span class="macro">!</span>(<span class="string">"{}"</span>, <span class="ident">x</span>);
}<a class="test-arrow" target="_blank" href="https://play.rust-lang.org/?code=%23!%5Ballow(unused)%5D%0Afn%20main()%20%7B%0Alet%20values%20%3D%20vec!%5B1%2C%202%2C%203%2C%204%2C%205%5D%3B%0A%0Afor%20x%20in%20values%20%7B%0A%20%20%20%20println!(%22%7B%7D%22%2C%20x)%3B%0A%7D%0A%7D">Run</a></pre>
<p>Rust de-sugars this into:</p>
<pre class="rust rust-example-rendered">
<span class="kw">let</span> <span class="ident">values</span> <span class="op">=</span> <span class="macro">vec</span><span class="macro">!</span>[<span class="number">1</span>, <span class="number">2</span>, <span class="number">3</span>, <span class="number">4</span>, <span class="number">5</span>];
{
<span class="kw">let</span> <span class="ident">result</span> <span class="op">=</span> <span class="kw">match</span> <span class="ident">IntoIterator</span>::<span class="ident">into_iter</span>(<span class="ident">values</span>) {
<span class="kw-2">mut</span> <span class="ident">iter</span> <span class="op">=></span> <span class="kw">loop</span> {
<span class="kw">let</span> <span class="ident">next</span>;
<span class="kw">match</span> <span class="ident">iter</span>.<span class="ident">next</span>() {
<span class="prelude-val">Some</span>(<span class="ident">val</span>) <span class="op">=></span> <span class="ident">next</span> <span class="op">=</span> <span class="ident">val</span>,
<span class="prelude-val">None</span> <span class="op">=></span> <span class="kw">break</span>,
};
<span class="kw">let</span> <span class="ident">x</span> <span class="op">=</span> <span class="ident">next</span>;
<span class="kw">let</span> () <span class="op">=</span> { <span class="macro">println</span><span class="macro">!</span>(<span class="string">"{}"</span>, <span class="ident">x</span>); };
},
};
<span class="ident">result</span>
}<a class="test-arrow" target="_blank" href="https://play.rust-lang.org/?code=%23!%5Ballow(unused)%5D%0Afn%20main()%20%7B%0Alet%20values%20%3D%20vec!%5B1%2C%202%2C%203%2C%204%2C%205%5D%3B%0A%7B%0A%20%20%20%20let%20result%20%3D%20match%20IntoIterator%3A%3Ainto_iter(values)%20%7B%0A%20%20%20%20%20%20%20%20mut%20iter%20%3D%3E%20loop%20%7B%0A%20%20%20%20%20%20%20%20%20%20%20%20let%20next%3B%0A%20%20%20%20%20%20%20%20%20%20%20%20match%20iter.next()%20%7B%0A%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20Some(val)%20%3D%3E%20next%20%3D%20val%2C%0A%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20None%20%3D%3E%20break%2C%0A%20%20%20%20%20%20%20%20%20%20%20%20%7D%3B%0A%20%20%20%20%20%20%20%20%20%20%20%20let%20x%20%3D%20next%3B%0A%20%20%20%20%20%20%20%20%20%20%20%20let%20()%20%3D%20%7B%20println!(%22%7B%7D%22%2C%20x)%3B%20%7D%3B%0A%20%20%20%20%20%20%20%20%7D%2C%0A%20%20%20%20%7D%3B%0A%20%20%20%20result%0A%7D%0A%7D">Run</a></pre>
<p>First, we call <code>into_iter()</code> on the value. Then, we match on the iterator
that returns, calling <a href="trait.Iterator.html#tymethod.next"><code>next</code></a> over and over until we see a <code>None</code>. At
that point, we <code>break</code> out of the loop, and we're done iterating.</p>
<p>There's one more subtle bit here: the standard library contains an
interesting implementation of <a href="trait.IntoIterator.html"><code>IntoIterator</code></a>:</p>
<div class='information'><div class='tooltip ignore'>ⓘ<span class='tooltiptext'>This example is not tested</span></div></div><pre class="rust rust-example-rendered ignore">
<span class="kw">impl</span><span class="op"><</span><span class="ident">I</span>: <span class="ident">Iterator</span><span class="op">></span> <span class="ident">IntoIterator</span> <span class="kw">for</span> <span class="ident">I</span><a class="test-arrow" target="_blank" href="https://play.rust-lang.org/?code=%23!%5Ballow(unused)%5D%0Afn%20main()%20%7B%0Aimpl%3CI%3A%20Iterator%3E%20IntoIterator%20for%20I%0A%7D">Run</a></pre>
<p>In other words, all <a href="trait.Iterator.html"><code>Iterator</code></a>s implement <a href="trait.IntoIterator.html"><code>IntoIterator</code></a>, by just
returning themselves. This means two things:</p>
<ol>
<li>If you're writing an <a href="trait.Iterator.html"><code>Iterator</code></a>, you can use it with a <code>for</code> loop.</li>
<li>If you're creating a collection, implementing <a href="trait.IntoIterator.html"><code>IntoIterator</code></a> for it
will allow your collection to be used with the <code>for</code> loop.</li>
</ol>
<h1 id="adapters" class="section-header"><a href="#adapters">Adapters</a></h1>
<p>Functions which take an <a href="trait.Iterator.html"><code>Iterator</code></a> and return another <a href="trait.Iterator.html"><code>Iterator</code></a> are
often called 'iterator adapters', as they're a form of the 'adapter
pattern'.</p>
<p>Common iterator adapters include <a href="trait.Iterator.html#method.map"><code>map</code></a>, <a href="trait.Iterator.html#method.take"><code>take</code></a>, and <a href="trait.Iterator.html#method.filter"><code>filter</code></a>.
For more, see their documentation.</p>
<h1 id="laziness" class="section-header"><a href="#laziness">Laziness</a></h1>
<p>Iterators (and iterator <a href="#adapters">adapters</a>) are <em>lazy</em>. This means that
just creating an iterator doesn't <em>do</em> a whole lot. Nothing really happens
until you call <a href="trait.Iterator.html#tymethod.next"><code>next</code></a>. This is sometimes a source of confusion when
creating an iterator solely for its side effects. For example, the <a href="trait.Iterator.html#method.map"><code>map</code></a>
method calls a closure on each element it iterates over:</p>
<pre class="rust rust-example-rendered">
<span class="kw">let</span> <span class="ident">v</span> <span class="op">=</span> <span class="macro">vec</span><span class="macro">!</span>[<span class="number">1</span>, <span class="number">2</span>, <span class="number">3</span>, <span class="number">4</span>, <span class="number">5</span>];
<span class="ident">v</span>.<span class="ident">iter</span>().<span class="ident">map</span>(<span class="op">|</span><span class="ident">x</span><span class="op">|</span> <span class="macro">println</span><span class="macro">!</span>(<span class="string">"{}"</span>, <span class="ident">x</span>));<a class="test-arrow" target="_blank" href="https://play.rust-lang.org/?code=%23!%5Ballow(unused)%5D%0A%23!%5Ballow(unused_must_use)%5D%0Afn%20main()%20%7B%0Alet%20v%20%3D%20vec!%5B1%2C%202%2C%203%2C%204%2C%205%5D%3B%0Av.iter().map(%7Cx%7C%20println!(%22%7B%7D%22%2C%20x))%3B%0A%7D">Run</a></pre>
<p>This will not print any values, as we only created an iterator, rather than
using it. The compiler will warn us about this kind of behavior:</p>
<pre><code class="language-text">warning: unused result which must be used: iterator adaptors are lazy and
do nothing unless consumed
</code></pre>
<p>The idiomatic way to write a <a href="trait.Iterator.html#method.map"><code>map</code></a> for its side effects is to use a
<code>for</code> loop instead:</p>
<pre class="rust rust-example-rendered">
<span class="kw">let</span> <span class="ident">v</span> <span class="op">=</span> <span class="macro">vec</span><span class="macro">!</span>[<span class="number">1</span>, <span class="number">2</span>, <span class="number">3</span>, <span class="number">4</span>, <span class="number">5</span>];
<span class="kw">for</span> <span class="ident">x</span> <span class="kw">in</span> <span class="kw-2">&</span><span class="ident">v</span> {
<span class="macro">println</span><span class="macro">!</span>(<span class="string">"{}"</span>, <span class="ident">x</span>);
}<a class="test-arrow" target="_blank" href="https://play.rust-lang.org/?code=%23!%5Ballow(unused)%5D%0Afn%20main()%20%7B%0Alet%20v%20%3D%20vec!%5B1%2C%202%2C%203%2C%204%2C%205%5D%3B%0A%0Afor%20x%20in%20%26v%20%7B%0A%20%20%20%20println!(%22%7B%7D%22%2C%20x)%3B%0A%7D%0A%7D">Run</a></pre>
<p>The two most common ways to evaluate an iterator are to use a <code>for</code> loop
like this, or using the <a href="trait.Iterator.html#method.collect"><code>collect</code></a> method to produce a new collection.</p>
<h1 id="infinity" class="section-header"><a href="#infinity">Infinity</a></h1>
<p>Iterators do not have to be finite. As an example, an open-ended range is
an infinite iterator:</p>
<pre class="rust rust-example-rendered">
<span class="kw">let</span> <span class="ident">numbers</span> <span class="op">=</span> <span class="number">0</span>..;<a class="test-arrow" target="_blank" href="https://play.rust-lang.org/?code=%23!%5Ballow(unused)%5D%0Afn%20main()%20%7B%0Alet%20numbers%20%3D%200..%3B%0A%7D">Run</a></pre>
<p>It is common to use the <a href="trait.Iterator.html#method.take"><code>take</code></a> iterator adapter to turn an infinite
iterator into a finite one:</p>
<pre class="rust rust-example-rendered">
<span class="kw">let</span> <span class="ident">numbers</span> <span class="op">=</span> <span class="number">0</span>..;
<span class="kw">let</span> <span class="ident">five_numbers</span> <span class="op">=</span> <span class="ident">numbers</span>.<span class="ident">take</span>(<span class="number">5</span>);
<span class="kw">for</span> <span class="ident">number</span> <span class="kw">in</span> <span class="ident">five_numbers</span> {
<span class="macro">println</span><span class="macro">!</span>(<span class="string">"{}"</span>, <span class="ident">number</span>);
}<a class="test-arrow" target="_blank" href="https://play.rust-lang.org/?code=%23!%5Ballow(unused)%5D%0Afn%20main()%20%7B%0Alet%20numbers%20%3D%200..%3B%0Alet%20five_numbers%20%3D%20numbers.take(5)%3B%0A%0Afor%20number%20in%20five_numbers%20%7B%0A%20%20%20%20println!(%22%7B%7D%22%2C%20number)%3B%0A%7D%0A%7D">Run</a></pre>
<p>This will print the numbers <code>0</code> through <code>4</code>, each on their own line.</p>
<p>Bear in mind that methods on infinite iterators, even those for which a
result can be determined mathematically in finite time, may not terminate.
Specifically, methods such as <a href="trait.Iterator.html#method.min"><code>min</code></a>, which in the general case require
traversing every element in the iterator, are likely not to return
successfully for any infinite iterators.</p>
<pre class="rust rust-example-rendered">
<span class="kw">let</span> <span class="ident">ones</span> <span class="op">=</span> <span class="ident">std</span>::<span class="ident">iter</span>::<span class="ident">repeat</span>(<span class="number">1</span>);
<span class="kw">let</span> <span class="ident">least</span> <span class="op">=</span> <span class="ident">ones</span>.<span class="ident">min</span>().<span class="ident">unwrap</span>(); <span class="comment">// Oh no! An infinite loop!</span>
<span class="comment">// `ones.min()` causes an infinite loop, so we won't reach this point!</span>
<span class="macro">println</span><span class="macro">!</span>(<span class="string">"The smallest number one is {}."</span>, <span class="ident">least</span>);<a class="test-arrow" target="_blank" href="https://play.rust-lang.org/?code=%23!%5Ballow(unused)%5D%0Afn%20main()%20%7B%0Alet%20ones%20%3D%20std%3A%3Aiter%3A%3Arepeat(1)%3B%0Alet%20least%20%3D%20ones.min().unwrap()%3B%20%2F%2F%20Oh%20no!%20An%20infinite%20loop!%0A%2F%2F%20%60ones.min()%60%20causes%20an%20infinite%20loop%2C%20so%20we%20won't%20reach%20this%20point!%0Aprintln!(%22The%20smallest%20number%20one%20is%20%7B%7D.%22%2C%20least)%3B%0A%7D">Run</a></pre>
</div><h2 id='structs' class='section-header'><a href="#structs">Structs</a></h2>
<table>
<tr class=' module-item'>
<td><a class="struct" href="struct.Chain.html"
title='struct std::iter::Chain'>Chain</a></td>
<td class='docblock-short'>
<p>An iterator that strings two iterators together.</p>
</td>
</tr>
<tr class=' module-item'>
<td><a class="struct" href="struct.Cloned.html"
title='struct std::iter::Cloned'>Cloned</a></td>
<td class='docblock-short'>
<p>An iterator that clones the elements of an underlying iterator.</p>
</td>
</tr>
<tr class=' module-item'>
<td><a class="struct" href="struct.Cycle.html"
title='struct std::iter::Cycle'>Cycle</a></td>
<td class='docblock-short'>
<p>An iterator that repeats endlessly.</p>
</td>
</tr>
<tr class=' module-item'>
<td><a class="struct" href="struct.Empty.html"
title='struct std::iter::Empty'>Empty</a></td>
<td class='docblock-short'>
<p>An iterator that yields nothing.</p>
</td>
</tr>
<tr class=' module-item'>
<td><a class="struct" href="struct.Enumerate.html"
title='struct std::iter::Enumerate'>Enumerate</a></td>
<td class='docblock-short'>
<p>An iterator that yields the current count and the element during iteration.</p>
</td>
</tr>
<tr class=' module-item'>
<td><a class="struct" href="struct.Filter.html"
title='struct std::iter::Filter'>Filter</a></td>
<td class='docblock-short'>
<p>An iterator that filters the elements of <code>iter</code> with <code>predicate</code>.</p>
</td>
</tr>
<tr class=' module-item'>
<td><a class="struct" href="struct.FilterMap.html"
title='struct std::iter::FilterMap'>FilterMap</a></td>
<td class='docblock-short'>
<p>An iterator that uses <code>f</code> to both filter and map elements from <code>iter</code>.</p>
</td>
</tr>
<tr class=' module-item'>
<td><a class="struct" href="struct.FlatMap.html"
title='struct std::iter::FlatMap'>FlatMap</a></td>
<td class='docblock-short'>
<p>An iterator that maps each element to an iterator, and yields the elements
of the produced iterators.</p>
</td>
</tr>
<tr class=' module-item'>
<td><a class="struct" href="struct.Fuse.html"
title='struct std::iter::Fuse'>Fuse</a></td>
<td class='docblock-short'>
<p>An iterator that yields <code>None</code> forever after the underlying iterator
yields <code>None</code> once.</p>
</td>
</tr>
<tr class=' module-item'>
<td><a class="struct" href="struct.Inspect.html"
title='struct std::iter::Inspect'>Inspect</a></td>
<td class='docblock-short'>
<p>An iterator that calls a function with a reference to each element before
yielding it.</p>
</td>
</tr>
<tr class=' module-item'>
<td><a class="struct" href="struct.Map.html"
title='struct std::iter::Map'>Map</a></td>
<td class='docblock-short'>
<p>An iterator that maps the values of <code>iter</code> with <code>f</code>.</p>
</td>
</tr>
<tr class=' module-item'>
<td><a class="struct" href="struct.Once.html"
title='struct std::iter::Once'>Once</a></td>
<td class='docblock-short'>
<p>An iterator that yields an element exactly once.</p>
</td>
</tr>
<tr class=' module-item'>
<td><a class="struct" href="struct.Peekable.html"
title='struct std::iter::Peekable'>Peekable</a></td>
<td class='docblock-short'>
<p>An iterator with a <code>peek()</code> that returns an optional reference to the next
element.</p>
</td>
</tr>
<tr class=' module-item'>
<td><a class="struct" href="struct.Repeat.html"
title='struct std::iter::Repeat'>Repeat</a></td>
<td class='docblock-short'>
<p>An iterator that repeats an element endlessly.</p>
</td>
</tr>
<tr class=' module-item'>
<td><a class="struct" href="struct.RepeatWith.html"
title='struct std::iter::RepeatWith'>RepeatWith</a></td>
<td class='docblock-short'>
<p>An iterator that repeats elements of type <code>A</code> endlessly by
applying the provided closure <code>F: FnMut() -> A</code>.</p>
</td>
</tr>
<tr class=' module-item'>
<td><a class="struct" href="struct.Rev.html"
title='struct std::iter::Rev'>Rev</a></td>
<td class='docblock-short'>
<p>A double-ended iterator with the direction inverted.</p>
</td>
</tr>
<tr class=' module-item'>
<td><a class="struct" href="struct.Scan.html"
title='struct std::iter::Scan'>Scan</a></td>
<td class='docblock-short'>
<p>An iterator to maintain state while iterating another iterator.</p>
</td>
</tr>
<tr class=' module-item'>
<td><a class="struct" href="struct.Skip.html"
title='struct std::iter::Skip'>Skip</a></td>
<td class='docblock-short'>
<p>An iterator that skips over <code>n</code> elements of <code>iter</code>.</p>
</td>
</tr>
<tr class=' module-item'>
<td><a class="struct" href="struct.SkipWhile.html"
title='struct std::iter::SkipWhile'>SkipWhile</a></td>
<td class='docblock-short'>
<p>An iterator that rejects elements while <code>predicate</code> is true.</p>
</td>
</tr>
<tr class=' module-item'>
<td><a class="struct" href="struct.StepBy.html"
title='struct std::iter::StepBy'>StepBy</a></td>
<td class='docblock-short'>
<p>An iterator for stepping iterators by a custom amount.</p>
</td>
</tr>
<tr class=' module-item'>
<td><a class="struct" href="struct.Take.html"
title='struct std::iter::Take'>Take</a></td>
<td class='docblock-short'>
<p>An iterator that only iterates over the first <code>n</code> iterations of <code>iter</code>.</p>
</td>
</tr>
<tr class=' module-item'>
<td><a class="struct" href="struct.TakeWhile.html"
title='struct std::iter::TakeWhile'>TakeWhile</a></td>
<td class='docblock-short'>
<p>An iterator that only accepts elements while <code>predicate</code> is true.</p>
</td>
</tr>
<tr class=' module-item'>
<td><a class="struct" href="struct.Zip.html"
title='struct std::iter::Zip'>Zip</a></td>
<td class='docblock-short'>
<p>An iterator that iterates two other iterators simultaneously.</p>
</td>
</tr>
<tr class='unstable module-item'>
<td><a class="struct" href="struct.Flatten.html"
title='struct std::iter::Flatten'>Flatten</a></td>
<td class='docblock-short'>
[<div class='stab unstable'>Experimental</div>] <p>An iterator that flattens one level of nesting in an iterator of things
that can be turned into iterators.</p>
</td>
</tr></table><h2 id='traits' class='section-header'><a href="#traits">Traits</a></h2>
<table>
<tr class=' module-item'>
<td><a class="trait" href="trait.DoubleEndedIterator.html"
title='trait std::iter::DoubleEndedIterator'>DoubleEndedIterator</a></td>
<td class='docblock-short'>
<p>An iterator able to yield elements from both ends.</p>
</td>
</tr>
<tr class=' module-item'>
<td><a class="trait" href="trait.ExactSizeIterator.html"
title='trait std::iter::ExactSizeIterator'>ExactSizeIterator</a></td>
<td class='docblock-short'>
<p>An iterator that knows its exact length.</p>
</td>
</tr>
<tr class=' module-item'>
<td><a class="trait" href="trait.Extend.html"
title='trait std::iter::Extend'>Extend</a></td>
<td class='docblock-short'>
<p>Extend a collection with the contents of an iterator.</p>
</td>
</tr>
<tr class=' module-item'>
<td><a class="trait" href="trait.FromIterator.html"
title='trait std::iter::FromIterator'>FromIterator</a></td>
<td class='docblock-short'>
<p>Conversion from an <code>Iterator</code>.</p>
</td>
</tr>
<tr class=' module-item'>
<td><a class="trait" href="trait.FusedIterator.html"
title='trait std::iter::FusedIterator'>FusedIterator</a></td>
<td class='docblock-short'>
<p>An iterator that always continues to yield <code>None</code> when exhausted.</p>
</td>
</tr>
<tr class=' module-item'>
<td><a class="trait" href="trait.IntoIterator.html"
title='trait std::iter::IntoIterator'>IntoIterator</a></td>
<td class='docblock-short'>
<p>Conversion into an <code>Iterator</code>.</p>
</td>
</tr>
<tr class=' module-item'>
<td><a class="trait" href="trait.Iterator.html"
title='trait std::iter::Iterator'>Iterator</a></td>
<td class='docblock-short'>
<p>An interface for dealing with iterators.</p>
</td>
</tr>
<tr class=' module-item'>
<td><a class="trait" href="trait.Product.html"
title='trait std::iter::Product'>Product</a></td>
<td class='docblock-short'>
<p>Trait to represent types that can be created by multiplying elements of an
iterator.</p>
</td>
</tr>
<tr class=' module-item'>
<td><a class="trait" href="trait.Sum.html"
title='trait std::iter::Sum'>Sum</a></td>
<td class='docblock-short'>
<p>Trait to represent types that can be created by summing up an iterator.</p>
</td>
</tr>
<tr class='unstable module-item'>
<td><a class="trait" href="trait.Step.html"
title='trait std::iter::Step'>Step</a></td>
<td class='docblock-short'>
[<div class='stab unstable'>Experimental</div>] <p>Objects that can be stepped over in both directions.</p>
</td>
</tr>
<tr class='unstable module-item'>
<td><a class="trait" href="trait.TrustedLen.html"
title='trait std::iter::TrustedLen'>TrustedLen</a></td>
<td class='docblock-short'>
[<div class='stab unstable'>Experimental</div>] <p>An iterator that reports an accurate length using size_hint.</p>
</td>
</tr></table><h2 id='functions' class='section-header'><a href="#functions">Functions</a></h2>
<table>
<tr class=' module-item'>
<td><a class="fn" href="fn.empty.html"
title='fn std::iter::empty'>empty</a></td>
<td class='docblock-short'>
<p>Creates an iterator that yields nothing.</p>
</td>
</tr>
<tr class=' module-item'>
<td><a class="fn" href="fn.once.html"
title='fn std::iter::once'>once</a></td>
<td class='docblock-short'>
<p>Creates an iterator that yields an element exactly once.</p>
</td>
</tr>
<tr class=' module-item'>
<td><a class="fn" href="fn.repeat.html"
title='fn std::iter::repeat'>repeat</a></td>
<td class='docblock-short'>
<p>Creates a new iterator that endlessly repeats a single element.</p>
</td>
</tr>
<tr class=' module-item'>
<td><a class="fn" href="fn.repeat_with.html"
title='fn std::iter::repeat_with'>repeat_with</a></td>
<td class='docblock-short'>
<p>Creates a new iterator that repeats elements of type <code>A</code> endlessly by
applying the provided closure, the repeater, <code>F: FnMut() -> A</code>.</p>
</td>
</tr></table></section><section id="search" class="content hidden"></section><section class="footer"></section><aside id="help" class="hidden"><div><h1 class="hidden">Help</h1><div class="shortcuts"><h2>Keyboard Shortcuts</h2><dl><dt><kbd>?</kbd></dt><dd>Show this help dialog</dd><dt><kbd>S</kbd></dt><dd>Focus the search field</dd><dt><kbd>↑</kbd></dt><dd>Move up in search results</dd><dt><kbd>↓</kbd></dt><dd>Move down in search results</dd><dt><kbd>↹</kbd></dt><dd>Switch tab</dd><dt><kbd>⏎</kbd></dt><dd>Go to active search result</dd><dt><kbd>+</kbd></dt><dd>Expand all sections</dd><dt><kbd>-</kbd></dt><dd>Collapse all sections</dd></dl></div><div class="infos"><h2>Search Tricks</h2><p>Prefix searches with a type followed by a colon (e.g. <code>fn:</code>) to restrict the search to a given type.</p><p>Accepted types are: <code>fn</code>, <code>mod</code>, <code>struct</code>, <code>enum</code>, <code>trait</code>, <code>type</code>, <code>macro</code>, and <code>const</code>.</p><p>Search functions by type signature (e.g. <code>vec -> usize</code> or <code>* -> vec</code>)</p><p>Search multiple things at once by splitting your query with comma (e.g. <code>str,u8</code> or <code>String,struct:Vec,test</code>)</p></div></div></aside><script>window.rootPath = "../../";window.currentCrate = "std";</script><script src="../../aliases.js"></script><script src="../../main.js"></script><script defer src="../../search-index.js"></script></body></html>
distrib
>
Mageia
>
6
>
armv7hl
>
media
>
core-updates
>
by-pkgid
>
4e2dbb669434a7691662cb2f0ad38972
>
files
>
13466
