std.core

What the language itself needs: aborting with a reason, the ready-made Throwable, and the interfaces the built-in types satisfy.

panic and coroutineEnded are bound by the compiler, so nothing has to import this module to reach them.

panic function

pub fn panic(message: string): void

Ends the program with message and a backtrace.

Not catchable. Its return type is never, so the flow analysis treats everything after a call as unreachable — which is why expect can return a non-optional after panicking.

stdlib/std/core.lyr:23

coroutineEnded function

pub fn coroutineEnded(): void

Panics because a coroutine was resumed after its body had run to the end.

Called from a dispatcher nobody wrote, which is why nobody could have written the import either.

stdlib/std/core.lyr:30

assert function

pub fn assert(condition: bool, message: string): void

Panics with message when condition is false, for invariants the compiler does not check.

void rather than never: it does not replace a return, and a function ending in assert is still LYR-SEM0017.

stdlib/std/core.lyr:44

todo function

pub fn todo(message: string): void

Marks a place that is still missing. Unlike a comment it reports itself when reached, with not implemented: before the message.

stdlib/std/core.lyr:52

unreachable function

pub fn unreachable(message: string): void

Marks a branch that must never be taken, with unreachable: before the message.

todo means still to come; this means must never happen. Reaching it says that an assumption stated somewhere else is wrong.

stdlib/std/core.lyr:60

Exception class

pub class Exception :: [Throwable]

The ready-made Throwable for throwing a message: throw Exception { text = "…" };.

text: string

What message() returns.

pub fn message(): string

The text this exception was built with.

stdlib/std/core.lyr:72

Display interface

pub interface Display

What can be rendered as text — the anchor for print, println and std.fmt.

Every built-in scalar satisfies it through an extend, and a user type through ::. A value held THROUGH the interface (let d: Display = 5;) stays rejected: an interface value is a fat pointer and needs a reference, which a scalar has none of.

fn show(): string

This value as text.

stdlib/std/core.lyr:95

Equatable interface

pub interface Equatable<T>

Values of this type can be compared for equality.

Generic rather than fn equals(other: Equatable), so both sides carry the concrete type: an interface as a parameter type would need an interface VALUE, and a scalar cannot be one — there would be no Map<int, V>.

fn equals(other: T): bool

Whether the two are equal.

stdlib/std/core.lyr:149

Hashable interface

pub interface Hashable<T> :: [Equatable<T>]

Values of this type can be hashed, which is what a Map key and a Set element need.

Equal values must produce equal hashes. No compiler checks it and every hash table depends on it. The reverse does not hold — two different values may collide.

Hashable<T> implies Equatable<T> (its parent since 2.0): a hash table cannot exist without equality. A key constraint is K :: [Hashable<K>] alone.

fn hash(): int

The hash of this value.

stdlib/std/core.lyr:161

Ordered interface

pub interface Ordered<T>

Values of this type have an order — what sorting and range queries need.

One comparison instead of four methods: <, <=, > and >= all derive from it.

fn compare(other: T): int

Negative when this comes first, zero when the two are equal, positive when other comes first — as strcmp.

stdlib/std/core.lyr:169

Add interface

pub interface Add<T, R>

Values of this type can be added: a + b is a.add(b).

fn add(other: T): R

The sum of this value and other.

stdlib/std/core.lyr:352

Sub interface

pub interface Sub<T, R>

Values of this type can be subtracted: a - b is a.sub(b).

fn sub(other: T): R

This value minus other.

stdlib/std/core.lyr:358

Mul interface

pub interface Mul<T, R>

Values of this type can be multiplied: a * b is a.mul(b).

fn mul(other: T): R

The product of this value and other.

stdlib/std/core.lyr:364

Div interface

pub interface Div<T, R>

Values of this type can be divided: a / b is a.div(b).

fn div(other: T): R

This value divided by other. What a division by zero does is the type's own business; the built-in numerics panic.

stdlib/std/core.lyr:370

Into interface

pub interface Into<T>

A value of this type converts to T: x as T is x.into().

ONE target per type: the method is named into, and a type has one member of a name — a second conversion is an ordinary named method. Total conversions only; a conversion that can fail belongs in a named function returning an optional.

The numeric casts keep their opcodes: 1 as float never goes through here.

fn into(): T

This value as a T.

stdlib/std/core.lyr:467

OnModule interface

pub interface OnModule

A struct declaring this may stand as @Name before the module header.

stdlib/std/core.lyr:477

OnType interface

pub interface OnType

A struct declaring this may stand as @Name before a struct, class or enum declaration.

stdlib/std/core.lyr:480

OnFunction interface

pub interface OnFunction

A struct declaring this may stand as @Name before a top-level function.

stdlib/std/core.lyr:483

WithArg interface

pub interface WithArg<T>

An attribute declaring this takes its one value in parentheses — @On(Event.Damage) — and the value fills the attribute's FIRST field, whose type must be T. The braces form stays open to every attribute; this one is opted into, so a struct's field order never becomes an argument order by accident.

stdlib/std/core.lyr:489

Deprecated struct

pub struct Deprecated :: [OnModule, OnType, OnFunction]

Marks its target as deprecated: the compiler warns at every use, and message says what to use instead. The first attribute the compiler itself reads — it changes diagnostics and nothing else, so a program that ignores the warning runs unchanged.

message: string

What to use instead; shown in the warning at every use site.

until: string

The version this is kept until, as "3.5" — and it is a PROMISE the compiler enforces: building with a toolchain that has reached that version is an error (LYR-SEM0081), so the removal happens because the build stops, not because somebody remembered.

Empty means the ordinary policy: warn now, remove at the next major.

stdlib/std/core.lyr:494