Builtin Functions

Every built-in function in WCL — its signature, parameters, return value, and a usage example. Reflection and meta built-ins are introspected with fn_signature.

Index

• abs
• acos
• asin
• assert
• ast_string
• at
• atan
• atan2
• builtin_names
• cbrt
• ceil
• child_types
• clamp
• concat
• contains
• cos
• decorator_arg
• decorator_names
• degrees
• drop
• e
• ends_with
• error
• eval
• exp
• filter
• flatten
• floor
• fn_signature
• fold
• format
• head
• hypot
• index_of
• join
• len
• list_contains
• ln
• log10
• log2
• map
• max
• min
• panic
• pi
• pow
• radians
• range
• replace
• reverse
• round
• sign
• sin
• sort
• sort_connected
• split
• sqrt
• starts_with
• sum
• tail
• take
• tan
• tau
• tensor
• tensor_data
• tensor_reshape
• tensor_shape
• to_lower
• to_upper
• trim
• trunc
• type_fields
• unique
• zip

Functions

abs

abs(x: number) -> f64

Absolute value.

Example

abs(-5)   // 5.0

acos

acos(x: number) -> f64

Arccosine, in radians, of a value in [-1, 1].

Example

acos(1)   // 0.0

asin

asin(x: number) -> f64

Arcsine, in radians, of a value in [-1, 1].

Example

asin(1)   // 1.5707963…  (π/2)

assert

assert(cond: bool, msg: utf8) -> none

Return none when cond is true, otherwise abort with msg.

Example

assert(len(xs) > 0, "list must not be empty")

ast_string

ast_string(target: &T) -> utf8

Pretty-print the canonical source behind a reference (type/interface/union/symbol_set/block/field) or a function value.

Example

ast_string(Image)   // the Image type's source, pretty-printed

at

at(xs: [T], i: i64) -> T

The element at a zero-based index; errors if out of bounds or negative.

Example

at([10, 20, 30], 1)   // 20

atan

atan(x: number) -> f64

Arctangent, in radians.

Example

atan(1)   // 0.7853981…  (π/4)

atan2

atan2(a: number, b: number) -> f64

Arctangent of a/b in radians, using the signs of both to pick the quadrant.

Example

atan2(1, 1)   // 0.7853981…  (π/4)

builtin_names

builtin_names() -> [utf8]

The names of every registered built-in function, sorted. Pair with fn_signature to introspect each one.

Example

builtin_names()   // ["abs", "acos", …, "zip"]

cbrt

cbrt(x: number) -> f64

Cube root.

Example

cbrt(27)   // 3.0

ceil

ceil(x: number) -> f64

Round up to the nearest integer.

Example

ceil(2.1)   // 3.0

child_types

child_types(target: &T) -> [&T]

Reflect a type into references to the element types of its @child / @children block slots (own slots first, then inherited via extends). Pair with type_table / type_fields to auto-document the blocks a @document declares.

Example

child_types(MyDoc)   // [&ProjectMeta, &Settings] — the element types of MyDoc's block slots

clamp

clamp(x: number, lo: number, hi: number) -> f64

Constrain x to the range [lo, hi].

Example

clamp(12, 0, 10)   // 10.0

concat

concat(a: utf8, b: utf8) -> utf8

Concatenate two strings into one.

Example

concat("foo", "bar")   // "foobar"

contains

contains(s: utf8, needle: utf8) -> bool

Whether a string contains a substring.

Example

contains("hello", "ell")   // true

cos

cos(x: number) -> f64

Cosine of an angle in radians.

Example

cos(0)   // 1.0

decorator_arg

decorator_arg(target: &T, decorator: utf8, slot: utf8) -> any

Read one named argument of a decorator on a referenced declaration (none if absent).

Example

decorator_arg(Image, "block", "name")   // "image"

decorator_names

decorator_names(target: &T) -> [utf8]

List the names of the decorators attached to a referenced declaration.

Example

decorator_names(Image)   // ["block", "schemaless", …]

degrees

degrees(x: number) -> f64

Convert an angle from radians to degrees.

Example

degrees(pi())   // 180.0

drop

drop(xs: [T], n: i64) -> [T]

Every element of a list after the first n.

Example

drop([1, 2, 3, 4], 2)   // [3, 4]

e

e() -> f64

Euler's number e (≈ 2.71828).

Example

e()   // 2.71828…

ends_with

ends_with(s: utf8, suffix: utf8) -> bool

Whether a string ends with a suffix.

Example

ends_with("hello", "lo")   // true

error

error(msg: utf8) -> never

Abort evaluation with an error message.

Example

if found { value } else { error("config not found") }

eval

eval(src: utf8) -> any

Parse a string as a WCL expression and evaluate it in the current scope.

Example

eval("1 + 2 * 3")   // 7

exp

exp(x: number) -> f64

e raised to the power x.

Example

exp(1)   // 2.71828…

filter

filter(xs: [T], pred: fn (T) -> bool) -> [T]

Keep only the list elements for which the predicate returns true.

Example

filter(range(0, 6), fn(x: i64) -> bool x % 2 == 0)   // [0, 2, 4]

flatten

flatten(xss: [[T]]) -> [T]

Concatenate a list of lists into a single list, one level deep.

Example

flatten([[1, 2], [3], [4, 5]])   // [1, 2, 3, 4, 5]

floor

floor(x: number) -> f64

Round down to the nearest integer.

Example

floor(2.7)   // 2.0

fn_signature

fn_signature(f: any) -> record

Describe a function's parameters and return type. Pass a function value, or a built-in's name as a string.

Example

fn_signature("map")   // { signature: "fn(xs: [T], …) -> [U]", params: […], … }

fold

fold(xs: [T], init: U, f: fn (U, T) -> U) -> U

Reduce a list or tensor to a single value by repeatedly combining the accumulator with each element.

Example

fold([1, 2, 3, 4], 0, fn(acc: i64, x: i64) -> i64 acc + x)   // 10

format

format(utf8, ...args) -> utf8

Substitute trailing arguments into a template's {} placeholders ({{/}} are literal braces).

Example

format("{} = {}", "x", 42)   // "x = 42"

head

head(xs: [T]) -> T

The first element of a list or tensor (none when empty).

Example

head([10, 20, 30])   // 10

hypot

hypot(a: number, b: number) -> f64

Length of the hypotenuse sqrt(a² + b²).

Example

hypot(3, 4)   // 5.0

index_of

index_of(xs: [T], needle: T) -> i64

The index of the first element equal to needle, or -1 if absent.

Example

index_of(["a", "b", "c"], "b")   // 1
index_of(["a", "b"], "z")        // -1

join

join(parts: [utf8], sep: utf8) -> utf8

Join a list of strings into one, inserting a separator between each.

Example

join(["a", "b", "c"], "-")   // "a-b-c"

len

len(xs: [T]) -> usize

The number of elements in a list or tensor, or characters in a string.

Example

len([10, 20, 30])   // 3
len("hello")        // 5

list_contains

list_contains(xs: [T], needle: T) -> bool

Whether a list contains a value equal to needle.

Example

list_contains([1, 2, 3], 2)   // true

ln

ln(x: number) -> f64

Natural (base-e) logarithm.

Example

ln(e())   // 1.0

log10

log10(x: number) -> f64

Base-10 logarithm.

Example

log10(1000)   // 3.0

log2

log2(x: number) -> f64

Base-2 logarithm.

Example

log2(8)   // 3.0

map

map(xs: [T], f: fn (T) -> U) -> [U]

Apply a function to every element of a list or tensor, returning the transformed collection.

Example

map([1, 2, 3], fn(x: i64) -> i64 x * 2)   // [2, 4, 6]

max

max(a: number, b: number) -> f64

The larger of two numbers.

Example

max(3, 7)   // 7.0

min

min(a: number, b: number) -> f64

The smaller of two numbers.

Example

min(3, 7)   // 3.0

panic

panic(msg: utf8) -> never

Abort evaluation with an unrecoverable failure message.

Example

panic("unreachable state reached")

pi

pi() -> f64

The constant π (≈ 3.14159).

Example

pi()   // 3.14159…

pow

pow(a: number, b: number) -> f64

Raise a to the power b.

Example

pow(2, 10)   // 1024.0

radians

radians(x: number) -> f64

Convert an angle from degrees to radians.

Example

radians(180)   // 3.14159…

range

range(start: i64, end: i64) -> [i64]

The half-open integer range [start, end) as a list.

Example

range(1, 4)   // [1, 2, 3]

replace

replace(s: utf8, old: utf8, new: utf8) -> utf8

Replace every occurrence of a substring with another.

Example

replace("hello world", "world", "there")   // "hello there"

reverse

reverse(xs: [T]) -> [T]

Reverse the order of a list's elements.

Example

reverse([1, 2, 3])   // [3, 2, 1]

round

round(x: number) -> f64

Round to the nearest integer (ties away from zero).

Example

round(2.5)   // 3.0

sign

sign(x: number) -> f64

The sign of x: 1, -1, or 0.

Example

sign(-3)   // -1.0

sin

sin(x: number) -> f64

Sine of an angle in radians.

Example

sin(pi() / 2)   // 1.0

sort

sort(xs: [T]) -> [T]

Sort a list — numerically for all-numeric lists, lexicographically for all-string lists.

Example

sort([3, 1, 2])           // [1, 2, 3]
sort(["b", "a", "c"])     // ["a", "b", "c"]

sort_connected

sort_connected(items: [T], edges: [{source, destination, ...}]) -> [T]

Reorder a list so that items joined by edges cluster together (recursing into children).

Example

// Reorder items so nodes joined by edges sit next to each other.
sort_connected(nodes, edges)

split

split(s: utf8, sep: utf8) -> [utf8]

Split a string on every occurrence of a separator into a list of pieces.

Example

split("a,b,c", ",")   // ["a", "b", "c"]

sqrt

sqrt(x: number) -> f64

Square root.

Example

sqrt(16)   // 4.0

starts_with

starts_with(s: utf8, prefix: utf8) -> bool

Whether a string begins with a prefix.

Example

starts_with("hello", "he")   // true

sum

sum(xs: [number]) -> number

Add together every element of a non-empty homogeneous numeric list or tensor.

Example

sum([1.5, 2.5, 3.0])   // 7.0

tail

tail(xs: [T]) -> [T]

Every element of a list or tensor except the first.

Example

tail([10, 20, 30])   // [20, 30]

take

take(xs: [T], n: i64) -> [T]

The first n elements of a list (fewer if the list is shorter).

Example

take([1, 2, 3, 4], 2)   // [1, 2]

tan

tan(x: number) -> f64

Tangent of an angle in radians.

Example

tan(0)   // 0.0

tau

tau() -> f64

The constant τ = 2π (≈ 6.28319).

Example

tau()   // 6.28318…

tensor

tensor(data: [number], shape: [usize]) -> tensor<T>

Build a tensor from flat row-major data and a shape; the data length must equal the product of the dimensions.

Example

tensor([1, 2, 3, 4, 5, 6], [2, 3])   // a 2×3 tensor

tensor_data

tensor_data(t: tensor<T>) -> [T]

The flat row-major element data of a tensor as a list.

Example

tensor_data(tensor([1, 2, 3, 4], [2, 2]))   // [1, 2, 3, 4]

tensor_reshape

tensor_reshape(t: tensor<T>, shape: [usize]) -> tensor<T>

Reinterpret a tensor's data under a new shape; the element count must be unchanged.

Example

tensor_reshape(tensor([1, 2, 3, 4], [2, 2]), [4])   // shape [4]

tensor_shape

tensor_shape(t: tensor<T>) -> [usize]

The dimension sizes of a tensor as a list.

Example

tensor_shape(tensor([1, 2, 3, 4], [2, 2]))   // [2, 2]

to_lower

to_lower(s: utf8) -> utf8

Lowercase every character of a string.

Example

to_lower("AbC")   // "abc"

to_upper

to_upper(s: utf8) -> utf8

Uppercase every character of a string.

Example

to_upper("abc")   // "ABC"

trim

trim(s: utf8) -> utf8

Remove leading and trailing whitespace from a string.

Example

trim("  hi  ")   // "hi"

trunc

trunc(x: number) -> f64

Discard the fractional part, rounding toward zero.

Example

trunc(2.9)   // 2.0

type_fields

type_fields(target: &T) -> [record]

Reflect a type or interface into a list of field-description records (own fields first, then inherited via extends).

Example

type_fields(Image)   // [{ name: "source", type: "utf8", … }, …]

unique

unique(xs: [T]) -> [T]

Remove duplicate elements from a list, keeping first-seen order.

Example

unique([1, 2, 2, 3, 1])   // [1, 2, 3]

zip

zip(a: [A], b: [B]) -> [(A, B)]

Pair up elements of two lists by index, stopping at the shorter length.

Example

zip([1, 2, 3], ["a", "b", "c"])   // [[1, "a"], [2, "b"], [3, "c"]]