Standard Library

The Sun standard library is distributed as a precompiled stdlib.moon file. Include it in your manifest and import the sun namespace:

using sun;
 
function main() void {
    var allocator = make_heap_allocator();
    // Use stdlib types...
}
 
manifest {
    moons: ["stdlib.moon"]
}

HeapAllocator

The standard memory allocator using system malloc/free. Many stdlib types require an allocator for construction.

var allocator = make_heap_allocator();

var allocator = make_heap_allocator();
var p: raw_ptr<Point> = allocator.create<Point>(3, 4);
// p points to a heap-allocated, initialized Point
_free(p);  // Manual cleanup

Unique<T>

A smart pointer that automatically frees its data when deinit is called (at scope exit). Provides safe access to heap-allocated objects without manual unsafe blocks.

var allocator = make_heap_allocator();
var p = Unique<Point>(allocator.create<Point>(3, 4));
p.get().x;     // Safe access - returns ref T
p.get_raw();   // Get raw pointer for low-level operations
p.is_null();   // Check if null
// p.deinit() called automatically at scope exit

Vec<T>

A generic growable array backed by contiguous memory. Implements IIterable<T, Vec<T>> for use with for-in loops.

var allocator = make_heap_allocator();
var v = Vec<i32>(allocator, 8);  // Initial capacity 8
v.push(10);
v.push(20);
v.push(30);
var val = v.get(0);       // 10
v.set(1, 25);             // Update index 1
var last = v.pop();       // Option.Some(30) (removes last element)
var len = v.size();       // 2

Indexing

Vec<T> supports bracket indexing syntax:

v[0] = 42;       // Calls __setindex__
var x = v[0];    // Calls __index__

Iteration

var v = Vec<i32>(allocator, 4);
v.push(1); v.push(2); v.push(3);
 
for (var x: i32 in v) {
    println(x);
}

Map<K, V>

A generic hash map using open addressing with linear probing. Implements IIterable<V, Map<K, V>> for iterating over values. Supports i32, i64, and String keys.

var allocator = make_heap_allocator();
var m = Map<i64, i32>(allocator, 16);  // Initial capacity 16
m.insert(42, 100);
var val = m.getOrDefault(42, 0);   // 100
m.remove(42);

Iteration

var m = Map<i64, i32>(allocator, 16);
m.insert(1, 10);
m.insert(2, 20);
 
for (var v: i32 in m) {
    println(v);  // Iterates over values
}

String

A heap-allocated mutable string backed by Matrix<u8>. Supports slicing via the [start:end] syntax which returns a StringView.

var allocator = make_heap_allocator();
var s = String(allocator, "Hello");
var t = String("literal only");  // allocator-less: uses a fresh HeapAllocator
println(s.length());   // 5
var ch = s.at(0);          // 72 ('H')
s.append_char(33);         // Append '!'

The terminator c_str() writes sits past the length, so the string itself is unchanged. from_c_str(alloc, p) is the other direction — it copies a NUL-terminated C string into an owned String, which is how sun.env.get and read_dir hand back text from libc.

var path = String(alloc, "/tmp/");
path.append_literal("out.txt");
write_string(path.c_str(), body);

Text Manipulation

Methods that keep the same bytes, or fewer, edit the string in place. Methods that produce new strings take the allocator to build them with.

var line = String(allocator, "  name = Ada  ");
line.trim();                              // "name = Ada"
line.replace(" = ", "=");                 // "name=Ada"
line.to_upper();                          // "NAME=ADA"
 
var fields = line.split(allocator, 61);   // ['=' is 61] -> ["NAME", "ADA"]
var again = join(allocator, fields, "=");  // "NAME=ADA"

Slicing

String slicing returns a StringView (non-owning view, no copy):

var s = String(allocator, "Hello, World!");
var view = s[0:5];   // StringView of "Hello"
println(view.length());  // 5

StringView

A non-owning view into a String. Provides read-only access to a substring without copying.

Matrix<T>

N-dimensional matrices backed by contiguous heap memory. Supports bracket indexing and slicing.

var allocator = make_heap_allocator();
var m = Matrix<i32>(allocator, [3, 3]);   // 3x3 matrix
m[0, 0] = 1;
m[1, 1] = 5;
var val = m[1, 1];  // 5

See Matrices for detailed documentation.

Mutex

Thread synchronization primitive using atomic compare-and-swap with futex-based blocking.

var m = Mutex();
m.lock();
// Critical section
m.unlock();

See Threads for usage with spawned threads.

File I/O

stdlib/io.sun (module sun.io). Every path is taken two ways: as a static_ptr<u8> — what a string literal is — and as a ref String for a path put together at runtime.

using sun;
using sun.io;
 
var f = File();
try {
    f.open("notes.txt", FileMode.Write);
    f.write("Hello, World!");
    f.close();
} catch (e: IError) {
    eprintln("could not write notes.txt");
}
 
// Or in one step
var text = read_to_string(alloc, "notes.txt");
 
// A runtime path
var path = String(alloc, "/tmp/");
path.append_literal("report.csv");
write_string(path, text);

FileMode is Read (must exist), Write (create or truncate) or Append. Whence is Start, Current or End.

A File closes itself at scope exit. The descriptor it holds is 0 when it holds nothing, so a moved-from File — which is zeroed — closes nothing rather than closing stdin.

Free functions:

Path stands for the two overloads each of these has: static_ptr<u8> (a string literal) and ref String (a path built at runtime). rename_file has all four combinations.

read_line reads stdin one byte at a time and strips the newline, returning None only at end of input with nothing read. It is deliberately unbuffered: a buffered reader would swallow bytes a child process spawned later expects to find on the descriptor.

There is no stat. struct stat has a different field order and padding on x86-64 and aarch64, and the stdlib is compiled from one source for both, so the questions people actually ask are answered with access, opendir and lseek instead.

Reading a directory

read_dir returns the entries with their kind attached, taken from the directory record itself — no second syscall per entry, and no application-level parsing of getdents64 output.

var entries = read_dir(alloc, "/etc");
for (var e: DirEntry in entries) {
    if (e.is_dir()) {
        print("dir  ");
    } else {
        print("file ");
    }
    println(e.name());
}

Some filesystems do not report a kind, giving FileKind.Unknown; is_dir(path) answers it with a syscall when that matters.

Waiting on descriptors

Poller wraps poll(2). Descriptors keep the position they were added at, so is_readable(i) answers for the i-th one. Nothing here needs a struct pollfd assembled by hand.

var poller = Poller(alloc);
poller.add_read(sock_fd);
poller.add_read(pipe_fd);
 
var ready = poller.wait(1000);   // -1 blocks forever
if (poller.is_readable(0)) { /* sock_fd has data */ }
if (poller.is_hup(1)) { /* pipe_fd's writer closed */ }

The bits are POLLIN, POLLPRI, POLLOUT, POLLERR, POLLHUP and POLLNVAL. Do not call add while a wait is in flight: growing the set reallocates it.

Environment

stdlib/env.sun (module sun.env).

using sun.env;
 
var home = match get(alloc, "HOME") {
    Option.Some(p) => p,
    Option.None => String(alloc, "/")
};
 
try { set("LANG", "C"); } catch (e: IError) { }
var here = cwd(alloc);

Name stands for the two overloads each of these has: static_ptr<u8> (a literal) and ref String (a name or value built at runtime). set has all four combinations.

args takes argc and argv from main rather than discovering them. Under the JIT the running process is the compiler, so its own argv is not the script's — see Entry point.

function main(argc: i32, argv: raw_ptr<raw_ptr<i8>>) i32 {
    var alloc = make_heap_allocator();
    var cli = args(alloc, argc, argv);
    for (var s: String in cli) { println(s); }
    return 0;
}

Listing every environment variable needs the environ global, and Sun has no extern global declaration yet.

Processes

stdlib/process.sun (module sun.process). Command covers running a program; the raw POSIX calls are there for programs that drive the fork themselves.

using sun.process;
 
var cmd = Command(alloc, "/bin/sh");
cmd.arg("-c");
cmd.arg("printf hello");
var out = cmd.output();
 
println(out.status());     // 0
println(out.stdout());     // hello

Command

Arguments are passed to the program as they are given — a space inside one argument stays inside it, with no shell reparsing.

Child

collect polls the two pipes rather than draining one and then the other: a child that fills the stderr pipe while the parent is stuck reading stdout would deadlock. Output gives status() i32 and borrowed stdout() / stderr().

A Child releases any pipes it still holds when it goes out of scope. It never waits and never signals there — a moved-from Child is all zeroes, and reaping or killing on that would touch a process the object no longer stands for. Call wait to reap.

Identity, signals and raw control

Signal numbers are SIGHUP, SIGINT, SIGQUIT, SIGKILL, SIGSEGV, SIGPIPE, SIGALRM, SIGTERM, SIGCHLD, SIGCONT, SIGSTOP; wait_pid takes WNOHANG.

Between fork and exec a child may only call things that are safe inside a signal handler — no allocation, no method that might allocate. Command is written to that rule; hand-rolled forks have to be too.

Time

stdlib/time.sun (module sun.time).

using sun.time;
 
var start = now();
sleep(millis(50));
println(start.elapsed().as_millis());
 
println(format(alloc, utc(unix_time()), "%Y-%m-%d %H:%M:%S"));

Only differences between Instants mean anything: the zero point is arbitrary, and the clock never jumps backwards when the system time is adjusted.

DateTime uses human units — year is the full year and month is 1-12, not C's tm_year/tm_mon offsets. It also carries day, hour, minute, second, weekday (Sunday = 0), yearday and utc_offset.

Option<T> and Result<T, E>

Payload enums for absence and fallibility, defined in option.sun:

enum Option<T> { Some(T), None }
enum Result<T, E> { Ok(T), Err(E) }

Inspect them with match; construction infers type arguments from the payload (Option.Some(42)) or from the expected type (Option.None in return position or against an annotation):

var v = match m.find(key) {
    Option.Some(x) => x,
    Option.None => fallback
};

Use Option for "might not be there" (lookups, first/last, pop, iterator next), and IError throwing for actual failures. Result<T, E> suits fallible operations whose error is a value rather than an exception.

Iteration: IIterator<T, Container> and IIterable<T, Self>

The iteration protocol lives in iterator.sun and is what for-in drives:

interface IIterator<T, Container> {
    function next(container: ref Container) Option<T>;
}
interface IIterable<T, Self> {
    function iter() IIterator<T, Self>;
}

next() yields the next element or Option.None once the sequence is exhausted (and keeps returning None afterwards). for (var x: T in c) calls iter() when c has one, then loops on next() until None; the loop variable's type must match T. Iterators are separate objects that receive the container by ref on every call, so a container can be iterated more than once and iterators stay cheap:

class Countdown implements IIterator<i32, Countdown> {
    var n: i32;
    function init(n: i32) { this.n = n; }
 
    function next(self: ref Countdown) Option<i32> {
        if (this.n == 0) { return Option.None; }
        this.n = this.n - 1;
        return Option.Some(this.n + 1);
    }
}
 
function main() i32 {
    var sum: i32 = 0;
    for (var x: i32 in Countdown(5)) {
        sum = sum + x;
    }
    return sum;  // 5 + 4 + 3 + 2 + 1 = 15
}

Iterators can also be driven by hand:

var it = v.iter();
var going = true;
while (going) {
    match it.next(v) {
        Option.Some(x) => { println(x); },
        Option.None => { going = false; }
    };
}

A container implements IIterable and returns its concrete iterator from iter(); the loop then passes the container to every next() call, so next must take that container type by ref (the compiler checks this — it is what keeps the container access inside next memory-safe):

class Range implements IIterable<i32, Range> {
    var start: i32;
    var end: i32;
    function init(s: i32, e: i32) { this.start = s; this.end = e; }
    function iter() RangeIterator { return RangeIterator(this.start); }
}
 
class RangeIterator implements IIterator<i32, Range> {
    var cur: i32;
    function init(s: i32) { this.cur = s; }
    function next(r: ref Range) Option<i32> {
        if (this.cur >= r.end) { return Option.None; }
        this.cur = this.cur + 1;
        return Option.Some(this.cur - 1);
    }
}

Because iter() returns a class rather than the IIterator<T, Self> fat pointer the interface names, an IIterable implemented this way is static-only: it drives for-in, but a Range cannot be converted to an IIterable<i32, Range> value (there is no way to dispatch iter() through it soundly).

Vec<T>, LinkedList<T>, Map<K, V> (values) and ContiguousBuffer<T> implement IIterable.

BigUint

Arbitrary-precision unsigned integer from bigint.sun: little-endian u64 limbs in a Vec, schoolbook arithmetic built on _mul_hi_u64. Values are owned (clone() to copy); the by-ref argument of a binary operation is never modified.

var n = BigUint(alloc, 1);
for (var i: u64 = 2; i <= 30; i = i + 1) { n.mul_small(i); }   // 30!
var text = String(alloc, "");
n.append_decimal(text);   // 265252859812191058636308480000000

Numeric conversion

A value never narrows on its own: assigning an i64 to an i32 is a compile error. math.sun provides safe_convert<T>(x), which converts between any two numeric types and throws ConversionError when the value does not fit:

var ms: i64 = 200;
var t: i32 = safe_convert<i32>(ms);       // 200
var big: i64 = 4294967498;
var u: i32 = safe_convert<i32>(big);      // throws ConversionError
var n: u64 = safe_convert<u64>(-1);       // throws: negative to unsigned
var b: u8 = safe_convert<u8>(255.0);      // 255
var c: u8 = safe_convert<u8>(256.0);      // throws
var h: f32 = safe_convert<f32>(1.0e300);  // throws: infinite in f32

Checked: integer values outside T's range (including a sign change that flips the value), floats that are NaN or outside T's range, and an f64 that overflows f32. A fraction is truncated toward zero, as with _convert. Widening and integer-to-float conversions always succeed.

safe_convert takes two type parameters, <T, U>; the source type U is inferred from the argument, so only the target is written. When the value is known to fit, the _convert<T>(x) intrinsic does the same conversion with no check (see Intrinsics).

Numeric limits

math.sun also defines I64_MAX, I64_MIN, F64_MAX, F64_MIN_POSITIVE (smallest normal) and F64_EPSILON.

Json

json.sun parses JSON text into an owned tree and writes it back, compact or pretty. Objects keep their members in insertion order (lookups are a linear scan), numbers are Int(i64) when the text is an integer that fits and Float(f64) otherwise, strings are UTF-8 Strings.

var alloc = make_heap_allocator();
var doc = json_parse(alloc, "{\"name\": \"sun\", \"tags\": [1, 2.5]}");
var name: ref String = doc.get("name").as_string();
var second: f64 = doc.get("tags").at(1).as_f64();
 
var obj = json_object(alloc);
obj.set(String(alloc, "ok"), Json(true));
obj.set(String(alloc, "tags"), json_array(alloc));
obj.get("tags").push(Json(42));
println(obj.to_string(alloc));            // {"ok":true,"tags":[42]}
println(obj.to_pretty_string(alloc, 2));

The tree node is class Json wrapping a public var value: JsonValue:

enum JsonValue { Null, Bool(bool), Int(i64), Float(f64), String(String), Array(Vec<Json>), Object(Vec<JsonMember>) }
class JsonMember { var key: String; var value: Json; }

Match on j.value directly when the accessors below are not enough.

The tree owns everything in it. Json(s), push(item) and set(key, value) take their String and Json arguments by value, which in Sun means they are moved in: the caller cannot use them afterwards, and the borrow checker rejects a later use. When a value is still needed after being placed in a document, store a copy instead. json_string(alloc, ref s) does that for a String:

// cfg.model is still needed later, so the document gets a copy
req.set(String(alloc, "model"), json_string(alloc, cfg.model));
// Equivalent to an explicit clone:
req.set(String(alloc, "model"), Json(cfg.model.clone(alloc)));
// Moves cfg.model into the document; using it again is a compile error
req.set(String(alloc, "model"), Json(cfg.model));

Readers throw JsonError (code 60) on a kind mismatch or missing key; parse errors carry the byte offset of the problem in offset(). When writing, Float values keep a .0 or exponent so they read back as Float, and non-finite floats become null.

Error Types

All error types implement IError with code() i32 and message() String methods. message() returns an owned clone of the description, so the text stays usable for as long as the caller keeps it, independent of the error object itself.

function pop_first(v: ref Vec<i32>) i32, IError {
    if (v.isEmpty()) {
        throw EmptyError();
    }
    return v.get(0);
}

Error takes its message either as a literal or as a String put together at runtime. Given a String it keeps its own copy, so the message stays readable after the String it came from is gone — including in a caller that catches the error several frames up.

var path = String(alloc, "/tmp/");
path.append(name);
throw Error(errno(), path);
 
// ... several frames up:
catch (e: IError) {
    var msg: String = e.message();   // an owned clone
    eprintln(msg);
}

Print Functions

Overloaded print (no newline) and println (with newline) from print.sun. Both accept any of the following argument types:

Interpolated strings can be passed directly:

var x: i32 = 42;
println(`x = ${x}`);   // prints "x = 42\n"
print("no newline");
println();

eprint and eprintln write to stderr instead, so a caller can tell diagnostics apart from the program's real output. They take a string literal or a ref String; interpolation covers everything else.

eprintln("could not open the file");
eprintln(`giving up after ${attempts} tries`);