Skip to content
Tutorials Center
My learning

Topics

Lesson 13 of 36 ยท Procedures and Control Flow

Iterators, Closures and Lambdas

Write your own Nim iterators with yield, understand inline and closure iterators, create closures that capture variables, use lambdas and the sugar module, with C stand-ins.

A for loop works on anything that has an iterator. The standard library provides many (items, pairs, countup), and you can write your own with the yield statement. Related to iterators are closures: procedures that remember variables from the place where they were created. Both ideas are about producing or carrying state, and both are surprisingly simple in Nim.

Nim code in this lesson is read-only (the compiler cannot run on this site). The C stand-ins show what the compiler effectively builds.

Writing an iterator

NIM
iterator countTo(n: int): int =
  var i = 1
  while i <= n:
    yield i
    inc i

for x in countTo(3):
  echo x              # 1 2 3

An iterator looks like a procedure, but instead of return it uses yield to hand a value to the loop and pause. When the loop asks for the next value, execution continues right after the yield. The loop variable receives each yielded value.

You can yield more than one value and use the multi-variable form of for:

NIM
iterator indexed[T](items: openArray[T]): (int, T) =
  for i in 0 ..< items.len:
    yield (i, items[i])

for i, name in indexed(["ann", "bo", "cy"]):
  echo i, " ", name

Reaching the end of the iterator body ends the loop. An iterator can only be used in a for loop (or turned into a sequence with a helper such as toSeq from std/sequtils).

Inline iterators are free

Ordinary iterators (called inline iterators) are expanded directly into the loop at compile time. There is no function call and no allocation, so for x in countTo(3) runs as fast as a hand-written while. This is why standard iterators such as items and countup cost nothing.

Closure iterators

If you need an iterator that you can pass around and resume manually, mark it {.closure.}:

NIM
iterator fibs(): int {.closure.} =
  var a = 0
  var b = 1
  while true:
    yield a
    (a, b) = (b, a + b)

var gen = fibs
for _ in 1 .. 8:
  echo gen()          # 0 1 1 2 3 5 8 13

A closure iterator keeps its own state between calls; each call to gen() resumes after the last yield. Check finished(gen) to see whether it has run out. Closure iterators cost a heap object, so use them only when you need that flexibility.

Closures

A closure is a procedure value that captures variables from the surrounding scope:

NIM
proc makeCounter(): (proc(): int) =
  var count = 0
  result = proc(): int =
    inc count
    count

let a = makeCounter()
let b = makeCounter()
echo a(), " ", a(), " ", b()      # 1 2 1

Each call to makeCounter creates its own count. The returned anonymous procedure keeps it alive, so a and b count independently. Nim moves captured variables onto the heap when a closure outlives the procedure that created them.

Anonymous procedures and =>

A procedure without a name is a lambda. The std/sugar module adds an arrow syntax for short ones:

NIM
import std/[sequtils, sugar]

let nums = @[1, 2, 3, 4]
let doubled = nums.map(x => x * 2)                 # @[2, 4, 6, 8]
let evens = nums.filter(x => x mod 2 == 0)         # @[2, 4]
let squares = nums.mapIt(it * it)                  # @[1, 4, 9, 16]

map and filter take a procedure argument. mapIt and filterIt are templates that give you an implicit variable called it, which is the shortest form.

Procedure types

The type of a procedure value is written like the procedure's header:

NIM
type Operation = proc(a, b: int): int

proc apply(op: Operation, x, y: int): int = op(x, y)

echo apply((a, b) => a + b, 3, 4)          # 7

Passing procedures to procedures is how callbacks, strategies and sorting comparisons are expressed.

flowchart LR
  I["iterator body"] -- "yield value" --> L["for loop body"]
  L -- "next iteration" --> I
  C["closure"] --- E["captured variables<br/>(environment)"]

Caption: an iterator and its loop take turns; a closure carries its environment with it.

Stand-in: an iterator as a state machine

The compiler turns an inline iterator into a plain loop. A closure iterator is a small struct holding its local variables and the "where was I" position. This C stand-in builds the Fibonacci generator that way.

C Stand-in: closure iterator as a struct

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with scanf or fgets), it gets the next line from this box.

The output is 0 1 1 2 3 5 8 13, the same sequence the Nim iterator yields.

Stand-in: a closure as function plus environment

C has no closures, but you can build one: a function pointer paired with a struct for the captured variables. This is what Nim's compiler generates for you.

C Stand-in: counter closure with an environment

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with scanf or fgets), it gets the next line from this box.

Two closures, two separate environments, exactly like a and b in the Nim example.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does yield do in an iterator?

    yield produces the next loop value and resumes after itself.
  2. 2. Why are ordinary (inline) iterators fast?

    An inline iterator becomes plain loop code, with no call overhead.
  3. 3. In let a = makeCounter() and let b = makeCounter(), why do a and b count independently?

    Every call to makeCounter creates a new environment that the returned closure keeps alive.
  4. 4. What is it in nums.mapIt(it * it)?

    mapIt is a template that injects the element as it.

Summary

  • An iterator uses yield to feed a for loop; inline iterators compile to plain loops.
  • {.closure.} iterators keep state between manual calls but allocate.
  • A closure is a procedure that captures variables from its surroundings.
  • Lambdas are anonymous procedures; std/sugar provides => and std/sequtils offers map, filter, mapIt.

Next: Exceptions and defer