Skip to content

Declarations

A declaration is written as a function is, up to the result type, and stops there. This page reads the parts of a declaration that a function with a body does not have, each from a line of the standard library.

The receiver

A first parameter named self is the receiver: the value a call is made on. A declaration with a receiver is reached by a receiver call, value.f(), by a pipe, value | f, and by an ordinary call with the receiver first:

[abs(-3), (-3).abs(), -3 | abs]
[3, 3, 3]

A declaration without self takes its first argument the same way, as the value the call is made on, and is not reached by a receiver call.

Positional and named parameters

A / in a parameter list ends the parameters a call writes by position only, and a * begins the ones it writes by name only. pow is declared fn pow(self: Int, exponent: Int, /) : Int, so its exponent has no name at a call:

pow(2, 10)
1024
pow(2, exponent = 10)
check error[type-mismatch]: `pow` takes `exponent` by position: write the value without `exponent =`
 --> <expression>:1:19
  |
1 | pow(2, exponent = 10)
  |                   ^^

A parameter after * is the reverse: fn shuffle<T>(self: Seq<T>, *, seed: Int) : List<T> takes seed by name, xs.shuffle(seed = 7), and never by position. / and * are written in declarations only; a function with a body takes its arguments by position.

Defaults

A parameter with = value after its type may be left out of a call. The declaration states the default so that a reader sees it; the Rust function supplies it, since an argument a call does not write is absent when the function runs. Natives shows one.

Forms of one name

A name may be declared more than once, each line a form. A call takes the first form its receiver and arguments fit:

fn abs(self: Int) : Int
fn abs(self: Float) : Float
fn abs(self: Decimal) : Decimal
fn abs(self: Duration) : Duration
[abs(-3), abs(-1.5f).int(), abs(-2.50).int()]
[3, 1, 2]

The forms of a name share one Rust function, which reads the value it was given. A function with a body has one form.

Purity

A declaration written fn is pure: its result depends on its arguments alone, so the planner may reorder it, run it once for equal arguments, or skip it when nothing reads the result. A declaration written effectful fn runs once, where it is written. The two forms of shuffle differ in exactly this:

fn shuffle<T>(self: Seq<T>, *, seed: Int) : List<T>
effectful fn shuffle<T>(self: Seq<T>) : List<T>

With a seed the result is a function of the seed and the list. Without one the call draws from the evaluation's seed and is effectful.

Shape

A word before fn states how a backend may split the input of a call:

Word What it states
elementwise fn the result for each element depends on that element alone
partition fn the input is regrouped by a key, and the groups complete in any order
reduction fn the whole input collapses to one value through a combiner
none a barrier: the whole input is needed before any output

count is declared reduction fn count<T>(self: Collection<T>) : Int: a count of a collection is the sum of the counts of its parts.

[1, 2, 3].count()
3

Purity and shape are claims about the Rust function. The declaration states them, the extension marks its function the same way, and the two markings are compared when the package is bound (next page).