Module std.builtins

Print a value followed by a newline.

Accepts any type that implements Display.

Examples

fn main() {
    println(42);
    println("hello");
    println(true);
}

Print a value without a trailing newline.

Examples

fn main() {
    print("Enter name: ");
}

Assert that a condition is true, raising a recoverable logical fault when it is false.

A failure reports the condition's source text. When the condition is a comparison (==, !=, <, <=, >, >=), both operands are evaluated once and shown, with a line diff when either value spans lines. The optional second argument, assert(condition, message), is a string evaluated only when the assertion fails.

Examples

fn add(a: i64, b: i64) -> i64 {
    a + b
}

fn main() {
    assert(add(1, 2) == 3);
    assert(add(2, 2) > 3, "sums grow");
}

Convert any value to its string representation.

Accepts any type that implements Display — this includes all numeric primitives, bool, char, string, and user types with a Display impl.

Examples

fn main() {
    let s = to_string(42);     // "42"
    let t = to_string(true);   // "true"
    let u = to_string('x');    // "x"
}

Pause execution for the given duration.

The caller suspends cooperatively (inside an actor handler) or blocks the thread (in fn main / free functions).

Sub-millisecond semantics (context-dependent)

Sub-millisecond values behave differently depending on the execution context:

• Actor handlers (cooperative suspend): the duration is converted to milliseconds (floor). A sub-ms value (e.g. 500ns) becomes 0ms, which arms a zero-deadline timer wheel entry and still suspends and resumes the actor at the next scheduler tick. The actor is never truly sleeping for the nanosecond count.
• fn main / free functions (blocking): the OS sleep is requested at full nanosecond precision. sleep(500ns) sleeps for approximately 500 ns (subject to OS timer granularity, typically ≥1 µs on Linux/macOS).
• WASM target: the duration is converted to milliseconds and rounded up to a minimum of 1 ms. sleep(500ns) becomes sleep(1ms) on WASM.

Examples

fn main() {
    sleep(10ms);   // sleep for 10 milliseconds
    sleep(2s);     // sleep for 2 seconds
    sleep(500ms);  // sleep for 500 milliseconds
}

Pause execution until the given monotonic instant.

If target is already in the past, returns immediately. Use instant + duration to construct a future instant:

fn main() {
    let deadline = instant.now() + 10ms;
    sleep_until(deadline);   // wait until 10 ms from now
}

The instant + duration operation adds a duration offset to a monotonic timestamp, returning a new instant. The commutative form (duration + instant) also works.

Examples

fn main() {
    let deadline = instant.now();
    // ... do work ...
    sleep_until(deadline);   // wait until the deadline if not yet reached

    // Sleep for exactly 50 ms from a fixed reference point:
    let t0 = instant.now();
    // ... do work ...
    sleep_until(t0 + 50ms);  // accounts for time already spent
}

Terminate the program immediately with the given exit code.

This function never returns and does not run scope cleanup. Return from main for orderly cleanup. An unrecovered fault instead reports its diagnostic and exits with status 1 on the native path.

Terminate the program with an error message.

This function never returns.

Examples

fn main() {
    panic("something went wrong");
}

Stable key-derived node identity.

Identity of one live actor incarnation. This value grants no actor access.

The authenticated origin of a received handler call.

One handler delivery, consumed by exactly one of proceed or refuse.

A completed handler delivery, returned by its interceptor.

Complete remote actor location.

Source position of a compile-time invocation.

Authenticated distributed node transports. Ordinary QUIC sockets use std.net.quic.

Configuration supplied once to Node.start. Set key to a non-empty identity-file path; NodeConfig.at leaves it empty. Keep that file across restarts so the node identity remains stable.

A node lifecycle operation could not apply the supplied configuration.

An immutable one-way view for void receive handlers. Construct one with mailbox(target, on_full: ...). A receive call through the view submits under that policy and returns as soon as admission or a policy-selected discard is resolved. The policy type records whether submission can suspend. A call on the actor handle itself waits for the handler to finish instead.

An actor-owned one-shot submission view. Construct with mailbox(self, after: delay, overdue: limit); overdue is optional.

A cancellation handle for an actor-owned one-shot request. Dropping this handle does not cancel the request. The handle cannot be sent to another actor; stopping or restarting its owner cancels pending timers.

An immutable completion view choosing how its own calls are admitted. Construct one with policy(target, on_full: ...). A call through the view waits for the handler exactly as a call on the actor handle does; the policy decides only what happens when the destination mailbox is full. .Wait is the bare-handle behaviour; .Reject yields ActorError.Rejected(failure) instead of parking the caller.

Owned request description for one-way submission recovery. Consuming retry() and to(target) retain the request's typing.

Internal owner of an unaccepted completion request.

The request protocol is a sealed, inferred type parameter. The original payload stays inside its runtime owner until admission or cleanup.

A rejected submission retains its complete unaccepted message.

Successful submission describes acceptance or a discard. A discard is a loss either the destination's declared mailbox policy or the sender's own on_full chose; the message is gone either way and nothing is retryable.

A sender chooses how its own submission responds to a full mailbox.

Error returned when a send cannot be completed.

Error returned when Node.lookup(name) cannot resolve a discovery location.

Returned as Err(LookupError.NotFound) when no actor is registered under name on the current node (or any peer with a gossiped name). The variants below cover missing names, unavailable routes, stale references, and caller cancellation.

The error of a handler that cannot fail.

Never has no values, so ActorError<Never>.Failed can never be constructed: a call on an infallible handler reports transport and lifecycle outcomes only.

Error of a completion call on an actor handle.

E is the handler's declared fails type — Never when the handler cannot fail. Req carries an unaccepted request when admission may reject it. Omitted parameters default to Never.

Only Rejected is safely retryable: nothing was accepted, so the caller may make the same call again. Other variants do not return the request or establish whether its handler ran; repeating it may duplicate work.

Failure to subscribe to an actor's exit through link or monitor. Both operations require a current actor to receive the notification; a target that is already dead or unreachable is not an error, it answers with an immediate exit or DOWN.

Ordered, opt-in snapshots taken after exit hooks and before transition bodies.

A bounded machine step did not commit its staged configuration or outputs.

An owned double-ended cursor backed by ordered option slots.

Construction moves the elements into an ordered Vec<Option<T>> and adds one empty scratch slot. Each step exchanges its selected slot with the scratch slot, pops the owned option, and restores the empty scratch slot. Untaken elements remain in logical order, so early drop releases them in that order. Exhaustion leaves a live cursor that drops at scope exit.

Construction takes O(n) time and an additional O(n) buffer, including one option tag per element. An unshared cursor's end steps take O(1) time without cloning elements. Detaching a copied cursor follows ordinary Vec copy-on-write rules and can take O(n) time. Value-copy rules preserve independent source and cursor copies when their elements support cloning; clone-free elements remain owned.

A snapshot cursor over a string's Unicode scalars.

An owned snapshot cursor over a map's paired keys and values.

Each yielded pair is independently owned. The source map remains usable, and later changes to it do not affect this cursor. Iteration order is unspecified. Exhaustion leaves the cursor live until ordinary scope cleanup.

An absolute Unix wall-clock moment with nanosecond precision.

Construction and field access are sealed by the compiler. Use the explicit Unix-unit methods; a timestamp never implicitly becomes an integer or instant.

An invalid normalized timestamp or an overflowing Unix-unit conversion.

A structured scope failure, available only after child and deferred cleanup. Parent cancellation propagates to the enclosing scope and is not recoverable here.

A machine's ordinary staged evaluator and committed transition metadata.

Produce a sequence of values one item at a time.

User-defined iterators implement this trait directly; for loops accept values whose type implements IntoIterator and walk the resulting Iterator to bind each yielded Item.

next takes its receiver mutably (var self): iterator implementations step their internal state in place (cursor advance, decrement remaining, flush a buffer) and surface successive items through the Option<Self.Item> return. Callers must hold the iterator in a var binding so that the mutated receiver remains observable between calls; binding the iterator with let is rejected by the checker with a "receiver requires mutable binding" diagnostic.

Iterator methods with mutable receivers keep the iterator Live past exhaustion; drop fires at scope exit, not at the None return. This is a deliberate shift from a hypothetical by-move shape: exhaustion is a Some → None boundary, not a lifetime boundary. Iterator implementations that own non-shared resources (heap-owning buffers, channel readers) inherit the "exhaustion ≠ drop" invariant — see the lifecycle-symmetry invariant in docs/internal/engineering-invariants.md.

An iterator whose front and back share the same remaining items.

Convert a value into an Iterator.

For trait-based iteration, a for loop creates a mutable iterator and calls next() until it returns None. The item type is <Self.IntoIter as Iterator>.Item. Built-in collections also support borrowed iteration; a loop over an unbounded generic Vec<T> borrows its elements rather than taking ownership of them.

IntoIter carries the Iterator<Item = Self.Item> bound so that callers projecting <T as IntoIterator>.IntoIter.Item always agree with <T as IntoIterator>.Item. Concrete IntoIterator impls live next to each collection (Vec, HashSet, HashMap); this trait declaration reserves the surface only.

c[i] and c.get(i) for EVERY indexable collection resolve through this trait. A new collection type gets both accessors by writing one impl — no compiler change (the A195 mandate).

• get(self, i) -> Option<Self.Output> is the FUNDAMENTAL safe accessor: None on out-of-bounds/absent, else Some(elem) where the payload is a FRESH, independently-droppable owner (retain-share for strings, deep clone for owned records/enums, by-value for scalars). The container is borrowed, not consumed.
• at(self, i) -> Self.Output is the TRAPPING accessor: c[i]. It asserts presence and traps (TrapKind.IndexOutOfBounds) on absence.

Idx is a trait TYPE PARAMETER (not an associated type) so a collection may index by more than one key type (Vec/bytes/string by i64; HashMap by K), and a future Index<Range> slicing convergence is accommodated.

Leaf containers (Vec/HashMap/bytes/string) carry intrinsic bodies the compiler lowers directly (the index_get/index_at lang-items); user composites write ordinary Hew bodies that delegate to a leaf's get.

Convert a value of type Self into a human-readable string.

Implementing Display for a type lets it flow through print, println, to_string, len, and stop. The trait method must return a string derived from the receiver without invoking print itself (otherwise the output path becomes recursive).

Blanket impls below cover the primitive numeric kinds, bool, char, and string; user types add their own impls per receiver.

The marker an error type carries so it can be erased to dyn Error.

Error adds no methods of its own: an error is a value that can say what went wrong, so Display is the whole obligation. impl Error for MyError {} on a type that declares no Display supplies one: the variant name, then ": " and the payloads, each through its own Display.

Declares that a Source error converts into Self where a failure leaves a function. ? and return error apply it; everywhere else the conversion is the explicit call Target.from(value).

A conversion never chains, and erasure into dyn Error needs no impl.