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.