Module std::builtins

Print a value followed by a newline.

Accepts any type that implements Display.

Examples

println(42);
println("hello");
println(true);

Print a value without a trailing newline.

Examples

print("Enter name: ");

Assert that a condition is true. Panics if condition is false.

Examples

assert(x > 0);

Assert that two values are equal. Panics with a diff if they differ.

Both arguments must be the same type.

Examples

assert_eq(add(1, 2), 3);

Assert that two values are not equal. Panics if they are the same.

Both arguments must be the same type.

Examples

assert_ne(a, b);

Returns the absolute value of an integer.

Examples

let x = abs(-5);  // 5

Returns the square root of a floating-point number.

Examples

let r = sqrt(9.0);  // 3.0

Returns the smaller of two integers.

Returns the larger of two integers.

Convert an integer to a floating-point number.

Examples

let f = to_float(42);  // 42.0

Concatenate two strings, returning a new string.

Examples

let full = string_concat("hello ", "world");

Returns the byte length of a string.

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

let s = to_string(42);     // "42"
let t = to_string(true);   // "true"
let u = to_string('x');    // "x"

Returns the length of a collection or string.

Returns the character (as a char) at the given byte index.

Test whether two strings are equal.

Convert an integer to a string.

Examples

let s = string_from_int(42);  // "42"

Test whether haystack contains needle.

Test whether a string starts with the given prefix.

Extract a substring by byte indices [start, end).

Examples

let s = substring("hello", 0, 3);  // "hel"

Strip leading and trailing whitespace.

Parse a string as an integer. Returns 0 on failure.

Find the first occurrence of needle in haystack.

Returns the byte offset, or -1 if not found.

Read the entire contents of a file as a string.

Write a string to a file, creating or overwriting it.

Pause execution for the given number of milliseconds.

Pause execution for the given number of seconds.

Stop an actor gracefully.

Terminate the program with the given exit code.

This function never returns.

Terminate the program with an error message.

This function never returns.

Examples

panic("something went wrong");

A process-local actor pid returned by spawn.

LocalPid<T> is accepted by all built-in actor functions (close, link, monitor, etc.) and by any function that takes dyn Pid<Msg = M>.

Coercion to a remote pid is explicit:

let remote = pid.to_remote_via(node_handle);

An actor pid on a remote node.

Produced by peer-discovery or explicit construction via RemotePid::from_raw. Does NOT coerce implicitly to LocalPid<T> — remote actors are a distinct class.

.tell is a fail-closed stub until S4 wires up hew_actor_send_remote.

SHIM

RemotePid::from_raw is scaffolding for S1 tests. .tell fails closed with SendError::NodeRoutingNotWired until hew_actor_send_remote lands.

Error returned when a pid send cannot be completed.

Error returned when Node::lookup<T>(name) cannot resolve name.

Returned as Err(LookupError::NotFound) when no actor is registered under name on the current node (or any peer with a gossiped name). Future variants (e.g. transport-level failures, schema mismatches) are deferred to follow-on polish; today the runtime collapses every failure into NotFound since the underlying registry surface is fail-closed per set_last_error for the diagnostic detail.

Error returned when a remote actor ask cannot complete.

Variant order matches the native runtime ask ABI so codegen can project the runtime error discriminant directly into this public enum.

Error arm of await rx.recv() | after d and await stream.recv() | after d.

Returned as Err(TimeoutError::Timeout) when the deadline fires before an item arrives. Distinguishes a timeout from a closed channel (Ok(None)).

match await rx.recv() | after 50ms {
    Ok(Some(v)) => v,       // item received before deadline
    Ok(None)    => -1,      // channel closed (no deadline race)
    Err(_)      => -2,      // deadline fired
}

Cursor iterator over a Vec<T> produced by vec.into_iter().

VecIter<T> is the concrete IntoIterator::IntoIter for Vec<T> — it pairs the owned vector with the current idx cursor so that for x in v { ... } (for-loop desugar) and the lazy combinators in std/iter can drive iteration through the trait surface rather than the per-type *_int / *_str / *_f64 table.

next takes a mutable receiver: each call reads the current element and then bumps self.idx in place via a field-store. idx advances once per call until it reaches the vector's length, after which every subsequent next returns None. The receiver remains Live after exhaustion and drops at scope exit — see the Iterator trait doc-comment.

Vec is a refcounted heap handle, so the cursor carries the underlying vector storage by handle (no per-step copy).

Lives in std/builtins.hew rather than std/vec.hew so it registers alongside the Vec Index impl through register_builtins_hew_impls (the per-stdlib-module receiver-impl harness only handles a fixed set of receivers; auto-registration on builtin nominals belongs in builtins).

Monotonic timestamp captured by the runtime.

Message contract for actor types used behind LocalPid<A> / RemotePid<A>.

Named actors opt into the erased Pid surface by implementing this trait and binding Msg to the envelope type accepted by .tell / .ask, plus Reply to the response type returned by .ask.

Trait satisfied by both LocalPid<A> and RemotePid<A>.

Future surface target for accepting either local or remote pids. A640: generic P: Pid sends are fail-closed unless P::Msg is concretely proven Serializable; local-only dispatch through LocalPid<T> keeps the value model below.

fn ping<P: Pid>(p: P, msg: P::Msg) -> Result<(), SendError> {
    p.tell(msg)
}

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 LESSONS.md.

Convert a value into an Iterator.

for x in expr { ... } desugars to let mut it = expr.into_iter(); loop { match it.next() { Some(x) => ..., None => break } } — the iterable on the right of in must implement IntoIterator, and the loop binding is typed as <Self::IntoIter as Iterator>::Item.

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.

Bracket indexing surface for values that define an element lookup.

obj[k] type-checks through this trait for user-defined receivers. Vec keeps its compiler-backed bounds-check/runtime path, with this impl providing the same trait surface for bounds and associated-type projection.

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

Implementing Display for a type lets it flow through print, println, assert_eq, assert_ne, 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.