Function references
A top-level function is a value: you can keep one in a variable, a field or an array, return it from a function, pass it on, call it later and compare two of them. Such a value is a function reference. It names a function you declared at the top level of a module and nothing more, so it carries no captured variables. The normative rules are in the reference's Function references section.
Keeping a function in a field
Give the function type a name with type, and use it like any other type:
type Op = (x: i32) => i32;
const double = (x: i32): i32 => x * 2;
const negate = (x: i32): i32 => 0 - x;
class Stage {
op: Op;
constructor(op: Op) {
this.op = op;
}
run(x: i32): i32 {
return this.op(x);
}
}
export const main = (): i32 => {
const s = new Stage(double);
console.log(`${s.run(5)}`); // 10
s.op = negate;
console.log(`${s.run(5)}`); // -5
return 0;
};
new Stage(double) names double without calling it, and this.op(x) calls
whichever function the field holds at that moment.
Arrays, returns and comparison
A reference goes anywhere a value of its type can: a local, a field of a
class or an interface, an array element, a return value, and a parameter
whose type is the alias, of a function, a method or a constructor. You call
it with the usual syntax, h(3) or this.op(4), or call an element in place
as below, and === and !== tell you whether two references name the same
function:
type Step = (x: i32) => i32;
const inc = (x: i32): i32 => x + 1;
const square = (x: i32): i32 => x * x;
const half = (x: i32): i32 => x / 2;
const pick = (name: string): Step => {
if (name === "inc") {
return inc;
}
return square;
};
export const main = (): i32 => {
const steps: Step[] = [inc, square];
steps.push(half);
let x = 3;
for (const step of steps) {
x = step(x);
}
console.log(`${x}`); // 8
console.log(`${steps[1](7)}`); // 49
const s = pick("inc");
console.log(`${s(1)}`); // 2
console.log(`${s === inc}`); // true
console.log(`${s !== square}`); // true
return 0;
};
A reference has no empty value, so a variable of a function type is
initialised where it is declared, and an array of them is built from [] or
a literal and push (fill, unshift and splice are not available on
it). new Array<Op>(n), which would fill the array with zeros, is refused:
type Op = (x: i32) => i32;
export const main = (): i32 => {
const ops = new Array<Op>(4);
return ops.length;
};
What a reference can name
A reference names a function declared at the top level of a module, with
const f = (...) => ... or function f(...). These cannot be referenced,
and naming one where a value is expected is an error:
-
a generic function (
NL2725), anasyncfunction (NL2727), a function declared in C (NL2728), a function with a rest parameter (NL2729), and a function that takes a function parameter (NL2726); -
a function that takes a
MutexGuard(NL2739): a guard goes only to a helper named at the call; -
a function type with a rest, optional or defaulted parameter, such as
(x: i32, y?: i32) => i32(NL2729): a call through a reference passes every parameter; - a method,
c.step, which needs its object (NL2732); -
an arrow written inside a function. One that reads a variable of the
function around it would need to carry that variable with it, which a
reference cannot (
NL2731); one that reads nothing is refused too (NL2336): declare it at the top level and name it.
export const main = (): i32 => {
const k = 3;
const addK = (x: i32): i32 => x + k;
return addK(1);
};
Pass k as an argument instead, or, when the function is only handed to
another function, write the arrow at that call; there it may read k
(Passing a function to a function).
What a reference does
A reference is called, compared, stored and passed, and nothing else. In particular it cannot be printed or put in a template string, because a native program has no source text to show for it:
type Op = (x: i32) => i32;
const inc = (x: i32): i32 => x + 1;
export const main = (): i32 => {
const f: Op = inc;
console.log(`${f}`);
return 0;
};
It cannot be ordered with <, joined or encoded as JSON; store an index or
an enum beside it when you need one of those.
A reference that may be null
Op | null holds a function or nothing. A field of that type starts as
null, and new Array<Op | null>(n) holds n of them. Call it only after a
test proves it holds a function; a nullable field is read into a const
first, and the test is on the const:
type Op = (x: i32) => i32;
const inc = (x: i32): i32 => x + 1;
class Slot {
op: Op | null = null;
}
export const main = (): i32 => {
const s = new Slot();
s.op = inc;
const h = s.op;
if (h !== null) {
console.log(`${h(4)}`); // 5
}
return 0;
};
?? gives a function in place of null, as in const f: Op = s.op ?? inc.
A call with no test before it is refused (NL2758):
type Op = (x: i32) => i32;
export const run = (h: Op | null): i32 => h(1);
export const main = (): i32 => run(null);
In a Map
A Map value can be a reference, an array of them, or a nullable of either.
A call through what get returns can reach every function of that type that
any Map or array in the program holds, so it is a choice among all of them:
type Op = (x: i32) => i32;
const inc = (x: i32): i32 => x + 1;
const dec = (x: i32): i32 => x - 1;
export const main = (): i32 => {
const byName = new Map<string, Op>();
byName.set("inc", inc);
byName.set("dec", dec);
const f = byName.get("dec");
if (f !== undefined) {
console.log(`${f(5)}`); // 4
}
return 0;
};
If one of those functions keeps an argument and another does not, a call
through get is refused (NL2736): call the one that keeps it by name, or
hold it in a variable or field of its own and do not also store it in the
Map, so the compiler follows it apart from the Map's values.
A reference cannot be a Map key.
Not in a Result
A reference cannot sit directly in a Result, in either arm, nullable or not:
Result<Op, string> is refused (NL2762). Return an array of references
(Result<Op[], string>), or a class with a reference field, instead:
type Op = (x: i32) => i32;
const plus1 = (x: i32): i32 => x + 1;
const pick = (): Result<Op[], string> => Ok([plus1]);
export const main = (): void => {
const r = pick();
if (r.ok) {
const f = r.value[0];
console.log(`${f(10)}`);
}
};
As a function argument
A parameter whose function type is written out in the parameter list, as in
apply below, takes a function's name, an arrow, or a variable holding a
reference. The call passes an arrow that calls the reference:
type F = (x: i32) => i32;
const apply = (f: (x: i32) => i32, x: i32): i32 => f(x);
const inc = (x: i32): i32 => x + 1;
export const main = (): i32 => {
const h: F = inc;
console.log(`${apply(h, 1)}`); // 2
return 0;
};
A field or array element is refused (NL2759): the arrow would read it
again each time the callee calls it, where JavaScript reads it once. Read it
into a const first and pass the const, as in const op = ops[0] then
apply(op, 1). A variable that may be null is passed once a test such as
h !== null has narrowed it (NL2760). And a variable that a later
argument of the same call assigns, as in apply(h, k((h = inc))), is
refused (NL2761): the call would read it after that assignment, where
JavaScript reads it before; read it into a const first.
The builtins that check the body they are handed, such as parallelMap, a
scope's spawn, expose and region, take only a function's name or an
arrow (NL2734).
Calls through a reference
A call through a reference compiles to a choice among the functions that
variable, field or array can hold, followed by an ordinary direct call: there
is no function pointer. When only one function can reach it, there is no
choice to make. More than eight is a warning (NL9017), because that call is
then a branch over all of them where a direct call would not branch.
Built with --profile debug, a call through a reference also checks that
the reference holds one of those functions, and panics if it does not.
Under a debugger, a program built with -g prints a reference as the
function it holds. Stepping into a call through one takes two steps: the
first stops in the generated chooser, named $ref. and the call's signature,
the second in the function. To step straight through, tell gdb to skip the
choosers:
(gdb) skip -rfu '^\$ref\.'
A reference stays inside your program. A library built with -o cannot
export a function whose parameter or return type holds one, or whose
classes have a field of one, because code outside the program could hand back a value
that names no function (NL2733). A program built from several modules
together with --link may pass references between them.

