Skip to main content
Version: Zig 0.13.0

Optionals

Optionals use the syntax ?T and are used to store the data null, or a value of type T.

const expect = @import("std").testing.expect;

test "optional" {
var found_index: ?usize = null;
const data = [_]i32{ 1, 2, 3, 4, 5, 6, 7, 8, 12 };
for (data, 0..) |v, i| {
if (v == 10) found_index = i;
}
try expect(found_index == null);
}

Optionals support the orelse expression, which acts when the optional is null. This unwraps the optional to its child type.

const expect = @import("std").testing.expect;

test "orelse" {
const a: ?f32 = null;
const fallback_value: f32 = 0;
const b = a orelse fallback_value;
try expect(b == 0);
try expect(@TypeOf(b) == f32);
}

.? is a shorthand for orelse unreachable. This is used for when you know it is impossible for an optional value to be null, and using this to unwrap a null value is detectable illegal behaviour.

const expect = @import("std").testing.expect;

test "orelse unreachable" {
const a: ?f32 = 5;
const b = a orelse unreachable;
const c = a.?;
try expect(b == c);
try expect(@TypeOf(c) == f32);
}

Both if expressions and while loops support taking optional values as conditions, allowing you to "capture" the inner non-null value.

Here we use an if optional payload capture; a and b are equivalent here. if (b) |value| captures the value of b (in the cases where b is not null), and makes it available as value. As in the union example, the captured value is immutable, but we can still use a pointer capture to modify the value stored in b.

const expect = @import("std").testing.expect;

test "if optional payload capture" {
const a: ?i32 = 5;
if (a != null) {
const value = a.?;
_ = value;
}

var b: ?i32 = 5;
if (b) |*value| {
value.* += 1;
}
try expect(b.? == 6);
}

And with while:

const expect = @import("std").testing.expect;

var numbers_left: u32 = 4;
fn eventuallyNullSequence() ?u32 {
if (numbers_left == 0) return null;
numbers_left -= 1;
return numbers_left;
}

test "while null capture" {
var sum: u32 = 0;
while (eventuallyNullSequence()) |value| {
sum += value;
}
try expect(sum == 6); // 3 + 2 + 1
}

Optional pointer and optional slice types do not take up any extra memory compared to non-optional ones. This is because internally they use the 0 value of the pointer for null.

This is how null pointers in Zig work - they must be unwrapped to a non-optional before dereferencing, which stops null pointer dereferences from happening accidentally.