while

while

A while loop is used to repeatedly execute an expression until some condition is no longer true.

while.zig

const assert = @import("std").debug.assert;
test "while basic" {
    var i: usize = 0;
    while (i < 10) {
        i += 1;
    }
    assert(i == 10);
}

$ zig test while.zig
Test 1/1 while basic...OK
All tests passed.

Use break to exit a while loop early.

while.zig

const assert = @import("std").debug.assert;
test "while break" {
    var i: usize = 0;
    while (true) {
        if (i == 10)
            break;
        i += 1;
    }
    assert(i == 10);
}

$ zig test while.zig
Test 1/1 while break...OK
All tests passed.

Use continue to jump back to the beginning of the loop.

while.zig

const assert = @import("std").debug.assert;
test "while continue" {
    var i: usize = 0;
    while (true) {
        i += 1;
        if (i < 10)
            continue;
        break;
    }
    assert(i == 10);
}

$ zig test while.zig
Test 1/1 while continue...OK
All tests passed.

While loops support a continue expression which is executed when the loop is continued. The continue keyword respects this expression.

while.zig

const assert = @import("std").debug.assert;
test "while loop continue expression" {
    var i: usize = 0;
    while (i < 10) : (i += 1) {}
    assert(i == 10);
}
test "while loop continue expression, more complicated" {
    var i: usize = 1;
    var j: usize = 1;
    while (i * j < 2000) : ({ i *= 2; j *= 3; }) {
        const my_ij = i * j;
        assert(my_ij < 2000);
    }
}

$ zig test while.zig
Test 1/2 while loop continue expression...OK
Test 2/2 while loop continue expression, more complicated...OK
All tests passed.

While loops are expressions. The result of the expression is the result of the else clause of a while loop, which is executed when the condition of the while loop is tested as false.

break, like return, accepts a value parameter. This is the result of the while expression. When you break from a while loop, the else branch is not evaluated.

while.zig

const assert = @import("std").debug.assert;
test "while else" {
    assert(rangeHasNumber(0, 10, 5));
    assert(!rangeHasNumber(0, 10, 15));
}
fn rangeHasNumber(begin: usize, end: usize, number: usize) bool {
    var i = begin;
    return while (i < end) : (i += 1) {
        if (i == number) {
            break true;
        }
    } else false;
}

$ zig test while.zig
Test 1/1 while else...OK
All tests passed.

Labeled while

When a while loop is labeled, it can be referenced from a break or continue from within a nested loop:

test.zig

test "nested break" {
    outer: while (true) {
        while (true) {
            break :outer;
        }
    }
}
test "nested continue" {
    var i: usize = 0;
    outer: while (i < 10) : (i += 1) {
        while (true) {
            continue :outer;
        }
    }
}

$ zig test test.zig
Test 1/2 nested break...OK
Test 2/2 nested continue...OK
All tests passed.

while with Optionals

Just like if expressions, while loops can take an optional as the condition and capture the payload. When null is encountered the loop exits.

When the |x| syntax is present on a while expression, the while condition must have an Optional Type.

The else branch is allowed on optional iteration. In this case, it will be executed on the first null value encountered.

while.zig

const assert = @import("std").debug.assert;
test "while null capture" {
    var sum1: u32 = 0;
    numbers_left = 3;
    while (eventuallyNullSequence()) |value| {
        sum1 += value;
    }
    assert(sum1 == 3);
    var sum2: u32 = 0;
    numbers_left = 3;
    while (eventuallyNullSequence()) |value| {
        sum2 += value;
    } else {
        assert(sum1 == 3);
    }
}
var numbers_left: u32 = undefined;
fn eventuallyNullSequence() ?u32 {
    return if (numbers_left == 0) null else blk: {
        numbers_left -= 1;
        break :blk numbers_left;
    };
}

$ zig test while.zig
Test 1/1 while null capture...OK
All tests passed.

while with Error Unions

Just like if expressions, while loops can take an error union as the condition and capture the payload or the error code. When the condition results in an error code the else branch is evaluated and the loop is finished.

When the else |x| syntax is present on a while expression, the while condition must have an Error Union Type.

while.zig

const assert = @import("std").debug.assert;
test "while error union capture" {
    var sum1: u32 = 0;
    numbers_left = 3;
    while (eventuallyErrorSequence()) |value| {
        sum1 += value;
    } else |err| {
        assert(err == error.ReachedZero);
    }
}
var numbers_left: u32 = undefined;
fn eventuallyErrorSequence() anyerror!u32 {
    return if (numbers_left == 0) error.ReachedZero else blk: {
        numbers_left -= 1;
        break :blk numbers_left;
    };
}

$ zig test while.zig
Test 1/1 while error union capture...OK
All tests passed.

inline while

While loops can be inlined. This causes the loop to be unrolled, which allows the code to do some things which only work at compile time, such as use types as first class values.

test.zig

const assert = @import("std").debug.assert;
test "inline while loop" {
    comptime var i = 0;
    var sum: usize = 0;
    inline while (i < 3) : (i += 1) {
        const T = switch (i) {
            0 => f32,
            1 => i8,
            2 => bool,
            else => unreachable,
        };
        sum += typeNameLength(T);
    }
    assert(sum == 9);
}
fn typeNameLength(comptime T: type) usize {
    return @typeName(T).len;
}

$ zig test test.zig
Test 1/1 inline while loop...OK
All tests passed.

It is recommended to use inline loops only for one of these reasons:

You need the loop to execute at comptime for the semantics to work.
You have a benchmark to prove that forcibly unrolling the loop in this way is measurably faster.