std/core

Always in scope — no import required.

The core data types with their methods, scalar math, and the global utility and transport functions.

Array

The Array type and its utilities.

An Array is an ordered, growable collection of values of any type, written with the #[1, 2, 3] literal. Its methods index and slice, add and remove elements, and transform, filter, and fold — most returning arrays so calls chain.

Array

Ordered collection of values. Construct with #[1, 2, 3] or Array(1, 2, 3).

Constructor

fn Array(...items) -> Array

Creates an array from individual values. Prefer the #[1, 2, 3] literal syntax. This constructor is kept for compatibility.

Example:

Array(1, 2, 3) returns #[1, 2, 3]

Parameters:

items (Array) — variadic values to collect into the array

Returns: Array — a new array of the given values

length

fn length() -> Number

Returns the number of elements.

Returns: Number — the element count

push

fn push(value: any) -> Array

Adds an element to the end of the array.

Parameters:

value (Any) — the element to add

Returns: Array — the array, for chaining

pop

fn pop()

Removes and returns the last element. Errors on empty array.

Returns: Any — the removed last element

get

fn get(index: Number)

Returns the element at the given index. Errors if the index is out of bounds.

Parameters:

index (Number) — zero-based position

Returns: Any — the element at index

slice

fn slice(start: Number, end: Number) -> Array

Returns a subarray from start (inclusive) to end (exclusive).

Parameters:

start (Number) — start index (inclusive, 0-based)
end (Number) — end index (exclusive)

Returns: Array — the subarray

concat

fn concat(other: Array) -> Array

Returns a new array with elements from both arrays.

Parameters:

other (Array) — array to append

Returns: Array — a new array with the elements of both

reverse

fn reverse() -> Array

Returns a new array with elements in reverse order.

Returns: Array — a new reversed array

contains

fn contains(value: any) -> Boolean

Returns true if the array contains the given value.

Parameters:

value (Any) — the value to search for

Returns: Boolean — true if the value is present

map

fn map(func: Function) -> Array

Applies a function to each element, returns a new array.

Parameters:

func (Function) — fn(element) -> new_element

Returns: Array — a new array of transformed elements

filter

fn filter(func: Function) -> Array

Returns a new array with only elements satisfying the predicate.

Parameters:

func (Function) — fn(element) -> bool

Returns: Array — a new array of matching elements

reduce

fn reduce(func: Function, initial: any)

Reduces the array to a single value.

Parameters:

func (Function) — fn(accumulator, element) -> new_accumulator
initial (Any) — starting accumulator value

Returns: Any — the final accumulated value

iter

fn iter() -> Iterator

Returns an iterator over the array elements.

Returns: Iterator — an iterator over the elements

concat

fn concat(array1: Array, array2: Array) -> Array

Concatenates two arrays.

Parameters:

array1 (Array) — first array
array2 (Array) — second array

Returns: Array — a new array containing all elements from both arrays

filter

fn filter(array: Array, func: Function) -> Array

Selects elements from an array that satisfy a predicate.

Example:

filter([1, 2, 3, 4], fn(x) { x > 2; }) returns [3, 4]

Parameters:

array (Array) — the array to filter
func (Function) — returns truthy/falsy for each element

Returns: Array — a new array of matching elements

fold

fn fold(array: Array, initial: any, func: Function) -> any

Reduces an array to a single value using an accumulator function.

Example:

fold([1, 2, 3], 0, fn(acc, x) { acc + x; }) returns 6

Parameters:

array (Array) — the array to reduce
initial (Any) — starting value for the accumulator
func (Function) — takes (accumulator, element), returns new accumulator

Returns: Any — the final accumulated value

length

fn length(array: Array) -> Number

Returns the number of elements in an array.

Parameters:

array (Array) — the array to measure

Returns: Number — the element count

map

fn map(array: Array, func: Function) -> Array

Transforms each element of an array using a function.

Example:

map([1, 2, 3], fn(x) { x * 2; }) returns [2, 4, 6]

Parameters:

array (Array) — the array to transform
func (Function) — takes one element, returns the transformed value

Returns: Array — a new array of transformed elements

range

fn range(start_or_end: Number, end: Number = NUL) -> Array

Generates an array of sequential numbers.

range(3);      // => #[0, 1, 2]
range(2, 5);   // => #[2, 3, 4]

Parameters:

start_or_end (Number) — if called with one arg, this is the end (start=0); if called with two args, this is the start
end (Number) — exclusive upper bound

Returns: Array — sequential numbers from start to end-1

slice

fn slice(array: Array, start: Number, end: Number) -> Array

Extracts a subarray from start index to end index.

Parameters:

array (Array) — the source array
start (Number) — start index (inclusive, 0-based)
end (Number) — end index (exclusive)

Returns: Array — the subarray

String

The String type: text values.

A String is a Unicode-aware run of text written with "..." literals. Its methods query length and case, split and join, search, slice, and convert text — returning new strings rather than mutating in place.

String

Text value with Unicode support. Construct with literal syntax "hello".

length

fn length() -> Number

Returns the character count (Unicode-aware).

Returns: Number — the character count

uppercase

fn uppercase() -> String

Returns the string converted to uppercase.

Returns: String — the uppercased string

lowercase

fn lowercase() -> String

Returns the string converted to lowercase.

Returns: String — the lowercased string

substring

fn substring(start: Number, end: Number) -> String

Returns a substring from start to end (Unicode-aware).

Parameters:

start (Number) — start index (inclusive, 0-based)
end (Number) — end index (exclusive)

Returns: String — the substring

split

fn split(delimiter: String) -> Array

Splits the string by a delimiter, returns an array of strings.

Parameters:

delimiter (String) — the string to split on

Returns: Array — the parts as Strings

contains

fn contains(needle: String) -> Boolean

Returns true if the string contains the given substring.

Parameters:

needle (String) — the substring to search for

Returns: Boolean — true if needle is present

trim

fn trim() -> String

Returns the string with leading and trailing whitespace removed.

Returns: String — the trimmed string

replace

fn replace(old: String, new: String) -> String

Returns the string with all occurrences of old replaced with new.

Parameters:

old (String) — the substring to find
new (String) — the replacement string

Returns: String — the string with replacements applied

starts_with

fn starts_with(prefix: String) -> Boolean

Returns true if the string starts with the given prefix.

Parameters:

prefix (String) — the prefix to check

Returns: Boolean — true if the string starts with prefix

ends_with

fn ends_with(suffix: String) -> Boolean

Returns true if the string ends with the given suffix.

Parameters:

suffix (String) — the suffix to check

Returns: Boolean — true if the string ends with suffix

repeat

fn repeat(n: Number) -> String

Returns a new string by repeating this string n times.

Parameters:

n (Number) — number of repetitions

Returns: String — the repeated string

iter

fn iter() -> Iterator

Returns an iterator over the characters.

Returns: Iterator — an iterator over the characters

Dict

The Dict type: key–value maps.

A Dict maps String or Number keys to values of any type. Construct one with the #{"key": value} literal, then read, update, and iterate its entries. Keys are unique, so setting an existing key updates it in place.

Dict

Key-value mapping with String or Number keys. Construct with #{"key": value} literal syntax.

get

fn get(key: String or Number)

Returns the value for the given key, or NUL if not found.

Parameters:

key (String | Number) — the key to look up

Returns: Any — the value for key, or NUL if absent

set

fn set(key: String or Number, value: any) -> Dict

Sets a key-value pair in place.

Parameters:

key (String | Number) — the key to set
value (Any) — the value to associate

Returns: Dict — the dict, for chaining

remove

fn remove(key: String or Number)

Removes a key in place.

Parameters:

key (String | Number) — the key to remove

Returns: Any — the removed value, or NUL if the key was not found

keys

fn keys() -> Array

Returns an Array of all keys.

Returns: Array — all keys

values

fn values() -> Array

Returns an Array of all values.

Returns: Array — all values

length

fn length() -> Number

Returns the number of entries.

Returns: Number — the entry count

contains_key

fn contains_key(key: String or Number) -> Boolean

Returns true if the dict contains the given key.

Parameters:

key (String | Number) — the key to check

Returns: Boolean — true if key is present

entries

fn entries() -> Array

Returns an Array of [key, value] pairs.

Returns: Array — one [key, value] pair per entry

merge

fn merge(other: Dict) -> Dict

Returns a new dict with entries from both dicts merged. Does not mutate either dict.

Parameters:

other (Dict) — dict to merge in (its keys override on conflict)

Returns: Dict — a new merged dict

map

fn map(func: Function) -> Dict

Transforms values using a function.

Parameters:

func (Function) — fn(key, value) -> new_value

Returns: Dict — a new dict with transformed values

filter

fn filter(func: Function) -> Dict

Filters entries by predicate.

Parameters:

func (Function) — fn(key, value) -> bool

Returns: Dict — a new dict with matching entries

reduce

fn reduce(func: Function, initial: any)

Reduces entries to a single value.

Parameters:

func (Function) — fn(accumulator, key, value) -> new_accumulator
initial (Any) — starting accumulator value

Returns: Any — the final accumulated value

iter

fn iter() -> Iterator

Returns an Iterator over the keys.

Returns: Iterator — an iterator over the keys

Iterator

The Iterator type: lazy sequences.

An Iterator is a lazy stream of values with chainable transformations (map, filter, take, and more) that compute only as elements are pulled. Obtain one with .iter() on an array, string, or pattern, and materialize the result with .collect().

Iterator

Lazy sequence of values with chainable transformations. Obtain from .iter() on arrays, strings, or patterns.

Advancing

fn next()

Returns the next value, or nil if exhausted.

Returns: Any — the next value, or nil if exhausted

take

fn take(n: Number) -> Iterator

Returns a lazy iterator yielding the first n elements.

Parameters:

n (Number) — maximum number of elements to yield

Returns: Iterator — a lazy iterator over the first n elements

skip

fn skip(n: Number) -> Iterator

Returns a lazy iterator that skips the first n elements.

Parameters:

n (Number) — number of elements to skip

Returns: Iterator — a lazy iterator past the first n elements

step_by

fn step_by(step: Number) -> Iterator

Returns a lazy iterator yielding every nth element.

Parameters:

step (Number) — take every nth element

Returns: Iterator — a lazy iterator over every step-th element

Transforming

enumerate

fn enumerate() -> Iterator

Returns a lazy iterator yielding [index, value] pairs.

Returns: Iterator — a lazy iterator of [index, value] pairs

map

fn map(func: Function) -> Array

Applies a function to each element, returns an array.

Parameters:

func (Function) — fn(element) -> new_element

Returns: Array — a new array of transformed elements

filter

fn filter(func: Function) -> Array

Filters elements by predicate, returns an array.

Parameters:

func (Function) — fn(element) -> bool

Returns: Array — a new array of matching elements

zip

fn zip(other: Iterator) -> Iterator

Zips this iterator with another, yielding [a, b] pairs.

Parameters:

other (Iterator) — iterator to zip with

Returns: Iterator — a lazy iterator of [a, b] pairs

chain

fn chain(other: Iterator) -> Iterator

Chains another iterator after this one.

Parameters:

other (Iterator) — iterator to append

Returns: Iterator — a lazy iterator over both in sequence

flatten

fn flatten() -> Array

Flattens nested arrays into a single array.

Returns: Array — the flattened elements

Consuming

collect

fn collect() -> Array

Collects all remaining elements into an array.

Returns: Array — the remaining elements

count

fn count() -> Number

Counts remaining elements (consumes the iterator).

Returns: Number — the count of remaining elements

first

fn first()

Returns the first element, or nil if empty.

Returns: Any — the first element, or nil if empty

last

fn last()

Returns the last element, or nil if empty. Warning: consumes the entire iterator; hangs on infinite iterators.

Returns: Any — the last element, or nil if empty

find

fn find(func: Function)

Returns the first element matching the predicate, or nil.

Parameters:

func (Function) — fn(element) -> bool

Returns: Any — the first matching element, or nil

any

fn any(func: Function) -> Boolean

Returns true if any element matches the predicate.

Parameters:

func (Function) — fn(element) -> bool

Returns: Boolean — true if at least one element matches

all

fn all(func: Function) -> Boolean

Returns true if all elements match the predicate.

Parameters:

func (Function) — fn(element) -> bool

Returns: Boolean — true if every element matches

fold

fn fold(initial: any, func: Function)

Folds the iterator to a single value.

Parameters:

initial (Any) — starting accumulator value
func (Function) — fn(accumulator, element) -> new_accumulator

Returns: Any — the final accumulated value

Utilities

Global utility and introspection functions.

Cross-cutting helpers that don’t belong to a single type: high-resolution timing and sleeping, value inspection (type, show), loading files, and hot-reloading native extensions. All are in scope anywhere in a script.

clock

fn clock() -> Number

Returns time in nanoseconds from an arbitrary reference point. Useful for benchmarking and timing operations.

Returns: Number — nanoseconds from an arbitrary reference point

load_file

fn load_file(path: String) -> String

Reads a text file and returns its contents as a String. The path is resolved relative to the directory of the .non file being run (falling back to the working directory). Useful for keeping GLSL shaders in external files: gfx.Visual(load_file("shaders/plasma.glsl")).

Parameters:

path (String) — file path, relative to the current .non file

Returns: String — the file contents (UTF-8)

print

fn print(value: any, newline: Boolean = true) -> NUL

Writes a value to the output, followed by a newline. Instances that define __str__ are formatted through it.

Parameters:

value (Any) — value to write
newline (Boolean) — append a trailing newline; pass false to suppress it

Returns: NUL — nothing

put

fn put(value: any) -> NUL

Writes a value to the output with no trailing newline. Shorthand for print(value, false); useful for building a line piecewise.

Parameters:

value (Any) — value to write

Returns: NUL — nothing

reload_ext

fn reload_ext(name: String) -> NUL

Reloads a native extension from disk. Fails if any objects from the extension still exist — drop them first.

Parameters:

name (String) — extension name to reload

Returns: NUL — nothing

show

fn show(value: any = NUL) -> NUL

Displays detailed information about a value. For modules: name, path, exports, and documentation. For functions: the full typed signature, parameter types, and doc comments. For other values: the runtime type and representation.

Parameters:

value (Any) — any resonon value

Returns: NUL — nothing; prints the information

sleep

fn sleep(seconds: Number) -> NUL

Pauses execution for the given number of seconds.

Useful for timed recording, waiting for hardware, or scripted workflows.

Parameters:

seconds (Number) — duration to sleep (e.g. 1.5 for 1500ms)

Returns: NUL — nothing

type

fn type(value: any = NUL) -> String

Returns the type name of a value as a string.

Parameters:

value (Any) — any resonon value

Returns: String — the value’s type name

Math

Scalar math functions.

These mirror the math builtins available inside dsp blocks, so the same vocabulary works in scripts and DSP graphs. All operate on Number.

abs

fn abs(x: Number) -> Number

Absolute value.

Parameters:

x (Number) — the input value

Returns: Number — the absolute value

ceil

fn ceil(x: Number) -> Number

Smallest integer greater than or equal to the value.

Parameters:

x (Number) — the input value

Returns: Number — the ceiling

clamp

fn clamp(x: Number, lo: Number, hi: Number) -> Number

Constrains a value to the inclusive range [lo, hi].

Parameters:

x (Number) — the value to constrain
lo (Number) — lower bound
hi (Number) — upper bound

Returns: Number — the clamped value

cos

fn cos(x: Number) -> Number

Cosine of an angle in radians.

Parameters:

x (Number) — angle in radians

Returns: Number — the cosine

exp

fn exp(x: Number) -> Number

Exponential function (e raised to the power x).

Parameters:

x (Number) — the exponent

Returns: Number — e to the power x

floor

fn floor(x: Number) -> Number

Largest integer less than or equal to the value.

Parameters:

x (Number) — the input value

Returns: Number — the floor

fract

fn fract(x: Number) -> Number

Fractional part of the value (the part after the decimal point).

Parameters:

x (Number) — the input value

Returns: Number — the fractional part

ftom

fn ftom(freq: Number) -> Number

Converts a frequency in Hz to a MIDI note number.

Parameters:

freq (Number) — frequency in Hz

Returns: Number — MIDI note number (may be fractional)

lerp

fn lerp(a: Number, b: Number, t: Number) -> Number

Linearly interpolates between two values.

Parameters:

a (Number) — start value (t = 0)
b (Number) — end value (t = 1)
t (Number) — interpolation factor

Returns: Number — the interpolated value

log

fn log(x: Number) -> Number

Natural logarithm (base e).

Parameters:

x (Number) — the input value

Returns: Number — the natural logarithm

log10

fn log10(x: Number) -> Number

Base-10 logarithm.

Parameters:

x (Number) — the input value

Returns: Number — the base-10 logarithm

log2

fn log2(x: Number) -> Number

Base-2 logarithm.

Parameters:

x (Number) — the input value

Returns: Number — the base-2 logarithm

max

fn max(a: Number, b: Number) -> Number

Larger of two numbers.

Parameters:

a (Number) — first value
b (Number) — second value

Returns: Number — the larger value

min

fn min(a: Number, b: Number) -> Number

Smaller of two numbers.

Parameters:

a (Number) — first value
b (Number) — second value

Returns: Number — the smaller value

mtof

fn mtof(note: Number) -> Number

Converts a MIDI note number to frequency in Hz.

Parameters:

note (Number) — MIDI note number (69 = A4 = 440 Hz)

Returns: Number — frequency in Hz

pow

fn pow(base: Number, exponent: Number) -> Number

Raises a base to a power.

Parameters:

base (Number) — the base
exponent (Number) — the exponent

Returns: Number — base raised to the exponent

round

fn round(value: Number, places: Number = 0) -> Number

Rounds a number to the given number of decimal places.

Parameters:

value (Number) — the number to round
places (Number) — decimal places

Returns: Number — the rounded number

sin

fn sin(x: Number) -> Number

Sine of an angle in radians.

Parameters:

x (Number) — angle in radians

Returns: Number — the sine

sqrt

fn sqrt(x: Number) -> Number

Square root.

Parameters:

x (Number) — the input value

Returns: Number — the square root

tan

fn tan(x: Number) -> Number

Tangent of an angle in radians.

Parameters:

x (Number) — angle in radians

Returns: Number — the tangent

tanh

fn tanh(x: Number) -> Number

Hyperbolic tangent.

Parameters:

x (Number) — the input value

Returns: Number — the hyperbolic tangent