---
title: "Iterative Statements"
canonical: "https://docs.magma-maths.org/v2.30-1/MagmaLanguage/StatementsAndExpressions/iteration.html"
source: "https://docs.magma-maths.org/v2.30-1/MagmaLanguage/StatementsAndExpressions/iteration.md"
part: "The Magma Language"
chapter: "Statements and Expressions"
breadcrumbs:
  - {"title": "Magma Handbook", "source": "https://docs.magma-maths.org/v2.30-1/index.md"}
  - {"title": "The Magma Language", "source": "https://docs.magma-maths.org/v2.30-1/MagmaLanguage/index-magma-language.md"}
  - {"title": "Statements and Expressions", "source": "https://docs.magma-maths.org/v2.30-1/MagmaLanguage/StatementsAndExpressions/index-statements-and-expressions.md"}
prev: {"title": "Error Handling Statements", "source": "https://docs.magma-maths.org/v2.30-1/MagmaLanguage/StatementsAndExpressions/error-handling.md"}
next: {"title": "Runtime Evaluation: the eval Expression", "source": "https://docs.magma-maths.org/v2.30-1/MagmaLanguage/StatementsAndExpressions/eval-expression.md"}
intrinsics:
  - {"name": "for", "signature": "for i := expr₁ to expr₂ by expr₃ do"}
  - {"name": "for", "signature": "for i := expr₁ to expr₂ do"}
  - {"name": "for", "signature": "for x in S do statements end for;"}
  - {"name": "while", "signature": "while Boolean expression do statements end while;"}
  - {"name": "repeat", "signature": "repeat statements until Boolean expression;"}
  - {"name": "for random", "signature": "for random x in S do statements end for;"}
  - {"name": "for", "signature": "for i -> x in S do statements end for;"}
  - {"name": "for random", "signature": "for random i -> x in S do statements end for;"}
  - {"name": "continue", "signature": "continue;"}
  - {"name": "continue", "signature": "continue identifier;"}
  - {"name": "break", "signature": "break;"}
  - {"name": "break", "signature": "break identifier;"}
examples:
  - "ex-9a6f96"
  - "ex-bdac72"
  - "ex-c95fc5"
---

# Iterative Statements

Four types of iterative statement are available: the `for`-statement that provides definite iteration, and the `for random`-, `while`-, and `repeat`-statements that provide indefinite iteration. Iteration may be performed over an arithmetic progression of integers or over any finite enumerated structure. Iterative statements may be nested. If nested iterations occur over the same enumerated structure, abbreviations such as `for x, y in X do` may be used; the leftmost identifier will correspond to the outermost loop, etc. (For nested iteration in sequence constructors, see Chapter [Sequences](https://docs.magma-maths.org/v2.30-1/SetsSequencesMappings/Sequences/index-sequences.md#chapseq).) Early termination of the body of loop may be specified through use of the ‘jump’ commands `break` and `continue`.

## Definite Iteration

<a id="literal-literal-for-for-i-expr1-to-expr2-by-expr3-do"></a>
### `for i := expr₁ to expr₂ by expr₃ do`

<a id="literal-literal-for-for-i-expr1-to-expr2-do"></a>
### `for i := expr₁ to expr₂ do`

The expressions in this `for` loop must return integer values, say $b$, $e$, and $s$ (for ‘begin’, ‘end’, and ‘step’) respectively. The loop is ignored if either $s>0$ and $b>e$, or $s<0$ and $b<e$. If $s=0$ an error occurs. In the remaining cases, the value $b+k\cdot s$ will be assigned to `i`, and the statements executed, for $k=0, 1, 2, \ldots$ in succession, as long as $b+k\cdot s \le e$ (for $e>0$) or $b+k\cdot s \ge e$ (for $e<0$).

In the second form above, where the step size is omitted, it is taken to be 1.

<a id="literal-literal-for-for-x-in-s-do-br-indent-statements-br-end-for"></a>
### `for x in S do statements end for;`

Each of the elements of the finite enumerated structure $S$ will be assigned to $x$ in succession, and each time the statements will be executed.

## Indefinite Iteration

<a id="literal-literal-while-while-boolean-expression-do-br-indent-statements-br-end-while"></a>
### `while Boolean expression do statements end while;`

Check whether or not the Boolean expression has the value `true`; if it has, execute the statements. Repeat this until the expression assumes the value `false`, in which case statements following the `end while;` will be executed.

<a id="example-ex-9a6f96"></a>
### `Example: Collatz Iteration with a While Loop (ex-9a6f96)`

The following short program implements a run of the famous $3x+1$ problem on a random integer between 1 and 100.

```magma
> x := Random(1, 100);
> while x gt 1 do
>     x;
>     if IsEven(x) then
>         x div:= 2;
>     else
>         x := 3*x+1;
>     end if;
> end while;
13
40
20
10
5
16
8
4
2
```

<a id="literal-literal-repeat-repeat-br-indent-statements-br-until-boolean-expression"></a>
### `repeat statements until Boolean expression;`

Execute the statements, then check whether or not the Boolean expression has the value `true`. Repeat this until the expression assumes the value `false`, in which case the loop is exited, and statements following it will be executed.

<a id="example-ex-bdac72"></a>
### `Example: Collatz Steps with a Repeat Loop (ex-bdac72)`

This example is similar to the previous one, except that it only prints $x$ and the number of steps taken before $x$ becomes $1$. We use a `repeat` loop, and show that the use of a `break` statement sometimes makes it unnecessary that the Boolean expression following the `until` ever evaluates to `true`. Similarly, a `while true` statement may be used if the user makes sure the loop will be exited using `break`.

```magma
> x := Random(1, 1000);
> x;
172
> i := 0;
> repeat
>     while IsEven(x) do
>         i +:= 1;
>         x div:= 2;
>     end while;
>     if x eq 1 then
>         break;
>     end if;
>     x := 3*x+1;
>     i +:= 1;
> until false;
> i;
31
```

<a id="literal-literal-for-random-for-random-x-in-s-do-br-indent-statements-br-end-for"></a>
### `for random x in S do statements end for;`

For each iteration of the loop a random element of $S$ is assigned to $x$ and the statements are executed. The loop will repeat with a new random selection each time until a `break` command is executed as part of the statements.

## Dual Iteration

Some objects (such as sequences, indexed sets, associative arrays, etc.) have an index or other value associated with each element. The standard iteration would loop through the elements in the object, but sometimes this other value is also wanted. Magma provides a special syntax to make it easy to get both the values at once. For conciseness, the explanations below assume that the other value is an index; the actual interpretation of the dual iteration variables is described in the Handbook section for each type which supports dual iteration.

<a id="literal-literal-for-for-i-x-in-s-do-br-indent-statements-br-end-for"></a>
### `for i -> x in S do statements end for;`

Each of the elements of the finite enumerated structure $S$ will be assigned to $x$ in succession, with the associated index assigned to $i$, and each time the statements will be executed.

<a id="literal-literal-for-random-for-random-i-x-in-s-do-br-indent-statements-br-end-for"></a>
### `for random i -> x in S do statements end for;`

For each iteration of the loop a random element of $S$ is assigned to $x$, and its associated index assigned to $i$, and the statements are executed. The loop will repeat with a new random selection each time until a `break` command is executed as part of the statements.

## Early Exit from Iterative Statements

<a id="literal-literal-continue-continue"></a>
### `continue;`

The `continue` statement can be used to jump to the end of the innermost enclosing loop: the termination condition for the loop is checked immediately.

<a id="literal-literal-continue-continue-identifier"></a>
### `continue identifier;`

As in the case of `break`, this allows jumps out of nested `for` loops: the termination condition of the loop with loop variable identifier is checked immediately after `continue identifier` is encountered.

<a id="literal-literal-break-break"></a>
### `break;`

A `break` inside a loop causes immediate exit from the innermost enclosing loop.

<a id="literal-literal-break-break-identifier"></a>
### `break identifier;`

In nested `for` loops, this allows breaking out of several loops at once: this will cause an immediate exit from the loop with loop variable identifier.

<a id="example-ex-c95fc5"></a>
### `Example: Breaking Out of Nested Loops (ex-c95fc5)`

```magma
> p := 10037;
> for x in [1 .. 100] do
>    for y in [1 .. 100] do
>       if x^2 + y^2 eq p then
>          x, y;
>          break x;
>       end if;
>    end for;
> end for;
46 89
```

Note that `break` instead of `break x` would have broken only out of the inner loop; the output in that case would have been:

```magma
46 89
89 46
```
