Builtin functions

Every function available without importing, from print and len to files, processes and streams.

vlatest

Builtin functions need no import. They are declared in the compiler's builtin registry rather than in a .pkl file, and they take positional arguments only named arguments and spread are rejected on every one of them.

Output

Function Result
print(args...) void
println(args...) void
stdout_stream() Stream
stderr_stream() Stream

Multiple arguments are concatenated with nothing between them, so add the separators yourself:

fn main() {
    print("a", "b", "c")
    println("")
    println("a", "b", "c")
}

Both print abc.

println does not print a list's contents, it prints the list's length:

fn main() {
    let nums = [1, 2, 3]
    println(nums)
}

That prints List(len=3). To see the elements, iterate or index.

There is no stdin_stream. To read standard input, use std.io or a stream opened with stream_open_read.

Numbers

Function Result
abs(x) the argument's type
min(a, b) the arguments' type
max(a, b) the arguments' type
clamp(x, lo, hi) the arguments' type
range(end), range(start, end), range(start, end, step) List<int>
fn main() {
    println(abs(-5))          // 5
    println(abs(-2.5))        // 2.5
    println(min(2, 3))        // 2
    println(max(1, 2))        // 2
    println(clamp(5, 0, 3))   // 3

    for (i in range(3)) { print("{i} ") }
    println("")
    for (i in range(2, 8, 3)) { print("{i} ") }
    println("")
}

Every argument to min, max, and clamp must have the same type. Passing an int with float arguments type-checks and then crashes the code generator, so convert first:

fn main() {
    println(clamp(5.0, 0.0, 3.0))   // 3
}

range always returns a List<int>, so its bounds must be int. range is the reliable way to build a numeric sequence; see Operators for how the range operator types its bounds.

Length and conversion

Function Result
len(items) int
str(x) string
bytes(s: string) List<byte>
fn main() {
    println(len("abc"))       // 3
    println(len([1, 2, 3]))   // 3
    println(str(42))          // 42
    println(str(3.5))         // 3.5
    println(bytes("Hi"))      // List(len=2)
}

str accepts int, float, bool, char, and List<byte>. It has no overload for a List<int>, so str([1, 2, 3]) is a compile error.

Files

Function Result
read_file(path) string?
write_file(path, text) bool
file_exists(path) bool
delete(path) bool
mkdir(path) bool
list_dir(path) List<string>?
fn main() {
    println(write_file("notes.txt", "hello\n"))
    println(file_exists("notes.txt"))

    let text = read_file("notes.txt")
    if (let some(s) = text) {
        println(s)
    } else {
        println("missing")
    }

    println(delete("notes.txt"))
    println(file_exists("notes.txt"))
}

read_file and list_dir return none rather than failing, so handle the optional. The bool results are not exceptions, they report success, and a false on a write is worth logging.

See Files for buffered streams and std.fs.

Streams

Function Result
stream_open_read(path) Stream?
stream_open_write(path) Stream?
stream_open_append(path) Stream?
stdout_stream() Stream
stderr_stream() Stream

A Stream has read(n), write(bytes), flush(), and close(). See Files.

Processes

Function Result
run_cmd(argv: List<string>) (int?, string, string, bool)?
run_spawn(argv: List<string>) Stream?
proc_wait(h) bool
proc_running(h) bool
proc_code(h) int?
proc_kill(h) bool
proc_out_read(h) string?
proc_err_read(h) string?
proc_in_write(h, b) int
proc_in_close(h) bool
args() List<string>
exit(code) void

See Processes for what each one returns and for the std.process wrappers built on top.

Threads, channels, and atomics

The thread builtins are listed in full in Threads. They cover task spawn/join, mutexes, condition variables, semaphores, atomics, once-cells, and channels.

Diagnostics and the test harness

Function Result
assert(cond) void
expect(value) test-harness matcher
alloc(T, count) raw pointer, unsafe only
free(p) void, unsafe only

assert aborts the process when the condition is false:

fn main() {
    assert(1 + 1 == 2)
    println("assert passed")
}

expect and its matchers (toBe, toEqual, toContain, toThrow, …) are only available in a test file. See Testing.

alloc and free are raw memory the garbage collector never traces. They must be called inside an unsafe block, and a #[manualAlloc] binding needs an explicit .free(). Reach for them only when the standard library does not cover what you need.

Program control

exit(code) stops the process with a numeric code and never returns. An uncaught throw also ends the process, see Error Handling for how failures are actually reported.

Next steps