Control Flow

Control flow statements determine the execution path of your program.

If Expressions

Basic If

1if condition {2    // Execute if condition is true3}

If-Else

1if condition {2    // Execute if condition is true3} else {4    // Execute if condition is false5}

Else-If Chains

1if condition1 {2    // Execute if condition1 is true3} else if condition2 {4    // Execute if condition2 is true5} else if condition3 {6    // Execute if condition3 is true7} else {8    // Execute if all conditions are false9}

Conditional Requirements

Conditions must be boolean expressions:

1// Valid conditions2if x > 0 { }3if flag { }4if a == b { }5if is_valid && is_ready { }6 7// Invalid conditions8// if x { }           // Error: x is i32, not bool9// if 1 { }           // Error: 1 is i32, not bool

If in Functions

Early Return

1func clamp(x: i32, min: i32, max: i32) -> i32 {2    if x < min {3        return min4    }5    if x > max {6        return max7    }8    return x9}

Conditional Return

1func sign(x: i32) -> i32 {2    if x > 0 {3        return 14    } else if x < 0 {5        return -16    } else {7        return 08    }9}

Expression-Based Return

An if/else is an expression: its value is the trailing expression of the taken branch. It can be a function's implicit return value or be bound to a variable. Both branches must yield the same type, so an else is required when the value is used.

A branch that leaves the scope instead of producing a value (return, break, continue, panic(...), unreachable()) is exempt from that agreement: it never reaches the point where the if has a value, so the other branch decides the type. if n > 0 { return 1 } else { 2 } is an i32. The same rule applies to match arms.

1func abs(x: i32) -> i32 {2    if x >= 0 {3        x  // Implicit return4    } else {5        -x  // Implicit return6    }7}8 9func clamp_low(x: i32) -> i32 {10    val y = if x < 0 { 0 } else { x }  // bound to a variable11    y12}

Block Scopes

Variables declared in if/else blocks are scoped to that block:

1func scoped() -> i32 {2    val x: i32 = 103    if true {4        val y: i32 = 20  // y only exists in this block5        // Both x and y are accessible here6    }7    // Only x is accessible here8    // return y  // Error: y not in scope9    return x10}

Nested If Statements

1func nested(a: i32, b: i32) -> i32 {2    if a > 0 {3        if b > 0 {4            return a + b5        } else {6            return a - b7        }8    } else {9        if b > 0 {10            return b - a11        } else {12            return 013        }14    }15}

While Loops

Use while to repeat a block while a boolean condition is true:

1while condition {2    // loop body3}

While Requirements

Loop conditions must be boolean expressions:

1mut i: i32 = 02while i < 10 {3    i = i + 14}5 6// Invalid7// while 42 { }  // Error: expected bool condition

prefer-loop-over-while-true lint

while true { ... } compiles and runs, but the compiler emits a warning:

1warning[prefer-loop-over-while-true] at 23..27: `while true { ... }` should2be written as `loop { ... }`; silence with `@allow(prefer_loop_over_while_true)`3on the enclosing function

The motivation is style, not safety; both forms produce identical machine code. To silence the warning on a function (typically when transcribing code from C, Python, or JavaScript), attach the @allow attribute:

1@allow(prefer_loop_over_while_true)2func main() -> i32 {3    mut i: i32 = 04    while true {5        if i == 7 { break }6        i = i + 17    }8    return i9}

The lint only triggers on the bare literal true. Parenthesised while (true) { ... } is treated as an explicit escape hatch and is not flagged. The recommended replacement is the loop { ... } statement below.

Loop (Infinite)

Use loop for an infinite loop. Unlike while, it has no condition: the only way out is a break, and continue re-enters the body from the top. This is the canonical infinite-loop form the prefer-loop-over-while-true lint suggests.

1mut attempts: i32 = 02loop {3    attempts = attempts + 14    if attempts > 5 {5        break6    }7}

break and continue behave exactly as they do in while and for bodies.

Loop as a value expression

Because blocks are expressions, a loop can produce a value: break v exits the loop and makes v the value of the whole loop expression.

1mut i: i32 = 02val first_even = loop {3    i = i + 14    if i % 2 == 0 {5        break i          // the loop expression evaluates to i6    }7}

All value-carrying breaks for one loop must agree on type. With a label, break outer value carries the value out of an outer loop, and the labeled loop may itself be used in value position (val x = outer: loop { ... }).

Only loop can yield a value: it is the one loop guaranteed (by the absence of a fall-through exit) to leave solely via a break. while and for always evaluate to unit (), so a break value targeting one is a compile error.

For Loops

Use for to iterate over an integer range. Ranges can be exclusive (..) or inclusive (..=):

1// Exclusive range: 0, 1, 2, ..., 92for i in 0..10 {3    // i takes values 0 through 94}5 6// Inclusive range: 1, 2, ..., 57for j in 1..=5 {8    // j takes values 1 through 59}

For-Range Requirements

• Range bounds must be integer-compatible expressions.
• The iteration variable is implicitly declared and its type is inferred from the range bounds.

1func sum_first_five() -> i32 {2    mut sum: i32 = 03    for i in 0..=5 {4        sum = sum + i // 0 + 1 + 2 + 3 + 4 + 5 = 155    }6    return sum7}

Iterating with a Position — .enumerate()

A for head may bind a pair instead of a single variable when the iterable ends in .enumerate(). The first binding is the position — a u64 counting from zero — and the second is the element:

1val scores: [i32; 3] = [5, 4, 3]2 3for (place, score) in scores.enumerate() {4    println("place {place} scored {score}")5}

The position is a u64 because that is what an index expression and .len() use, so it reads back into the sequence it walks without a cast:

1for (i, score) in scores.enumerate() {2    val same = scores[i] == score      // true, every iteration3}

.enumerate() applies to a fixed-size array, a Vec<T>, a borrow of either, and a range. A range must be parenthesised, because .. binds looser than a method call — 0..n.enumerate() would enumerate n:

1for (step, value) in (10..13).enumerate() {2    // step: 0, 1, 2   value: 10, 11, 123}

The position is a count of iterations, not a value the sequence holds — which is why the two columns above differ.

The pair head and .enumerate() imply each other: a pair head over a plain iterable, or .enumerate() under a single-variable head, is a parse error. Both bindings live in the loop's own scope, so they shadow any outer name of the same spelling for the loop's duration and disappear at its exit; naming them alike (for (i, i) in ...) is a redefinition error rather than a shadow.

The iteration protocol

for is not limited to the built-in sequences. for x in e means:

1. call e.into_iter() once, producing an iterator;
2. call .next() on that iterator repeatedly;
3. bind each Some(v) to the loop variable and run the body;
4. stop when .next() answers None.

Two prelude traits state the contract, so no import is needed:

1trait Iterator {2    type Item3    func next(&mut self) -> Option<Self::Item>4}5 6trait IntoIterator {7    type Item8    type Iter9    func into_iter(self) -> Self::Iter10}

Any type implementing either one may stand in a for head. A type that implements Iterator is its own iterator — no second IntoIterator impl is needed, and the loop uses the value directly:

1@derive(Copy, Clone)2struct Countdown { remaining: i32 }3 4impl Iterator for Countdown {5    type Item = i326 7    func next(&mut self) -> Option<i32> {8        if self.remaining <= 0 { return Option::None }9        self.remaining = self.remaining - 110        Option::Some(self.remaining)11    }12}13 14val c = Countdown { remaining: 3 }15for n in c {16    println("{n}")          // 2, 1, 017}

Implement IntoIterator when the container and the cursor are different types — which is what lets a container be walked more than once, since each for head asks it for a fresh cursor.

The loop variable's type is the Item the iterator's own impl Iterator bound, break and continue work as they do in any other loop (a label lands on the for and reaches out of a nested one), and .enumerate() applies here too, its position counting the loop's own steps.

Adapters. An adapter is an iterator that wraps another one, so it composes in a single for head. The Iterator<Item = T> bound on its type parameter is what lets its body call .next() on what it holds:

1@derive(Copy, Clone)2struct Doubling<S> { inner: S }3 4impl<S: Iterator<Item = i32>> Iterator for Doubling<S> {5    type Item = i326 7    func next(&mut self) -> Option<i32> {8        match self.inner.next() {9            Option::Some(v) => Option::Some(v * 2),10            Option::None => Option::None11        }12    }13}14 15val doubled = Doubling { inner: Countdown { remaining: 3 } }16for n in doubled {17    println("{n}")          // 4, 2, 018}

Nothing between the source and the loop is materialized: each step pulls one element through the whole chain.

What is not covered. The built-in heads — a range, a fixed-size array, a Vec<T>, a borrowed slice — do not go through the protocol. They compile to counted loops directly, which is a lowering choice, not a difference in meaning.

Adapter methods — .map(f) and .filter(p)

A for head may end in a chain of .map(f) / .filter(p) calls, which need no adapter type of their own:

• .map(f) replaces each element with f(element);
• .filter(p) drops each element for which p(element) is false.

1for value in [1, 2, 3, 4].map(|x: i32| -> i32 { x * 2 }) {2    println("{value}")        // 2, 4, 6, 83}4 5for value in (0..12).filter(|x: i32| -> bool { x % 4 == 0 }) {6    println("{value}")        // 0, 4, 87}

The chain runs left to right — a filter sees what the map before it produced — and composes to any depth. Each element is pulled through the whole chain one at a time; nothing in between is materialized:

1for value in [1, 2, 3, 4, 5]2    .map(|x: i32| -> i32 { x * x })3    .filter(|x: i32| -> bool { x > 4 }) {4    println("{value}")        // 9, 16, 255}

.map may change the element type, so the loop binding is whatever the function returns. The function is an ordinary expression of function type — usually a closure literal — evaluated once, before the loop, in the scope around it: it cannot name the binding it feeds, and a closure binding used by a head is still usable afterwards.

Like .enumerate(), these apply to every head: a range (parenthesised), a fixed-size array, a Vec<T>, a borrow of either, and any type that implements IntoIterator or Iterator. .enumerate() stays outermost, and its position counts what the chain yielded — so it stays dense however much a filter drops:

1for (rank, value) in [10, 3, 20, 4, 30].filter(|x: i32| -> bool { x >= 10 }).enumerate() {2    println("{rank}: {value}")     // 0: 10   1: 20   2: 303}

A .filter predicate must return bool and a .map function must return a value; a function that does not take the element type is rejected where the head is written.

Head form, not a value. .map / .filter are part of the for head, exactly as .enumerate() is — val m = xs.map(f) is not a method call that resolves. Write the adapter type, as above, when the pipeline has to be stored or returned.

Walking text — .chars() and .char_indices()

A string is UTF-8, so its characters are not its bytes. .chars() is an ordinary iterator over Unicode scalar values and stands in a for head like any other, with .enumerate() and the adapters composing over it. .char_indices() is the second pair-yielding head form: it binds the byte offset of each scalar beside it, which is the offset .slice(range) takes.

1for c in "héllo".chars() { }                       // 5 scalars, 6 bytes2 3for (offset, c) in "héllo".char_indices() {4    // offset: 0, 1, 3, 4, 5 — 'é' occupies two bytes5}

A .char_indices() head binds a pair and only a pair, and it takes no .enumerate() and no adapters: it already carries a position. See types for the method surface behind both.

Break and Continue

Use break to exit the nearest loop and continue to skip to the next iteration:

1while condition {2    if should_stop {3        break4    }5 6    if should_skip {7        continue8    }9 10    // normal loop body work11}

Break/Continue Requirements

Both statements are only valid inside loops:

1func valid() -> i32 {2    mut i: i32 = 03    while i < 10 {4        i = i + 15        if i == 5 {6            break7        }8    }9    return i10}11 12// Invalid13// func invalid() -> i32 {14//     break      // Error: break used outside of a loop15//     return 016// }

Loop Labels

A for, while, or loop may be prefixed with a label, an identifier followed by a colon (outer:). break label and continue label then target the labeled loop rather than the innermost one, so an inner loop can exit or re-enter an outer loop directly:

1func count() -> i32 {2    mut total: i32 = 03    outer: for i in 0..5 {4        for j in 0..5 {5            total = total + 16            if i + j >= 3 {7                break outer       // exits BOTH loops8            }9        }10    }11    return total12}

continue label re-enters the labeled loop's next iteration:

1outer: for i in 0..3 {2    for j in 0..3 {3        if j == 1 {4            continue outer        // skip to the outer loop's next i5        }6    }7}

A label on break / continue must name an enclosing loop; an unknown label is a compile error (use of undefined loop label).

Examples

Range Check

1func in_range(x: i32, min: i32, max: i32) -> bool {2    if x >= min && x <= max {3        true4    } else {5        false6    }7}

Maximum of Three

1func max3(a: i32, b: i32, c: i32) -> i32 {2    if a >= b && a >= c {3        a4    } else if b >= c {5        b6    } else {7        c8    }9}

Grade Calculator

1func letter_grade(score: i32) -> i32 {2    if score >= 90 {3        return 4  // A4    } else if score >= 80 {5        return 3  // B6    } else if score >= 70 {7        return 2  // C8    } else if score >= 60 {9        return 1  // D10    } else {11        return 0  // F12    }13}

Best Practices

Prefer Early Returns

1// Good: early returns2func process(x: i32) -> i32 {3    if x < 0 {4        return 05    }6    if x > 100 {7        return 1008    }9    return x * 210}11 12// Less clear: nested conditions13func process_nested(x: i32) -> i32 {14    if x >= 0 {15        if x <= 100 {16            return x * 217        } else {18            return 10019        }20    } else {21        return 022    }23}

Simplify Boolean Conditions

1// Good: direct boolean return2func is_positive(x: i32) -> bool {3    x > 04}5 6// Unnecessary: explicit true/false7func is_positive_verbose(x: i32) -> bool {8    if x > 0 {9        return true10    } else {11        return false12    }13}

Pattern Matching

match selects a branch by deconstructing a value, and is itself an expression. The first arm whose pattern matches (and whose optional if guard holds) runs:

1func classify(n: i32) -> i32 {2    match n {3        0            => 1,        // literal4        1 | 2        => 2,        // or-pattern5        3..=9        => 3,        // inclusive range6        n if n < 0   => 4,        // bare binding + guard7        _            => 9         // wildcard8    }9}

An arm body is an expression, and may also be a bare return, break, or continue — the statement that leaves the enclosing function or loop instead of producing a value for the arm:

1func first_even(limit: i32) -> i32 {2    mut i: i32 = 03    loop {4        i = i + 15        match i % 2 {6            0 => break i,7            _ => continue8        }9        if i > limit { return 0 - 1 }10    }11}

Enum variants deconstruct and bind their payloads (E::Tuple(a), E::Struct { field }). A match must be exhaustive. See Expressions → Match Expressions for the full pattern grammar, exhaustiveness rules, and current Phase-1E limits.

val-else, Unwrap or Leave the Scope

val PATTERN = value else { ... } binds a refutable pattern and hands the failure to an else branch. The bindings are live for the rest of the enclosing block, not just one arm, which is what makes it the straight-line alternative to a match whose success arm would otherwise swallow the whole function:

1func doubled_or_error(raw: i32) -> i32 {2    val Result::Ok(value) = parse(raw) else |err| { return err }3    value + 1        // `value` is in scope from here on4}

The else branch must exit the scope: return, break, continue, panic(...), or unreachable(). A branch that can fall through is rejected, so the binding is guaranteed initialized on the path that continues:

The else |binding| form

Writing else |name| after else binds the value the failure carried. This is a dedicated val-else production, not a closure literal. What name refers to is decided by the scrutinee's type:

Option and Result have exactly one "other" variant, so the payload to unwrap is unambiguous. A general enum has several, so |name| hands back the whole value and the branch discriminates further:

1func area(s: Shape) -> i32 {2    val Shape::Circle { radius } = s else |other| {3        match other {4            Shape::Square(side) => { return side * side },5            _ => { return 0 }6        }7    }8    radius * 39}

Naming an Option's binding is rejected, since there is nothing to name:

Because break counts as leaving the scope, val-else is also the natural drain loop:

1loop {2    val Option::Some(v) = next(i) else { break }3    total = total + v4    i = i + 15}

Runnable program: examples/control_flow/val_else.nr.

References

• Expressions - Boolean expressions
• Operators - Comparison and logical operators
• Variables - Variable scope in blocks