Skip to main content

Functions and annotations

Inferred functions​

A function without annotations gets the mutability it needs, and is generalized over the rest, like over any type:

fn size(xs) = array_len(xs); // fn([a]) -> i32
fn fill(xs: [i32], x) { xs[0] = x; } // error: `xs` isn't `mut`
fn fill(xs: mut [i32], x) { xs[0] = x; } // fn(mut [i32], i32) -> ()

size is generalized over the mutability of its argument, ∀μ α. Array[μ,α]→i32\forall \mu\, \alpha.\ \mathsf{Array}[\mu, \alpha] \to \mathsf{i32}, and that's shown as [a]. It takes arrays of either mutability, which makes its argument read-only in its body, not unchanging: a mut array can still be changed during the call through another name for it, like by a closure that the caller passed too. Only imm promises that nothing changes it. fill needs a mut array, since it changes its argument. Instantiating a scheme gives a fresh mutability, so each call can pass a different kind of array.

Indexing goes through the prelude's classes, so a function that indexes an argument whose type it doesn't know is generic over the class instead: fn first(xs) = xs[0] is forall a. Index[a] => fn(a) -> a.Item, and fn set(xs, x) { xs[0] = x; } is forall a. IndexMut[a] => fn(a, a.Item). The impl IndexMut[mut [T]] only covers mut arrays, so set([1], 2) is an error.

A field of a value whose type isn't known is a field constraint. One that's assigned to says so, and needs a mut struct once the type is known:

fn move_x(p) { p.x = 5; } // forall a. mut a.x: i32 => fn(a) -> ()

move_x(mut Point { x: 1, y: 2 }); // fine
move_x(Point { x: 1, y: 2 }); // error: a field of an `imm Point` is changed here

Annotations​

A type needs mut or imm to be fixed, and a value asks for its mutability with mut. [T] and Point in a function's parameters, without mut or imm, leave the mutability to inference, like a type that isn't written: the body decides it.

fn sum(xs: [i32]) -> i32 = xs[0]; // fn(xs: [i32]) -> i32
fn push_one(xs: [i32]) { xs[0] = 1; } // fn(xs: mut [i32]) -> ()
fn pick(c: Bool, a: Money, b: Money) -> Money = if c { a } else { b };
// fn(c: Bool, a: 'm Money, b: 'm Money) -> 'm Money
fn both(a: Money, b: Money) = [a, b]; // fn(a: imm Money, b: imm Money) -> ...

sum only reads xs, so nothing decides its mutability, and it's generalized: sum takes both kinds of array. push_one changes xs, so it takes a mut one, and pick gives back one of its arguments, so they have one mutability. both puts its arguments in an imm array, which can only hold imm values.

mut, imm and a named mutability like 'm fix a mutability, as a written type fixes a type, and the body must fit it:

fn keep(xs: imm [i32]) { xs[0] = 1; } // error: can't change imm [i32]
fn named(xs: 'm [i32]) -> i32 { let w = [xs]; 0 }
// error: 'm [i32] isn't at most imm

A parameter that a function only reads doesn't stay the same while the function runs: the caller may have a mut name for it. imm is for code that relies on a value never changing, like a cache keyed by it, or the reactive design deciding that something can't change.

Programs lay out their mutabilities like their types. A function whose signature writes every type and every mutability is declared: its type doesn't depend on its body, so a change to the body can't change what its callers may pass, and the checker doesn't check them again. A lint that writes the inferred mutabilities into a signature is #437.

A function whose type can't come from its body, like a method of a class or an impl, or a function without a body, has no body to decide an unwritten mutability. There it's a hidden parameter of the function, which the caller chooses:

#[link(wasm, module = "env", name = "len")]
fn len(xs: [i32]) -> i32; // takes both kinds

In a let annotation, [T] is an inference variable, which the value decides:

let a: [i32] = mut [1]; // `mut [i32]`
let b: [i32] = [1]; // `imm [i32]`

Return types​

Like those of the parameters, the body decides the mutabilities that a return type doesn't say:

fn primes() -> [i32] = [2, 3, 5]; // `fn() -> imm [i32]`
fn buffer() -> [u8] = mut [0; 1024]; // `fn() -> mut [u8]`
fn next(n: Node) -> Node = n.next; // the mutability of `n`
fn fixed() -> imm [i32] = mut []; // error: expected `imm [a]`, found `mut [a]`

To return such a value as imm, a body says so with imm, as in imm mut []. That's a copy, which Conduit's region analysis (Conduit) can leave out when nothing else has the value.

next returns what it's given, so its result has its argument's mutability: next(a) is a mut Node for a mut Node a, and an imm Node for an imm one.

That makes the signature incomplete: such a function is inferred, not checked on its own, so editing its body checks its callers again. Writing mut, imm or a name in the return type makes it complete: fn next(n: 'm Node) -> 'm Node says what the body of next would decide, and is checked on its own. A function without a body, like a class method, has no body to decide, so its return type is imm where it doesn't say.

The type of a const and an array or struct in a where predicate, like the [T] of where Show[[T]], are imm too.

An impl gets hidden parameters like a function: impl Size[Point] is for points of either mutability, and impl Size[mut Point] only for those that can be changed.

Type aliases​

A type alias doesn't decide what [T] or Point means in it: the type it's used in does. With type Ints = [i32], fn sum(xs: Ints) takes either kind of array, and mut Ints is mut [i32].