Home / Docs / Language guide / Expressions and control flow

for

Release v0.4.0Edition 0.2 and laterU0101U0103U2017U2019U4002U5002

What it does

From edition 0.2, for x in xs runs its body once for each element of a list, in order, and for i in a..<b or for i in a..b once for each integer of a range, in increasing order. A loop is a statement with the value unit (the value that carries no information): it does its work by updating let edit bindings, names whose value the code may change, declared before it.

Learn more: for over ranges and texts.

una
module shop

pub order_total(prices: List[Int]) -> Int
=
  let edit cents = 0
  for price in prices
    cents = cents + price
  cents

pub shelf_slots(shelves: Int) -> List[Int]
=
  let edit slots: List[Int] = []
  for i in 0..<shelves
    slots = slots.append(item: i * i)
  slots

Forms

In the grammar below, each rule gives a name, =, what the name stands for and ;, quoted words are written as shown, NEWLINE, INDENT and DEDENT stand for a line break and for one more or one less level of indentation, [ ] marks an optional part, { } a part that may repeat, | separates alternatives, ( ) groups them, and (* *) holds a comment.

ebnf
for_stmt        = "for" lower_ident "in" ( line_expr | range_expr ) NEWLINE INDENT block DEDENT ;
range_expr      = add_expr ( ".." | "..<" ) add_expr ;
if_stmt         = "if" line_expr NEWLINE INDENT block DEDENT ;      (* no else: a Unit statement *)

There is no while or loop, and no break or continue. In edition 0.4, stop and skip end a loop or an iteration early, and for until and for ever loop until a condition holds or until the program is stopped: see Loops that run until stopped.

Examples

An if without else inside the body, and a loop over fixed-width bounds:

una
module shop

pub count_expensive(prices: List[Int], limit: Int) -> Int
=
  let edit count = 0
  for price in prices
    if price > limit
      count = count + 1
  count

pub bin_codes(low: U8, high: U8) -> List[U8]
=
  let edit codes: List[U8] = []
  for code in low..high
    codes = codes.append(item: code)
  codes

The loop variable is not editable:

una
-- fails with U2019
module shop

pub order_total(prices: List[Int]) -> Int
=
  let edit cents = 0
  for price in prices
    price = price + 1
  cents

A bounded loop is not a general cost proof

A precondition can bound a particular range. The function below accepts at most 1,000 iterations and returns the count for this input:

una
module demo

pub count_up(limit: Int) -> Nat
  requires limit >= 0 and limit <= 1000
=
  let edit count: Nat = 0
  for i in 0..<limit
    count = count + 1
  count

example "bounded"
  do count_up(5)
  expect result == 5

This example's expect checks the chosen input; it is not a proof that every possible call returns the limit. The checker preserves declared refinements such as Nat; it does not infer the equality between this counter and the processed prefix. The requires bounds the range only when callers prove it; it is not a bound on the cost of each iteration or on allocations the body performs.

Runtime limits are separate: --max-depth caps calls in progress, and --max-memory caps heap held by a run. Exceeding either aborts with U6003; neither proves that a function terminates or that it meets a time/cost contract. See U6003 for the runtime behavior. A general termination or cost guarantee needs a separate language design.

Edge cases

Invariants come from types. The verifier (the part of una check that proves each obligation, a fact the program must be shown to keep) checks the body once, for any iteration, with the bindings the loop updates fresh at their declared types. No fact about their values survives the loop, and there is no invariant clause. So a refinement (a condition a type adds to its values, as Int in 0..100) that one iteration cannot preserve on its own is not proven:

una
-- fails with U5002
module shop

pub kind Basket = Int in 0..100

pub basket_size(prices: List[Int]) -> Basket
=
  let edit items: Basket = 0
  for price in prices
    items = items + 1
  items

The diagnostic's reason says what the loop forgets, and what to do: "guard the use with an if, or move the update into a helper with an edit parameter whose ensures states what the use needs".

A labeled list raises the program counter (the label of the conditions that decide whether a line runs; see Branches and failures: implicit flows). The body runs under the top label of the list, or of a range's bounds, since how often it runs depends on them. There, fail and calls that can fail are U4002:

una
-- fails with U4002
module shop

pub kind AuditError = | NegativePrice

pub audit(prices: secret List[Int]) -> Int
  fails AuditError
=
  for price in prices
    if price < 0
      fail NegativePrice
  0

A binding taken in the body is taken in every later iteration:

una
-- fails with U2017
module shop

pub ship(take items: List[Int]) -> Int = items.len

pub ship_batches(items: List[Int], batches: List[Int]) -> Int
=
  let edit shipped = 0
  for batch in batches
    let sent = ship(take items)
    shipped = shipped + sent
  shipped

Further rules:

Diagnostics

Edition

for loops exist from edition 0.2 on. In edition 0.1, a for loop is a syntax error, since for appears only in handler h for K:

una
-- edition 0.1
-- fails with U0101
module shop

pub first_count(prices: List[Int]) -> Int
=
  for price in prices
    unit
  0

The loops of edition 0.2 usually update a let edit binding, and edit is a reserved word in edition 0.1:

una
-- edition 0.1
-- fails with U0103
module shop

pub order_total(prices: List[Int]) -> Int
=
  let edit cents = 0
  for price in prices
    cents = cents + price
  cents

Normative source