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.