Commit e26661fc authored by Tim McNamara's avatar Tim McNamara


parent d6247856
This example demonstrates how to create an infinitely long `Iterator`
for a [iterated function][]. We're using'a [logistic map][] as our function, for three reasons:
This post walks you through how to define an infinite iterator in the Rust programming language.
### Background: the logistic map
To make things both simple and interesting, our iterator will be for a [iterated function][].
We're using'a [logistic map][] as our function, for three reasons:
- it's very simple
- it's the gateway drug into chaos theory
......@@ -9,13 +14,70 @@ for a [iterated function][]. We're using'a [logistic map][] as our function, for
[iterated function]:
[logistic map]:
The function is remarkably simple, yet produces spectacularly unpredictable results when the `r` parameter falls between 3.5 and 4.0:
x_new = r * x * (1 - x)
The thing that makes the logistic map interesting is that the value of `x_new` becomes `x` in the next iteration.
For many values of `r`, `x_new` is fairly orderly. But as `r` approaches 4.0, it becomes very difficult to predict the next value of `x_new`.
Here is the path for `r` is 3.995 and `x` is 0.5: 0.99875, 0.00498, 0.01982, 0.07763, 0.2861, 0.8159, 0.6000, ...
If you're confused, that's great!
You're not supposed to be able to predict what the next value will be.
All you need is a data structure stores some state, in this case `x`,
that is then fed into the actual function at each step.
### What is an iterator?
My guess is that the computer science terminology for "iterator" comes from mathematics.
An iteration is a repeated application of a function.
Within software engineering, the Gang of Four's Design Patterns book introduced the term "iterator pattern" into common discourse.
The intent was to show that it's possible to use more sophisticated methods of iterating over a collection than purely index-based methods.
In Rust, an interator is a type `T` that implements [`std::iter::Iterator`](, or `Iterator` for short.
`Iterator` includes several specialist methods, but the most important one has the following signature:
## Example 1: Implementing the logistic map as a Rust iterator
fn next(&mut self) -> Option<Self::Item>
If you're new to Rust, some of this syntax might look intimidating. Here's a 3 second guide to each part of the line.
- `fn`: keyword to define a function in Rust
- `next`: the name of the function
- `(...)`: the function's arguments
- `&mut`: the function takes read/write access to the parameter
- `self`: the object/instance that is implementing `Iterator`
- `->`: the return type indicator, e.g. what follows is returned from `next`
- `Option`: an enum containing either a data ("`Some(...)`")or a value that represents no more data ("`None`")
- `Self::Item`: It's an _associated type_ that is defined as part of the `Iterator` implementation. For out mathematical function, our iterator's associated type is a floating point number type, `f64`.
Here is a concrete example of what it means to satisfy `fn next(&mut self) -> Option<Self::Item>`, with the implementation details replaced with an imaginary function "`calculate()`":
impl Iterator for LogisticMap {
type Item = f64; // <-.
// | set Self::Item to f64
fn next(&mut self) -> Option<Self::Item> { // <-'
let new_x = calculate();
### Implementing the logistic map as a Rust iterator
The implentation at _Listing 1`_ breaks the problem into parts:
* data structure stores some state, in this case `x` and `r`. That structure, `LogisticMap`, will be repeatedly mutated over its lifetime.
* the mathematical work is pushed into a standalone function `logistic_map()`
* `LogisticMap::next()` takes care of updating its `x` value and returning the correct result
### Listing 1
fn logistic_map(x: f64, r: f64) -> f64 {
x * r * (1.0 - x)
......@@ -70,5 +132,20 @@ Output ([Try yourself][example-1])
> ]
> ```
### How do I implement an infinitely long iterator?
Oh, that's easy. Never return `None` from `T::next()`. As long as you're always returning `Some<<T::Item>`, there will be another iteration.
### Found a problem?
Please file an issue! I will be happy to look into it!
### Support the author!
If you've liked this post, then check out the book I'm writing: [_Rust in Action_][ria], published by Manning Publications.
\ No newline at end of file
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment