The Standard Library

type struct Name { ... }
type enum Name { ... }
type trait Name { ... }
type union Name { ... }

Begins a type declaration; the keyword that follows says which kind. On its own, type Name = Existing; declares an alias.

type struct Name {
    field: Type;
    method(&this) -> Ret { ... }
}

A value type with named fields and optional methods. Structs live on the stack and are passed by value. Fields are public by default and may carry = default values; methods take their receiver as &this, mut &this, or this.

static name(param: Type) -> Ret { ... }

A method that belongs to the type rather than an instance, called as Type::name(..). For structs, static new(..) returning a struct literal is the idiomatic constructor.

namespace app::module;

Every source file opens with one: its position in the module hierarchy. The compiler uses it to resolve imports and to mangle symbol names, so two parse functions in different modules never collide at link time.

import a::b;
import a::b::{ X, Y };
import a::b as c;
import a::b::*;

Brings a module, or selected items from it, into scope. One path per declaration: use the brace form for several items, as to alias, and * for everything public (prefer the brace form; wildcards invite name collisions).

namespace std;

std: the Cryo standard library.

namespace std::fmt;

fmt: formatting values as text.

function name<T>(param: Type) -> Ret { ... }

Declares a function. Parameters are written name: Type and are never inferred; the return type follows -> and defaults to void. Declaration order does not matter: every signature is collected before any body is checked, so functions may call each other freely and recurse.

primitive i32

32-bit signed integer.

function println(text: String) -> void

Like print, followed by a newline.

return value;

Leaves the current function with the given value. A function whose return type is not void must return one; a bare return; is for void. In an async function it completes the future with the value.

namespace std::collections;

collections: growable containers built on alloc/.

namespace std::collections::array;

Array<T, A>: growable, heap-backed, contiguous sequence.

namespace std::collections::str;

Str: a borrowed UTF-8 string slice.

primitive string

NUL-terminated raw string (u8*), matching the C ABI. Length-typed text is Str / String.

namespace std::net;

net: network primitives + HTTP.

namespace std::net::http;

http: HTTP/1.1 with keep-alive.

namespace std::net::http::status;

HTTP status codes.

import a::b as c;

Gives an imported module or item a local alias.

namespace std::fmt::display;

Display / Debug / Formatter.

public function name() { ... }
public:

Visible to any module that imports this one - the default for top-level items and for struct fields, so it is mostly written to be explicit. public: opens a visibility block that groups the members after it.

public module collections::array;

In a directory's _module.cryo aggregator, lists a submodule and whether it is public. Importing the directory's namespace sees only the modules declared public here.

namespace std::prelude;

Prelude: auto-imported into every Cryo source file.

namespace std::core;

core: foundation of the stdlib.

namespace std::alloc;

alloc: heap allocation primitives.

namespace std::io;

io: byte-level input/output.

namespace std::json;

json: RFC 8259 JSON parser and serializer.

namespace std::encoding;

encoding: byte <-> text codecs.

namespace std::fs;

fs: filesystem access.

namespace std::ffi;

ffi: the C ABI boundary.

namespace std::sys;

sys: the low-level OS seam.

namespace std::env;

env: process environment and arguments.

namespace std::math;

math: numeric operations on floats and integers.

namespace std::time;

std::time: durations, clocks, and civil time.

namespace std::random;

std::random: pseudo-random and OS-backed randomness.

namespace std::process;

process: subprocess spawning.

namespace std::thread;

std::thread: native OS threads.

namespace std::sync;

std::sync: synchronization primitives for concurrent code.

namespace std::future;

std::future: stackless async foundations — Future, Poll, Context, Waker, and the drivers that poll them.

namespace std::test;

test: Cryo's built-in unit-test framework.

type trait Name : Base {
    method(&this, other: &This) -> Ret;
}

Names a set of methods a type may implement. Inside the body This is the implementing type; methods may carry default bodies, and a trait may require a base trait (type trait Ord : Eq). Generic code asks for a trait with where T: Name.

implement struct Name { ... }
implement trait Trait for Type { ... }
implement u64 { ... }

Adds methods to a type outside its declaration. implement struct T (or enum, or a bare primitive) opens an inherent block; implement trait Tr for T supplies a trait's methods for one type. Resolution is at compile time - no dynamic dispatch.

type struct Array<T, A = GlobalAlloc> where A: Allocator {
    ptr: T*;
    length: i64;
    capacity: i64;
    alloc: A;
}

Array<T, A>: growable, heap-backed, contiguous sequence.

type struct HashMap<K, V, A = GlobalAlloc> where A: Allocator {
    buckets: Entry<K, V>**;
    bucket_count: u64;
    length: u64;
    alloc: A;
    seed: u64;
}

HashMap<K, V, A>: key-value map with amortized O(1) operations.

type trait Display {
    fmt<W>(&this, f: mut &Formatter<W>) -> Result<(), FmtError>
    where W: FmtWrite;
}

Display / Debug / Formatter.

function panic(message: string, loc: intrinsics::Location) -> never

Panic with message, reporting the place loc: intrinsics::location() written at the call, or in a ![caller_location] function its caller's. The helpers below do that automatically.

primitive never

The type of an expression that does not return. Only valid as a return type, written by functions that always panic, trap, or diverge. 0 bytes.

function assert(condition: boolean, message: string) -> void

Panic if condition is false. Always checked.

function unreachable() -> never

Mark a code path the programmer believes cannot be reached. If it ever is, the program aborts with a clear message rather than executing wrong code.

function todo() -> never

Stub a function you'll implement later. Reading better than inlining panic("not yet implemented", ...) with the place is its whole job.

namespace std::core::option;

Option: a value that may be absent.

namespace std::core::result;

Result: a value that may be an error.

namespace std::core::primitives;

Methods on primitive types.

primitive char

8-bit character (byte).

namespace std::core::varargs;

VaArgs: a safe, typed wrapper over a C-ABI variadic argument list.

type struct VaArgs {
    ptr: void*;
}

Single-pointer wrapper over the active va_list. ptr is the raw va_list pointer - the args identifier the compiler binds in a variadic body.

function name(count: i32, args...)

A variadic parameter: the trailing bucket receives any number of further arguments with C's calling convention, so the function stays ABI-compatible with the printf family. Wrap the bucket in VaArgs to read typed values from it.

namespace std::core::slice;

Slice<T>: a borrowed view into a contiguous sequence.

for (mut i: i32 = 0; i < n; i++) { ... }
for (item in iterable) { ... }

Two forms. The C-style for (init; condition; step) scopes its loop variable to the body. for (x in expr) iterates anything with next() -> Option<T>: an iterator, a range such as 0..n, an Array or Slice (their iter() is inserted for you), or a fixed-size array.

for (item in iterable) { ... }

Separates the loop variable from the sequence in a for loop. The sequence is evaluated once; the loop lowers to loop { match (it.next()) { Some(x) => .., None => break } }.

namespace std::core::ops;

Ranges and the Step trait.

start..end

A half-open range - start up to but excluding end - and sugar for Range::new(start, end): an iterator usable in for, and an ordinary value anywhere else. It binds looser than arithmetic, so a..b + 1 is a..(b + 1).

namespace std::core::iter;

Iterator: a lazy sequence.

function drop<T>(_v: T) -> void

Explicitly drop a value of type T. This is a no-op for types that do not implement a destructor. The caller is responsible for ensuring that any resources held by _v are properly released if necessary.

namespace std::core::marker;

Marker traits.

namespace std::core::cmp;

Comparison: equality and ordering.

namespace std::core::clone;

Clone: explicit duplication.

type trait Drop {
    drop(mut &this) -> void;
}

Drop: explicit destructor.

type trait Copy {}

Types whose values can be duplicated by a bitwise copy. Integers, floats, pointers, and pure-POD structs qualify; anything that owns resources (heap storage, file handles, refcount) does not.

type trait Send {}

Types that are safe to transfer between threads. An owning value of a Send type may cross a thread boundary without violating memory safety.

type trait Sync {}

Types that are safe to share between threads by shared reference. T: Sync if &T: Send.

type trait Eq {
    equals(&this, other: &This) -> boolean;
}

Types that support value equality. equals(a, b) must be reflexive, symmetric, and transitive.

type trait Ord : Eq {
    compare(&this, other: &This) -> Ordering;
}

Types that have a total order: every pair is Less, Equal, or Greater. compare must be consistent with equals: if a.equals(b) then a.compare(b) == Equal.

type trait Clone {
    clone(&this) -> This;
}

Clone: explicit duplication.

implement trait Trait for Type { ... }

Introduces a trait implementation: the block supplies, for one concrete type, the method bodies the trait requires.

implement trait Trait for Type { ... }

Names the type a trait implementation is for. The block that follows supplies the bodies the trait requires.

namespace std::alloc::box;

Box<T, A>: single-owner heap allocation.

namespace std::alloc::rc;

Rc<T, A>: single-threaded reference counting, with weak references.

namespace std::fmt::interp;

f-string interpolation runtime.

type enum Option<T> {
    Some(T);
    None;
}

Option: a value that may be absent.

type enum Result<T, E> {
    Ok(T);
    Err(E);
}

Result: a value that may be an error.

type struct Slice<T> {
    ptr: T*;
    length: u64;
}

Slice<T>: a borrowed view into a contiguous sequence.

type struct Layout {
    size: u64;
    alignment: u64;
}

Layout: size + alignment of a memory block.

type trait Allocator {
    allocate(mut &this, layout: Layout) -> Result<NonNull<u8>, AllocError>;
    deallocate(mut &this, ptr: NonNull<u8>, layout: Layout) -> void;
    reallocate(mut &this, ptr: NonNull<u8>, old_layout: Layout, new_layout: Layout) -> Result<NonNull<u8>, AllocError>;
}

Allocator: the trait every heap strategy implements.

type struct Box<T, A = GlobalAlloc> where A: Allocator {
    ptr: T*;
    alloc: A;
}

Box<T, A>: single-owner heap allocation.

type struct Rc<T, A = GlobalAlloc> where A: Allocator {
    inner: RcInner<T, A>*;
}

Rc<T, A>: single-threaded reference counting, with weak references.

type struct Arc<T, A = GlobalAlloc> where A: Allocator {
    inner: ArcInner<T, A>*;
}

Arc<T, A>: atomic reference counting, with weak references.

type struct Arena {
    head: Chunk*;
    current: Chunk*;
    chunk_size: u64;
}

Arena: bump allocator with bulk release.

type struct Pool {
    slot: Layout;
    slots_per_block: u64;
    free_list: FreeNode*;
    blocks: Block*;
}

Pool: O(1) allocator for uniformly-sized slots.

type struct Str {
    bytes: u8*;
    length: u64;
}

Str: a borrowed UTF-8 string slice.

type struct String<A = GlobalAlloc> {
    buffer: RawBuffer<u8, A>;
    length: u64;
}

String: owned, heap-allocated, length-typed UTF-8.

type struct HashSet<T, A = GlobalAlloc> {
    map: HashMap<T, (), A>;
}

HashSet<T, A>: unordered collection of unique values.

type trait Seek {
    seek(mut &this, from: SeekFrom) -> Result<u64, IoError>;
    stream_position(mut &this) -> Result<u64, IoError>;
    rewind(mut &this) -> Result<(), IoError>;
}

A byte stream whose read/write cursor can be repositioned. Absolute positions are u64 offsets from the start; every seek returns the resulting absolute position.

type struct Cursor {
    buffer: Array<u8>;
    pos: u64;
}

Cursor is also declared in std::net::http2::hpack

An in-memory Read + Write + Seek byte buffer. Owns its Array<u8>; drop releases it (or move it out with into_inner first).

type struct Path {
    inner: Str;
}

Path / PathBuf: filesystem paths as length-typed UTF-8.

type struct File {
    fd: i32;
}

File: Read/Write over a file descriptor.

type struct Command {
    program: String;
    args: Array<String>;
    envs: Array<EnvEntry>;
    clear_env_flag: boolean;
    cwd: Option<String>;
    stdin_cfg: Stdio;
    stdout_cfg: Stdio;
    stderr_cfg: Stdio;
}

Command: builder for spawning a subprocess.

type struct Child {
    stdin: Option<ChildStdin>;
    stdout: Option<ChildStdout>;
    stderr: Option<ChildStderr>;
}

Child: a running subprocess.

type enum Stdio {
    Inherit;
    Null;
    Piped;
    Fd(i32);
}

How a child's stdin / stdout / stderr is wired up.

type struct ExitStatus {
    code: i32;
    signal: i32;
    signaled: boolean;
}

Result of a child's termination. Either it exited normally with a code, or it was killed by a signal. POSIX encodes both into a single wstatus word; ExitStatus is the decoded form.

type struct Duration {
    secs: u64;
    nanos: u32;
}

A length of time: whole secs plus a sub-second nanos remainder (0 <= nanos < 1_000_000_000). POD; copy-by-value, no drop.

type struct Instant {
    secs: i64;
    nanos: i64;
}

A measurement of the monotonic clock. Opaque: the fields are the raw timespec, meaningful only relative to another Instant. POD.

type struct SystemTime {
    secs: i64;
    nanos: i64;
}

A measurement of the wall clock (CLOCK_REALTIME) as a raw timespec. duration_since_epoch() yields a Unix timestamp. Subject to NTP steps and manual changes; do not use for elapsed-time measurement. POD.

type struct DateTime {
    year: i64;
    month: u32;
    day: u32;
    hour: u32;
    minute: u32;
    second: u32;
}

A UTC civil calendar reading. All fields are UTC and already normalized: month in 1..=12, day in 1..=31, hour in 0..=23, minute/second in 0..=59. year is the proleptic Gregorian year and may be negative for timestamps far before the Common Era. POD.

type struct Rng {
    s0: u64;
    s1: u64;
    s2: u64;
    s3: u64;
}

A fast non-cryptographic PRNG (xoshiro256**). The 256-bit state is the four words s0..s3.

type struct SecureRng {}

Cryptographically secure source backed by the kernel CSPRNG. Slower than Rng; use it only where unpredictability matters.

type struct Atomic<T> {
    value: T;
}

A single atomic cell of type T. See the module docs for the supported T and the compile-time dispatch model.

type struct Mutex<T, A = GlobalAlloc> where A: Allocator {
    inner: MutexInner<T, A>*;
}

Mutex<T>: mutual-exclusion lock around a value.

type struct RwLock<T, A = GlobalAlloc> where A: Allocator {
    inner: RwLockInner<T, A>*;
}

RwLock<T>: read/write reader-writer lock around a value.

type struct CondVar {
    inner: CondVarInner*;
}

CondVar: condition variable for blocking until a predicate holds.

type struct Once {
    inner: OnceInner*;
}

Once: one-shot initialization synchronization.

type struct Barrier {
    inner: BarrierInner*;
}

Barrier: thread rendezvous point.

type struct JoinHandle<O> {
    shared: TaskShared<O>*;
    exec: ExecInner*;
}

JoinHandle is also declared in std::thread

A handle to a spawned task, yielding its Output via join(). Dropping a handle without join/detach detaches (the task runs on, its result discarded). abort() requests cancellation.

type struct Builder {
    stack_bytes: u64;
    name_buf: [u8;
    16];
    name_len: u64;
}

A configurable thread spawn: set a stack size and/or an OS-visible thread name, then spawn (panics on failure) or try_spawn (returns a Result). Configuration is applied through a pthread_attr_t; the name is set with pthread_setname_np once the thread is running.

type trait Future {
    type Output;
    poll(mut &this, cx: Context*) -> Poll<This::Output>;
}

An asynchronous computation. poll drives it one step: Ready(v) when the value is available, Pending when it is not yet (the future has arranged, via cx's waker, to be polled again later).

type enum Poll<T> {
    Ready(T);
    Pending;
}

The result of polling a Future: either the final value, or a signal that the value is not ready yet and the task should be re-polled after its Waker fires.

type struct Context {
    waker: Waker;
}

The context threaded through a poll call. Holds the Waker a future registers when it returns Pending. Passed by pointer down the poll tree, matching the stdlib convention of moving aggregates by pointer.

type struct Waker {
    data: u8*;
}

A handle a stalled future stores so it can be re-scheduled: wake_fn(data) tells the executor "poll my task again". This is the manual-vtable shape used throughout the runtime — non-capturing function pointers plus an opaque data pointer identifying the task.

mut &this
mut &Type

An exclusive, mutating borrow. As a receiver, mut &this lets the method modify the fields - and callers can see that from the signature alone. As a parameter type, mut &T lets the callee mutate through the reference while the caller keeps ownership.

&this
mut &this
this

The receiver of a method. Its first parameter declares how the method takes it: &this borrows read-only, mut &this borrows exclusively, and this / mut this move the value in and consume it. In the body, this.field reaches the members.

type struct GlobalAlloc {}

Zero-sized handle to the process-wide allocator. Construct with GlobalAlloc::new(); all instances dispatch through the same underlying backend.