Standard library

The library is ordinary borrow-core code in lib/, checked with your program. include name brings one module into scope, together with the modules it includes itself; only what a program calls is compiled. This page lists each module’s user-facing names, and the guide chapter linked from each section teaches them.

Reading the signatures

Signatures are written as they are declared. Two conventions recur.

Hand-back functions. A function that changes or reads a value without consuming it takes the value first and returns it first: push(b: buf A, x: A) -> buf A * 1. You call it with a lend, push(&mut b, x), which moves b in, rebinds it to what comes back, and answers the rest, here (). len_of(&b) reads one the same way and answers the i32. A lend must be the whole of a let or a statement: let n = len_of(&b);.

A function that returns the value alone, with nothing after it (truncate, clear, reserve, grow, heap_push, clear_str, and the view functions that hand back an array_mut), is rebound with let: let b = truncate(b, 1);, let v = set(v, 0, x);.

Sums. T + 1 is an optional T: inl x when there is one, inr () when not. bool is 1 + 1. An Option[T] matches as Some(x) or None.

The prelude

In scope in every program, with no include.

The built-in forms (alloc, free, array_new, checked_div, div_fuel, …) are in the Language reference.

fail

The Fail effect and its handlers. Errors teaches them.

arith

Euclidean division, and the names of division’s error. / and % raise Fail[DivError] with no include; include arith adds the rest. Division teaches them.

include textio
include arith

-- The minute within its hour of `m` minutes after midnight, which may be negative.
fn minute(m: i32) -> i32 = rem_euclid(m, 60)

main -> 1 =
  print_dec(minute(0 - 75));
  print_byte(b' ');
  print_dec((0 - 75) % 60);
  print_byte(b' ');
  match checked_div(minute(0), 0) {
    inl q -> print_dec(q)
  | inr e -> match e { inl u -> print_lit("division by zero") | inr u -> print_lit("overflow") }
  };
  print_byte(b'\n')
-- output: 45 -15 division by zero

rec

The handlers a recursive function needs. A function that calls itself has a budget of 10000 levels and performs Exhausted when it runs out. Recursion teaches them.

include textio
include rec

fn depth(n: i32) -> i32 = if n == 0 { 0 } else { 1 + depth(n - 1) }

main -> 1 =
  match with exhausted_to_option { depth(100) } {
    inl d -> print_dec(d)
  | inr u -> print_lit("too deep")
  };
  print_byte(b' ');
  print_dec(with deep { depth(100) });
  print_byte(b'\n')
-- output: 100 100

io

The system’s effects, and decimal output. main is given each effect by the platform; any other function performs them and its caller serves them. Input and output teaches them.

textio

Text over the standard streams. Input and output teaches them.

include textio

main -> 1 =
  let s = read_input();
  let n = borrow imm s { t -> fold_lines(t, !{ (l, k) -> k + 1 }, 0) };
  let s = print_string(s);
  print_dec(n);
  print_lit(" lines\n")
-- stdin: alpha
-- stdin: beta
-- output: alpha
-- output: beta
-- output: 2 lines

text

string, a growable buffer of UTF-8 bytes, and text 'a, a view of some (text_mut 'a when it is exclusive). A view is lent from a string with borrow imm s { t -> … }, or from a literal with borrow imm "…" { t -> … }, and the functions that cut it answer sub-views without copying. A string is a buf of u8, so len_of, pop and the rest work on it. Buffers and strings teaches them.

Building a string. The push_ functions are called with &mut s.

Reading text.

UTF-8 and parsing.

In place, and buffers of views.

include textio

-- The number after the `=` of `key = value`, or 0 when there is no `=`.
fn value<'t>(line: text 't) -> i32 with Fail[ParseError] =
  match split_once(line, b'=') {
    inl (k, v) -> parse_i32(trim(v))
  | inr l -> 0
  }

main -> 1 =
  let mut s = box string(16);
  push_lit(&mut s, "caf");
  push_char(&mut s, 0xe9);
  push_lit(&mut s, " = ");
  push_dec(&mut s, 42);
  let bytes = len_of(&s);
  let chars = borrow imm s { t -> count_chars(t) };
  let v = borrow imm s { t -> with default(0 - 1) { value(t) } };
  let s = print_string(s);
  print_lit(": ");
  print_dec(bytes);
  print_lit(" bytes, ");
  print_dec(chars);
  print_lit(" characters, value ");
  print_dec(v);
  print_byte(b'\n')
-- output: café = 42: 10 bytes, 9 characters, value 42

buf

buf A, a growable array, and a priority queue on one. Vec[T] wraps a buf T, and every function here works on both. borrow imm b { v -> … } and borrow mut b { v -> … } lend the elements as a view for slice. Buffers and strings teaches them.

An element type needs a placeholder for the spare capacity: numbers, views, arrays, buffers and data built from them have one; a heap cell ref A doesn’t. A heap’s elements are copied where they lie, so its A is copyable (i32, bool, tuples of them).

include textio

main -> 1 =
  let h = box buf[i32 * i32](4);
  let h = heap_push(h, 5, 50);
  let h = heap_push(h, 2, 20);
  let mut h = heap_push(h, 9, 90);
  for i in 0..3 {
    let r = heap_pop(&mut h);
    match r { inl (k, x) -> print_dec(x); print_byte(b' ') | inr u -> () }
  };
  let mut b = box buf[i32](2);
  push(&mut b, 1); push(&mut b, 2); push(&mut b, 3);
  let mut b = truncate(b, 1);
  let c = cap_of(&b);
  let n = len_of(&b);
  print_dec(n); print_byte(b' '); print_dec(c);
  print_byte(b'\n')
-- output: 20 50 90 1 8

slice

Functions on views: array_imm 'a A (shared) and array_mut 'a A (exclusive), lent from an array or a buffer by a borrow block. A function that changes a view hands it back, and discard_mut ends it. An index out of range reads the default and writes nothing. Searches and sorts take the element comparison as an argument, and functions that copy an element need a copyable A. Arrays teaches them.

include textio
include slice

fn scramble(i: i32) -> i32 = (i * 7) % 10

main -> 1 =
  let mut a = array_new[i32](6, scramble);
  borrow mut a { v -> let v = sort(v, cmp_i32, 0); let v = reverse(v); discard_mut(v) };
  let at5 = borrow imm a { v -> find(v, 5, eq_i32) };
  let has3 = borrow imm a { v -> contains(v, 3, eq_i32) };
  for x in &a { print_dec(*x); print_byte(b' ') };
  match at5 { inl i -> print_lit("5 at "); print_dec(i) | inr u -> print_lit("no 5") };
  if has3 { print_lit(", has 3") } else { print_lit(", no 3") };
  print_byte(b'\n')
-- output: 8 7 5 4 1 0 5 at 2, no 3

key

The families a map uses: one equality, hash and order per type. They have cases at the integers, 1, tuples, sums (so bool), arrays, views and buffers (so string and text), compared structurally, and a program adds cases at its own types with poly. A float has none. Equality, hashing and order teaches them.

A view 'a T of an integer, a tuple of them or a view is the value itself, so equal(x, y) takes the values.

include textio
include key

main -> 1 =
  if equal((1, true), (1, true)) { print_lit("equal ") } else { print_lit("different ") };
  print_dec(order((1, 5), (2, 0)));
  print_byte(b' ');
  if hash(7) == hash(7) { print_lit("same hash") } else { print_lit("?") };
  print_byte(b'\n')
-- output: equal -1 same hash

map

A hash map and a set, keyed by key’s families. A map is a value: an operation takes it with &m or &mut m. borrow imm m { 'x, r -> … } lends it as r : MapRef[K, V]<'h, 'k, 'x>, to read keys and values in place. Maps and sets teaches them.

The keys and values need a placeholder, as a buffer’s elements do. Every iteration is in slot order: the same on every run for the same insertions and removals, but neither insertion order nor sorted.

include textio
include map

main -> 1 =
  let mut seen = set_new[i32](8);
  let mut dups = 0;
  for x in 0..20 {
    let fresh = set_insert(&mut seen, (x * x) % 7);
    if not(fresh) { dups = dups + 1 }
  };
  let mut m = map_new[i32, i32](8);
  let old = map_insert(&mut m, 1, 10);
  let old = map_insert(&mut m, 1, 11);
  let gone = map_remove(&mut m, 2);
  let n = set_len(&seen);
  print_dec(n);
  print_byte(b' ');
  print_dec(dups);
  print_byte(b' ');
  match old { Some(v) -> print_dec(v) | None -> print_lit("none") };
  print_byte(b' ');
  match gone { Some(v) -> print_dec(v) | None -> print_lit("none") };
  print_byte(b'\n')
-- output: 4 16 10 none

list

A generic owned list. Its functions are recursive, so a call needs a rec handler around it. Recursion introduces it.

include textio
include list

main -> 1 =
  let xs = cons(1, cons(2, cons(3, cons(4, nil()))));
  let sum = with on_exhausted(!{ u -> 0 - 1 }) {
    fold(filter(map(xs, !{ x -> x * x }), !{ x -> x % 2 == 0 }), 0, !{ (a, x) -> a + x })
  };
  print_dec(sum);
  print_byte(b'\n')
-- output: 20

list’s map and filter share their names with those of adapters and iters, so a program that calls them includes only one of these modules.

yield

The effect a generator performs. Generators teaches it.

adapters

Generic generators over stored generators. A source U (pull A K R) yields As, returns K when it finishes, and hands back R when closed early (Stored generators). An adapter that runs its source to the end returns the source’s K; those that may stop it early take a source with R = K. Chain them with |> (Pipelines).

include textio
include adapters

fn range(lo: i32, hi: i32) -> 1 with Yield[i32] =
  let mut i = lo;
  while i < hi { yield(i); i = i + 1 };
  ()

main -> 1 =
  let mut last = 0;
  for s in range(1, 100) |> skip(2) |> scan(0, !{ (acc, x) -> acc + x }) |> take_until(!{ s -> s > 40 }) {
    last = s
  };
  let mut pairs = 0;
  for p in zip(range(0, 10), range(100, 103)) { let (a, b) = p; pairs = pairs + a * b };
  print_dec(last);
  print_byte(b' ');
  print_dec(pairs);
  print_byte(b'\n')
-- output: 33 305

iters

Adapters over data, a view or a count a..b. A for over a chain of them runs at most once per element, so it stays total. for over data covers the loop they feed.

include textio
include iters

fn big(x: i32) -> bool = x > 2

total fn weighted<'a>(v: array_imm 'a i32) -> i32 =
  let mut s = 0;
  for p in zip(filter(copied(elems(v)), big), 100..200) { let (x, y) = p; s = s + x * y };
  s

main -> 1 =
  let a = array_new[i32](5, !{ i -> i });
  let w = borrow imm a { v -> weighted(v) };
  print_dec(w);
  print_byte(b'\n')
-- output: 704

async

Tasks and a round-robin scheduler, written in the language. Async tasks teaches them.

async’s push shares its name with buf’s, so a program that queues tasks doesn’t push to a buffer by that name.

float

The float operations by name, conversions, IEEE 754’s total order, and printing and parsing in the shortest decimal that reads back as the same float. Each name below exists at f64 and, with f32 in place of f64, at f32. Floats introduces them.

include float

main -> 1 =
  let x = borrow imm "2.5e-3" { t -> with default(0.0) { parse_f64(t) } };
  let mut s = box string(32);
  push_f64(&mut s, x * 4.0);
  push_lit(&mut s, " ");
  push_f32(&mut s, f32_of_f64(0.1));
  let s = print_string(s);
  print_byte(b' ');
  print_dec(total_cmp_f64(neg_f64(0.0), 0.0));
  print_byte(b' ');
  match i32_of_f64(1.0e12) { inl n -> print_dec(n) | inr u -> print_lit("out of range") };
  print_byte(b'\n')
-- output: 0.01 0.1 -1 out of range