Skip to main content

Mutability

mut on a variable only means it can be assigned again, as in Values and variables. Whether an array, a struct or a closure can be changed is something else: it's up to the value itself, and it's part of its type. This page shows how.

Arrays​

An array can't be changed, unless it's made with mut:

let scores = mut [0, 0, 0];
scores[1] = 10;
scores;
[0, 10, 0]

Changing an element of an array made without mut is an error:

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

The type of an array says which kind it is: primes is imm [i32], and scores is mut [i32]. A function that takes [i32] and only reads it takes both. One that changes its argument only takes a mut array: Bolt infers that, like a type you don't write, but it's clearer to write mut [i32]. A parameter written imm [i32] can't be changed.

Arrays are shared​

Arrays are shared: let b = a makes another name for the same array, not a copy, so a change through one name shows through the other. A function that's given an array can change it the same way:

fn fill(xs: mut [i32], x: i32) {
xs[0] = x;
xs[1] = x;
}

let a = mut [0, 0, 0];
let b = a;
fill(b, 7);
a;
[7, 7, 0]

let mut has nothing to do with this: it only means the variable can be given another value later.

[value; count] evaluates value once, so mut [mut [0, 0]; 2] holds the same row twice.

A function that can't change an array doesn't make it unchanging, though. If the array is mut, something else can still change it while the function runs, through another name for it:

fn total(xs: [i32], f: fn()) -> i32 {
let before = xs[0];
f();
before + xs[0]
}

let xs = mut [1];
total(xs, || { xs[0] = 100; });
101

total can't change xs, but the function it's given can. Only an imm array is sure never to change: a function that counts on that takes imm [i32].

Structs​

A struct can't be changed either, unless it's made with mut. Then change a field by assigning to it:

struct Point { x: i32, y: i32 }

let p = mut Point { x: 0, y: 0 };
p.x = 5;
p;
Point { x: 5, y: 0 }

Like for arrays, the type says which kind a struct is: p is mut Point, and Point { x: 0, y: 0 } alone is imm Point. A function that takes Point takes both, and can't change them. What an imm struct holds can't be changed either: its fields are imm too.

A struct whose values never change, like the prelude's String, can be declared imm struct. Then it's always imm, so its type has no mutability at all: String means the same wherever it's written, and mut String is an error.

imm struct Name(String);

fn greet(n: Name) -> String = "hello, " <> n.0;

greet(Name("Bolt"));
"hello, Bolt"

Structs are shared like arrays: let q = p makes another name for the same struct, and a function that takes mut Point can change the one it's given:

struct Point { x: i32, y: i32 }

fn shift(p: mut Point) { p.x += 1; }

let p = mut Point { x: 0, y: 0 };
let q = p;
shift(q);
p;
Point { x: 1, y: 0 }

Closures​

A closure that can change what it uses is a mut fn. Like a mut array, it can only be held by something that's mut too, since what an imm value holds never changes:

struct Counter { tick: fn() }

let mut count = 0;
let c = mut Counter { tick: || { count += 1; } }; // without `mut`, an error
(c.tick)();
(c.tick)();
count;
2

Generic functions​

A generic function must work for every type, and that includes types that can change, like mut [i32]. So a generic function can't put a T in something that never changes, like an imm array, unless it says that T never changes either, with the bound T: imm:

fn twice[T: imm](x: T) -> imm [T] = [x, x];

twice([1, 2]);
[[1, 2], [1, 2]]

Then calling it with something that can change is an error:

fn twice[T: imm](x: T) -> imm [T] = [x, x];

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

Copies​

To get a copy instead of another name for the same value, use to_mut, for one you can change, or to_imm, for one that never changes, even when the original does:

let primes = [2, 3, 5];
let mine = to_mut(primes);
mine[0] = 1;
let snapshot = to_imm(mine);
mine[1] = 4;
(primes, mine, snapshot);
([2, 3, 5], [1, 4, 5], [1, 3, 5])

imm before an expression makes a copy that never changes of everything in it: the arrays and structs it holds are copied too, and what's already imm is shared as it is. It's how a value that's built step by step ends up imm:

let squares = imm {
let xs = mut [0; 4];
xs[1] = 1;
xs[2] = 4;
xs[3] = 9;
xs
};
squares;
[0, 1, 4, 9]

squares is an imm [i32]. A closure can't be copied, so imm of one that changes something, which is mut, is an error.

In a generic function, the copy of a T is an imm T: whatever T is, with every array and struct in it imm. When T is already imm, as with the bound T: imm, imm T is just T:

fn snapshot[T](x: T) -> imm T = imm x;
let frozen = snapshot(mut [mut [1, 2]]); // imm [imm [i32]]

to_mut only copies the value itself: what it holds is shared with the original. To copy all of it, so that every array and struct in it can be changed, use to_mut_deep:

let grid = [[0, 0], [0, 0]];
let editable = to_mut_deep(grid);
editable[0][1] = 1;
(grid, editable);
([[0, 0], [0, 0]], [[0, 1], [0, 0]])

The other way, to_imm_deep gives a copy that can't be changed all the way down, even when the original holds arrays that can:

let rows = mut [mut [1, 2], mut [3]];
let frozen = to_imm_deep(rows);
rows[0][0] = 9;
frozen[0][0];
1

Each type says how it's copied with an impl of ToImmDeep, as with ToMutDeep: a Vec copies only its elements. A type of your own gets one the same way, and a value that holds a function has none, since a closure can't be copied. imm copies with that impl too, so a type of your own needs one before imm can copy it, unless it holds nothing that can be changed.

Reading without changing​

A function that only reads an array can take one of either mutability, when its parameter is ro, for read-only:

fn total(xs: ro [i32]) -> i32 = xs[0] + xs[1];

let scores = mut [3, 4];
let fixed = [10, 20];
(total(scores), total(fixed));
(7, 30)

Nothing can be changed through a ro value, and that's deep: the arrays and structs it holds are ro too.

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

ro isn't imm: a ro array can still be changed by someone else, who has it as mut. So an imm value can't hold a ro one, and to keep it, make an imm copy:

fn keep(xs: ro [i32]) = [xs];
[E0223] Error: an `imm [ro [i32]]` can't hold a `ro [i32]`: what an `imm` value holds can't be changed either
fn freeze(xs: ro [i32]) -> imm [i32] = imm xs;

let xs = mut [1, 2];
let frozen = freeze(xs);
xs[0] = 9;
frozen;
[1, 2]

A ro result can be one of the values it was given, whatever their mutability:

struct Money { cents: i32 }

fn larger(a: ro Money, b: ro Money) -> ro Money = if a.cents > b.cents { a } else { b };

let wallet = mut Money { cents: 5 };
let price = Money { cents: 7 };
larger(wallet, price).cents;
7

In a generic function, a ro T is a T seen as ro. Any T can be used as one, but not the other way, so what's read through a ro [T] is a ro T:

fn first[T](xs: ro [T]) -> ro T = xs[0];

(first(mut [1, 2]), first([3]));
(1, 3)
fn leak[T](xs: ro [T]) -> T = xs[0];
[E0201] Error: expected `T`, found `ro T`

Mutability in the advanced part goes on with values that hold other values, generic functions and closures. The internals explain how the checker does it.