Standard Library Overview #

The SafeC standard library (std/) covers core utilities, collections, allocators, threads and async, networking, TLS and HTTP, GUI, audio, DSP, machine learning, filesystems, encoding and serialization, cryptography, debugging, and bare-metal support. Each module is a .h header, plus a .sc implementation for the non-generic parts; generic containers are header-only. #include only ever names .h files — safeguard links the .sc implementations of the modules a program uses (from the prebuilt std, or compiled into build/deps/libsafec_std.a; see Including the Standard Library). Every public declaration, with its doc comment, is in the API Reference. Include prelude.h to pull in most modules at once; GUI, audio/MIDI, encoding, HTTP/RPC/wasm, async, the real-time scheduler, ML and SIMD are included by their own headers.

#include <std/prelude.h>

int main() {
    println("Hello from SafeC stdlib!");
    return 0;
}

Module Categories #

Core #

Serialization #

Collections #

Allocators #

Synchronization #

IPC #

Async #

Real-Time Scheduler #

Networking #

TLS #

HTTP & Web #

Machine Learning — see ML #

GUI #

Audio & MIDI #

Filesystems #

DSP & Real-Time #

Security & Cryptography #

Debugging & Profiling #

SIMD #

Hardware Abstraction Layer #

Interrupts & MMIO #

Kernel Primitives #

Testing & Benchmarking #

Encoding #

Utilities #

C Compatibility Headers #

Generic Pattern #

Containers and other value-holding APIs are generic structs and functions, monomorphized per element type. They hand out ?&T references (narrow them with match, .default(x), or std::expect_ref), return ?T when there may be no value, and take typed fn callbacks — the standard library has no void* element or callback parameters. T is written once, on the variable, and the constructor infers it from that target type:

#include <std/collections/vec.h>

int main() {
    struct Vec<int> v = std::Vec::new();
    v.push(42);
    v.push(100);
    match (v.get(0UL)) {
        case some(x): *x = *x + 1;      // 43, written in place
        case null:    { }
    }
    int last = v.pop().default(-1);     // 100
    v.free();
    return last == 100 ? 0 : 1;
}

Where a container must hold callbacks with different context types at once (a timer wheel, a widget tree, a VFS mounting several drivers), the slot stores the pair type-erased, but the only way to fill it is a generic method that takes a matching fn(?&T) and ?&T — TimerWheel::add, Widget::on_click, Vfs::mount, TaskScheduler::spawn — so every call is still checked at compile time. The erased slot is a ?&Erased (std/erased.h), never a void*. std has no void* even at the C ABI boundary: untyped memory is bytes (unsigned char*, what mem.h's raw allocator returns), libc/OS/C-library objects (FILE, pthread objects, SSL, CoreFoundation references, Win32 handles, ...) are opaque structs, and callbacks are fn types. tests/std_modules/api_lint.py (run by the smoke test) fails the build if a raw pointer appears in a public declaration, or a void* anywhere in std.

Buffers are slices. Wherever a C API would take a pointer and a length (or return an array through a pointer), std takes a built-in slice: []T when it writes the elements, []const T when it only reads them — f.read(buf[..]), sha256(data, digest[..]), fft(xs[0..n]), String::from_bytes(str_bytes("text")). A slice carries its length, indexing it is bounds-checked, and an output that must have a fixed size (a key, a digest) is checked on entry. See Slices.

Including the Standard Library #

Individual modules:

#include <std/mem.h>
#include <std/io.h>
#include <std/collections/vec.h>

Most modules at once:

#include <std/prelude.h>

When building with the safeguard package manager, the std modules the program includes (and the ones its code calls without an include: new, channels) are compiled into build/deps/libsafec_std.a and linked, with the system libraries they need — or, in a release install, taken from its prebuilt std archive (see Standard Library Modules).

When building manually, put the SafeC checkout on the include path (headers are named <std/...>) and link an archive of all of std — safeguard build of a project with [build] std = "all" makes one (or build it from every std/**/*.sc) — with the system libraries of the modules you use (safeguard std-modules std/x.h lists them):

safec myfile.sc -I /path/to/SafeC -o myfile.ll
clang myfile.ll /path/to/libsafec_std.a -lm -lpthread -o myfile