Builtin functions
Every function available without importing, from print and len to files, processes and streams.
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.
