Skip to main content

Mutability

Mutability in the basics showed arrays and structs made with mut, which can be changed, and the others, which can't. This page is about what happens when values hold other values, like a struct with a struct in a field, and about closures.

It all comes from one rule: an imm value never changes, and neither does anything inside it. Otherwise an imm value could hold a mut one, and change after all.

Fields follow their struct​

The structs and arrays in a struct's fields can be changed exactly when the struct can:

struct Point { x: i32, y: i32 }
struct Line { a: Point, b: Point }

let l = mut Line { a: mut Point { x: 0, y: 0 }, b: mut Point { x: 1, y: 1 } };
l.a.x = 5;
l;
Line { a: Point { x: 5, y: 0 }, b: Point { x: 1, y: 1 } }

A Line made without mut holds points that can't be changed either:

struct Point { x: i32, y: i32 }
struct Line { a: Point, b: Point }

let k = Line { a: Point { x: 0, y: 0 }, b: Point { x: 1, y: 1 } };
k.a.x = 5;
[E0221] Error: a field of an `imm Point` is changed here, but only a `mut` struct can be changed

So an imm Line can't hold a mut Point:

struct Point { x: i32, y: i32 }
struct Line { a: Point, b: Point }

Line { a: mut Point { x: 0, y: 0 }, b: Point { x: 1, y: 1 } };
[E0201] Error: expected `imm Point`, found `mut Point`

A field can say imm. Then what it holds never changes, even in a mut struct, though the field can still be given another value:

struct Player { score: i32, history: imm [i32] }

let p = mut Player { score: 0, history: [] };
p.score = 10;
p.history = [3, 7];
p;
Player { score: 10, history: [3, 7] }
struct Player { score: i32, history: imm [i32] }

let p = mut Player { score: 0, history: [3, 7] };
p.history[0] = 5;
[E0221] Error: cannot change an element of `p.history`, which is `imm [i32]`; only a `mut` array can be changed

A field can't say mut, since an imm struct would then hold something that changes. To change what a field holds, make the struct mut.

Going the other way is fine: a mut value can hold imm ones. In a mut [[i32]], you can replace a row, but not change one:

let rows = mut [[1, 2], [3, 4]];
rows[0] = [5, 6];
rows;
[[5, 6], [3, 4]]
let rows = mut [[1, 2], [3, 4]];
rows[1][0] = 9;
[E0221] Error: cannot change an element of `rows[1]`, which is `imm [i32]`; only a `mut` array can be changed

Type parameters​

A generic struct like Box[T] holds whatever type it's given, so the same rule applies to what it holds. A mut box can hold something that changes:

struct Point { x: i32, y: i32 }
struct Box[T] { item: T }

let a = mut Box { item: mut Point { x: 0, y: 0 } };
a.item.x = 3;
a;
Box { item: Point { x: 3, y: 0 } }

An imm box can't:

struct Point { x: i32, y: i32 }
struct Box[T] { item: T }

Box { item: mut Point { x: 0, y: 0 } };
[E0223] Error: an `imm Box[mut Point]` can't hold a `mut Point`: what an `imm` value holds can't be changed either

Arrays are the same: [mut [1]] is an imm array holding a mut one, and that's an error too.

A tuple has a mutability, like a struct: (1, 2) can't be changed, and mut (1, 2) can, with t.0 = 3. An imm tuple can't hold anything mut either, so a tuple of a mut array is written mut (xs, 1).

An enum has no mutability of its own: it can't be changed in place, and it's neither mut nor imm. A struct or array written in a variant, like the Point of Dot(Point), is imm, since there's no mutability of the enum for it to follow. A type parameter can be anything, so an Option[mut Point] holds a point that can change. Inside an imm value, like [Option[mut Point]], that's an error, as for any other mut value.

Generic functions​

A function that puts its argument in an imm value only works for arguments that never change. Bolt works this out for you:

struct Box[T] { item: T }

fn wrap(x) = Box { item: x };

wrap(1);
Box { item: 1 }
struct Box[T] { item: T }

fn wrap(x) = Box { item: x };

wrap(mut [1]);
[E0230] Error: expected a type that's at most `imm`, found `mut [i32]`

When you write a function's types yourself, say it with T: imm, as in the basics: fn wrap[T: imm](x: T) -> imm Box[T]. The same bound works in a where clause, on an impl and on a struct.

Closures​

A closure can change the variables it uses, so it can hold state:

let mut n = 0;
let next = || { n += 1; n };
next();
next();
2

A closure like next, which can change something, is a mut fn. A closure is mut when it uses a let mut variable, even only to read it, or something that's mut: a mut array, struct or closure. Other closures are imm, and so are named functions.

Like a mut array, a mut fn can only be held by something that's mut too:

struct Holder { poke: fn() }

let xs = mut [0];
Holder { poke: || { xs[0] += 1; } };
[E0201] Error: expected `fn() -> ()`, found `mut fn() -> ()`
struct Holder { poke: fn() }

let xs = mut [0];
let h = mut Holder { poke: || { xs[0] += 1; } };
(h.poke)();
(h.poke)();
xs;
[2]

Calling a closure doesn't need it to be mut, so functions that take a function work with both kinds, without saying anything:

fn twice(f, x) = f(f(x));

let mut calls = 0;
let result = twice(|x| { calls += 1; x * 2 }, 5);
(result, calls);
(20, 2)

To ask for one kind, write mut fn() -> T or imm fn() -> T. An imm fn is usually shown as just fn.

A function that makes a closure gives it the mutability of what it captures. A closure that reads an imm array is imm, and one that reads a mut array is mut:

fn reader(xs: [i32]) = || xs[0];

let fs = [reader([1]), reader([2])];
(fs[0])() + (fs[1])();
3
fn reader(xs: [i32]) = || xs[0];

[reader(mut [1])];
[E0230] Error: expected a mutability that's at most `imm`, found `mut`

Naming a mutability​

A function that takes [i32] and only reads it takes both kinds of array. But sometimes the kinds of two arrays have to match, or a function gives back the kind it was given. Then name the mutability, with a name that starts with ', written where mut or imm would go:

fn longer(a: 'm [i32], b: 'm [i32]) -> 'm [i32] =
if array_len(a) >= array_len(b) { a } else { b };

let xs = mut [1, 2, 3];
let ys = mut [4];
let l = longer(xs, ys);
l[0] = 9;
xs;
[9, 2, 3]

'm is the same everywhere in the signature, so longer gives back an array of the kind it was given. Given two mut arrays, it gives a mut one, which you can change. Given arrays of different kinds, 'm is ro, which both can be seen as, so what it gives back can be read but not changed:

fn longer(a: 'm [i32], b: 'm [i32]) -> 'm [i32] =
if array_len(a) >= array_len(b) { a } else { b };

let l = longer(mut [1, 2], [3]);
l[0] = 9;
[E0221] Error: cannot change an element of `l`, which is `ro [i32]`; only a `mut` array can be changed

Where a mut array is expected, 'm is mut, so both arrays must be:

let k: mut [i32] = longer(mut [1, 2], [3]);
[E0201] Error: expected `mut [i32]`, found `imm [i32]`

Different names are independent of each other:

fn pair(a: 'm [i32], b: 'n [i32]) -> ('m [i32], 'n [i32]) = (a, b);

let (a, b) = pair(mut [1], [2]);
a[0] = 5;
(a, b);
([5], [2])

The caller decides what a name stands for, so it may be imm. That's why a function can't change what has a name:

fn reset(xs: 'm [i32]) { xs[0] = 0; }
[E0221] Error: cannot change an element of `xs`, which is `'m [i32]`; only a `mut` array can be changed

For the same reason, fn make() -> 'm [i32] = [1] is an error: [1] is imm, not whatever the caller asks for. To make an array of the caller's mutability, write the name before it, as you'd write mut:

fn make() -> 'm [i32] = 'm [1];
let xs = make();
xs[0] = 2; // fine: the caller asked for a `mut` array
let ys: [i32] = make();

What a literal like that holds must be at most its name, as for mut: fn wrap[T](x: T) -> 'm [T] = 'm [x] needs T: 'm.

Bolt uses names too when it shows a type. Writing [i32] twice in fn same(xs: [i32]) -> [i32] = xs doesn't link the two, but the body does, so Bolt shows same as fn('m [i32]) -> 'm [i32]. A mutability that appears only once isn't named.

Names in structs​

A struct's fields follow its own mutability. But a struct can also name a mutability for a field, after its type parameters, so that the field doesn't follow the struct. Take a cursor that moves over an array: the cursor changes, but the array doesn't have to be one that can:

struct Cursor['v] { data: 'v [i32], index: i32 }

fn start(xs: 'v [i32]) -> mut Cursor['v] = mut Cursor { data: xs, index: 0 };

let c = start([10, 20, 30]);
c.index = 2;
c.data[c.index];
30

c is a mut Cursor[imm]: its index can change, and its data can't.

struct Cursor['v] { data: 'v [i32], index: i32 }

let c = mut Cursor { data: [10, 20, 30], index: 0 };
c.data[0] = 1;
[E0221] Error: cannot change an element of `c.data`, which is `imm [i32]`; only a `mut` array can be changed

The rule from the start of this page still holds: an imm cursor can't hold an array that changes.

struct Cursor['v] { data: 'v [i32], index: i32 }

Cursor { data: mut [1], index: 0 };
[E0223] Error: an `imm Cursor[mut]` can't have a `mut` mutability argument: what an `imm` value holds can't be changed either

What this gives you​

An imm value, and everything in it, never changes, however many names it has and whatever you pass it to. So code that's given an imm value can count on it staying the same, and imm values can be shared freely, without copies.

A mut value is different: it can be shared, and any name for it can change it. Unlike Rust, Bolt doesn't stop something else from changing a mut value while you use it. That's on purpose: sharing mut values is how one part of a program changes what another part sees.

The internals explain how the checker makes sure of all this.