# Iterator\[A: A\]
<span class="source-link">[[Source]](src/builtin/iterator.md#L1)</span>


Iterators generate a series of values, one value at a time on each call to `next()`.

An Iterator is considered exhausted, once its `has_next()` method returns `false`.
Thus every call to `next()` should be preceeded with a call to `has_next()` to
check for exhaustiveness.

## Usage

Given the rules for using Iterators mentioned above, basic usage
of an iterator looks like this:

```pony
while iterator.has_next() do
  let elem = iterator.next()?
  // do something with elem
end
```

The `For`-loop provides a more concise way of iteration:

```pony
for elem in iterator do
  // do something with elem
end
```

Iteration using `While` is more flexible as it allows to continue iterating if a call to `next()` errors.
The `For`-loop does not allow this.

## Implementing Iterators

Iterator implementations need to adhere to the following rules to be considered well-behaved:

* If the Iterator is exhausted, `has_next()` needs to return `false`.
* Once `has_next()` returned `false` it is not allowed to switch back to `true`
  (Unless the Iterator supports rewinding)
* `has_next()` does not change its returned value if `next()` has not been called.
  That means, that between two calls to `next()` any number of calls to `has_next()`
  need to return the same value. (Unless the Iterator supports rewinding)
* A call to `next()` erroring does not necessarily denote exhaustiveness.

### Example

```pony
// Generates values from `from` to 0
class ref Countdown is Iterator[USize]
  var _cur: USize
  var _has_next: Bool = true

  new ref create(from: USize) =>
    _cur = from

  fun ref has_next(): Bool =>
    _has_next

  fun ref next(): USize =>
    let elem = _cur = _cur - 1
    if elem == 0 then
      _has_next = false
    end
    elem
```



```pony
interface ref Iterator[A: A]
```

## Public Functions

### has_next
<span class="source-link">[[Source]](src/builtin/iterator.md#L69)</span>


Returns `true` if this Iterator is not yet exhausted.
That means that a value returned from a subsequent call to `next()`
is a valid part of this iterator.

Returns `false` if this Iterator is exhausted.

The behavior of `next()` after this function returned `false` is undefined,
it might throw an error or return values which are not part of this Iterator.


```pony
fun ref has_next()
: Bool val
```

#### Returns

* [Bool](builtin-Bool.md) val

---

### next
<span class="source-link">[[Source]](src/builtin/iterator.md#L81)</span>


Generate the next value.

This might error, which does not necessarily mean that the Iterator is exhausted.


```pony
fun ref next()
: A ?
```

#### Returns

* A ?

---

