std

The std module provides core language facilities.

Types

Type	Description
AbortError	Raised when execution is aborted by the host trap mechanism.
Array[T]	Arrays are ordered, mutable sequences of values.
@Assign[S @ {...}]	A value that implements the (assign) protocol for the keys in S, which it need not already have.
@AssignSeq[T]	A Seq whose items can be replaced, but not added or removed.
@BaseIter[T]	A value that implements the (next) protocol. Only an Iter also has its methods.
@BaseIterable[T]	A value that implements the (iter) protocol, as for and spreading require. Only an Iterable also has its methods.
@BaseSink[T]	A value that implements the (put) protocol. Only a Sink also has its methods.
@BaseSinkable[T]	A value that implements the (sink) protocol. Only a Sinkable also has its methods.
Bin	Binary data; an immutable sequence of bytes.
BinBuf	Mutable byte buffer; the mutable counterpart to Bin.
Bool	Boolean values: true and false.
BytecodeError	Raised on bytecode verification errors.
CanceledError	Raised when a strand is canceled. During finally blocks, cancellation is masked so cleanup can complete. See Concurrency for details.
CompileError	Raised on compilation errors.
ConcurrencyError	Raised when a concurrent access violation is detected.
CyclicImportError	Raised when a cyclic module dependency is detected.
Dict[S @ {...}]	Dictionaries are ordered, mutable key-value mappings. They preserve insertion order and are multi-maps: a single key can have multiple values.
Error	The abstract base type for all errors. All error types in std inherit from Error, so it can be used as a catch-all in typed catch handlers.
FieldError	Raised when accessing a nonexistent field on an object.
@FlagSet[F]	A set of flags, each named by a symbol in F, such as fs.unix.Mode.
Float	64-bit floating point numbers.
Fmt	An immutable sequence of literal text, bound interpolations, and unbound parameters, produced by a t"..." string.
FmtParam	An unbound interpolation in a Fmt.
FmtSpec	Stores reusable formatting options.
FmtValue	Binds a value to reusable formatting options.
Func	Func is the abstract supertype of function values.
Getter[T, R]	Abstract type for class-field getter objects.
ImmutableError	Raised when attempting to mutate an immutable value.
ImportError	Raised when a module import fails (e.g. module not found).
@Index[S @ {...}]	A value that implements the (index) protocol for the keys in S. A key's presence is not checked, only that the value has such a key.
IndexError	Raised when accessing an array or other indexed collection with an out-of-bounds index.
Int	128-bit signed integers.
Iter[T]	Abstract type for iterators, whose instances have the methods below. Built-in iterators are Iter; a class that only implements (next) is not.
Iterable[T]	Abstract type for iterable values, whose instances have the methods below. Arrays, dicts, and ranges are Iterable; a Record, or a class that only implements (iter), is not.
IterStop	Error raised to signal that an iterator is exhausted. This is used internally by the iteration protocol and can be caught in try/catch statements.
MissingKeyError	Raised when a required key argument is not provided.
MissingPosError	Raised when a required positional argument is not provided.
Module	A module object, produced by import or by loading a compiled module. Its fields are the module's exported bindings.
@MutSeq[T]	A Seq whose items can be replaced, added, and removed.
Nil	The type object for the nil value.
Null	Acts as an empty iterator and a sink that discards every value.
Num	Abstract supertype for numeric values.
OverflowError	Raised on integer overflow.
Range[T @ Num]	Describes a numeric interval for iteration and slicing.
Record[...Ts]	Stores an immutable sequence of positional items and symbol-keyed items.
RuntimeError	Supertype of ordinary catchable runtime failures, and a generic runtime error in its own right when no more specific type applies.
@Seq[T]	An iterable sequence of T, which integers index, slices, spreads, and destructures.
Set[T]	Sets are ordered, mutable collections with unique membership semantics.
Setter[T, V]	Abstract type for class-field setter objects.
Sink[T]	Abstract type for sinks, whose instances have the methods below. Built-in sinks are Sink; a class that only implements (put) is not.
Sinkable[T]	Abstract type for values that sinks can be obtained from, whose instances have the methods below. An Array is Sinkable; a class that only implements (sink) is not.
SinkStop	Error raised to signal that a sink has been closed.
@Spread[S @ {...}]	A value that implements the (spread) protocol, spreading as the items in S.
StateError	Raised when an operation is invalid for the current object or runtime state, such as using a closed handle or stale reference.
Str	Strings are immutable sequences of UTF-8 bytes.
StrBuf	Mutable UTF-8 string buffer; the mutable counterpart to Str.
Sym	Symbols are interned identifiers used for dictionary keys and enum-like values.
TimedOutError	Raised when a strand times out. Timeout is cooperative and is observed at suspend or interrupt-check points.
Tuple[*Ts]	Tuples are immutable, ordered sequences of values. They are produced by certain operations such as iterating over key-value pairs. The Tuple type object is in the prelude, so Tuple(iterable) is available without an explicit import.
Type[T]	The type of a class whose instances are T. Type is the type of all types and cannot be constructed directly.
TypeError	Raised when an operation receives a value of the wrong type.
UnexpectedKeyError	Raised when an unexpected key argument is passed.
UnexpectedPosError	Raised when an unexpected positional argument is passed.
@Unpack[S @ {...}]	A value that implements the (unpack) protocol, destructuring as the items in S.
UnsupportedError	Raised when an unsupported operation is attempted.
Value	Value is the abstract supertype of all values.
ValueError	Raised when a value has an acceptable type but invalid contents, range, or meaning for the operation.
ZeroDivError	Raised on integer division or modulo by zero.
Empty	The type with no values, which a function that never returns can declare as its result.
FmtAlign	An alignment for formatted output.
FmtFill	A fill for formatted output: a single character, or :ZERO: for numeric zero padding.
FmtKind	A representation kind for formatted output. See FmtSpec.kind.
FmtSign	A sign display for formatted numbers.
Phantom[S]	An opaque type that mentions S, for a field that only marks a binder as used.
Union[...Ts]	The union of its type arguments. Union[Int, Str] is (Int | Str), and a pack spreads into one, as in Union[T, ...Us].

Empty = Union[]

The type with no values, which a function that never returns can declare as its result.

FmtAlign = (:LEFT: | :RIGHT: | :CENTER:)

An alignment for formatted output.

FmtFill = (Str | :ZERO:)

A fill for formatted output: a single character, or :ZERO: for numeric zero padding.

FmtKind = (:STR: | :DBG: | :VERBATIM: | :HEX: | :OCT: | :BIN: | :DEC: | :EXP: | :FIXED:)

A representation kind for formatted output. See FmtSpec.kind.

FmtSign = (:PLUS: | :SPACE:)

A sign display for formatted numbers.

Phantom[S]

An opaque type that mentions S, for a field that only marks a binder as used.

Union[...Ts]

The union of its type arguments. Union[Int, Str] is (Int | Str), and a pack spreads into one, as in Union[T, ...Us].

Functions

array[T] ...values -> Array[T]

Creates an array from positional arguments.

Parameters

Name	Type	Description
...values	T

bool value -> Bool

Converts a value to Bool according to its truthiness.

Parameters

Name	Type	Description
value	Value

Example

assert_eq (bool 0) false
assert_eq (bool 1) true
assert_eq (bool nil) false
assert_eq (bool "") false
assert_eq (bool "hello") true

dbg value -> Str

Converts a value to its debug representation. Shows internal structure (e.g. quotes strings, shows type tags).

Parameters

Name	Type	Description
value	Value

dict[...Ts] ...pairs -> Dict[Ts]

Creates a dictionary from positional and key arguments.

Positional arguments receive incrementing integer keys starting at 0. Key arguments become symbol keys. The function-call syntax cannot specify other key types; use a horizontal dictionary literal or vertical data instead.

Parameters

Name	Type	Description
...pairs	Ts

float value -> Float

Coerces or parses a value as a Float.

Parameters

Name	Type	Description
value	(Num | Str)

getter[T, R] func -> Getter[T, R]

Builds a getter object from a function.

Parameters

Name	Type	Description
func	((T) -> R)	Function used for field reads.

Example

class Config
  field port = 8080

  #[getter]
  pub def port obj
    obj.#port

hash *values -> Int

Returns a hash code computed over all supplied values in sequence. Passing multiple values is useful for combining fields in a (hash) implementation:

def (hash) self
  hash $self.x $self.y $self.z

Parameters

Name	Type	Description
*values	Value	Values to hash.

int value -> Int

Coerces or parses a value as an Int.

Parameters

Name	Type	Description
value	(Num | Str)

record[...Ts] ...args -> Record[...Ts]

Creates a record from positional and key arguments.

Positional arguments become positional items, and key arguments become symbol-keyed items.

Parameters

Name	Type	Description
...args	Ts	Positional and key field values.

Example

let r = record name: Alice age: 30
echo $r[:name:]  # Alice

setter[T, V] func -> Setter[T, V]

Builds a setter object from a function.

Parameters

Name	Type	Description
func	((T, V) -> nil)	Function used for field writes.

Example

class Config
  #[setter]
  pub def port obj value
    obj.#_port = value

str value -> Str

Returns the general-purpose Str representation of a value.

Parameters

Name	Type	Description
value	Value

sym value -> Sym

Interns a string as a Sym.

Parameters

Name	Type	Description
value	(Str | Sym)	Value to intern.

tuple[*Ts] *values -> Tuple[...Ts]

Creates a tuple from positional arguments.

Parameters

Name	Type	Description
*values	Ts

type[T] value -> Type[T]

Returns the value's type

Parameters

Name	Type	Description
value	T

Example

assert_eq (type 42) $Int

type[T] value type -> Bool

Tests whether value is an instance of type.

Parameters

Name	Type	Description
value	Value
type	Type[T]

Example

assert (type 42 Int)

verbatim value -> Str

Converts a value to its verbatim representation. Preserves the literal textual form of values where possible, which is useful for passing values as command-line arguments to external programs.

Parameters

Name	Type	Description
value	Value

Values

class

Decorator placing a class member in the type-object namespace, where subclasses inherit it.

Applies to a def or a field inside a class body. A class method receives the class it was reached through as its first parameter. Each class in a hierarchy gets its own storage for a class field, seeded from the declared initializer.

class Counter
  #[class]
  pub field count = 0

  #[class]
  pub def bump cls
    cls.count = (cls.count + 1)
    cls.count

assert_eq $Counter.bump() 1

See static for the uninherited counterpart, and Class and Static Members for the full semantics.

null

The singleton Null value.

As an iterator it ends immediately; as a sink it discards every value.

static

Decorator placing a class member in the type-object namespace without making it inheritable.

Applies to a def or a field inside a class body. Because a static is not inherited, it shadows an inherited class member of the same name without propagating that shadowing to subclasses — which is what makes a static (call) usable as a factory that cannot recurse into itself:

class Shape
  pub field kind = ""

  def (init) self kind
    self.kind = kind

  #[static]
  pub def (call) cls kind
    Type.(call) $cls $kind

class Circle: Shape

let c = Circle "arc"   # default instantiation: the factory is not inherited

See class for the inherited counterpart, and Class and Static Members for the full semantics.