Builtin Functions

Functions

abs · builtin_names · cbrt · ceil · chars · child_types · clamp · contains · cos · decl_info · decorator_names · doc_comment · ends_with · exp · filter · find · flatten · floor · fn_signature · fold · format · head · hypot · join · keys · len · ln · log10 · log2 · map · map_values · max · merge · min · pow · replace · round · sign · sin · slice · split · sqrt · starts_with · tail · tan · to_lower · to_upper · trim · trunc · type_fields · values

abs(x: f64) → f64

Absolute value.

abs(-7.5)   // magnitude, dropping the sign → 7.5

builtin_names() → [utf8]

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

builtin_names()   // names of every builtin → ["abs", "acos", ..., "zip"]

cbrt(x: f64) → f64

Cube root.

cbrt(27)   // cube root → 3.0

ceil(x: f64) → f64

Round up to the nearest integer.

ceil(3.1)   // round up to a whole number → 4.0

chars(s: utf8) → [utf8]

The characters of a string as a list of one-character strings.

chars("abc")   // explode into single-character strings → ["a", "b", "c"]

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.

child_types(MyDoc)   // element types of the doc’s block slots → [&ProjectMeta, &Settings]

clamp(x: number, lo: number, hi: number) → f64

Constrain x to the range [lo, hi].

clamp(12.0, 0.0, 10.0)   // constrain the value into [0, 10] → 10.0

contains(s: utf8, needle: utf8) → bool

Whether a string contains a substring.

contains("hello", "ell")   // does the string contain the substring? → true

cos(x: f64) → f64

Cosine of an angle in radians.

cos(0.0)   // cosine of 0 radians → 1.0

decl_info(target: &T) → record

Describe a top-level declaration: its name, kind, doc comment, and schema classification (block / table / decorator / document).

decl_info(MyDoc)   // declaration metadata for a type → { kind: "document", is_document: true, name: "MyDoc" }

decorator_names(target: &T) → [utf8]

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

decorator_names(Image)   // the decorators on the Image type → ["block", "schemaless", ...]

doc_comment(target: &T) → utf8

The doc comment — the contiguous run of # / // lines immediately above a declaration — attached to a reference, or \"\" when there is none. Complements decorator_arg(x, \"doc\", …) for @doc(\"…\") metadata.

doc_comment(Image)   // the doc comment above a type → the comment lines above the Image type

ends_with(s: utf8, suffix: utf8) → bool

Whether a string ends with a suffix.

ends_with("hello", "lo")   // does it end with this suffix? → true

exp(x: f64) → f64

e raised to the power x.

exp(0.0)   // e raised to the power 0 → 1.0

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

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

filter([1, 2, 3, 4], fn(x: i64) -> bool { x % 2 == 0 })   // keep the even numbers → [2, 4]

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

The first element for which the predicate returns true, or none.

find([1, 2, 3], fn(x: i64) -> bool { x > 1 })   // first element greater than 1 → 2

flatten(xss: [[T]]) → [T]

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

flatten([[1, 2], [3]])   // concatenate the inner lists, one level deep → [1, 2, 3]

floor(x: f64) → f64

Round down to the nearest integer.

floor(3.9)   // round down to a whole number → 3.0

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.

fn_signature("map")   // describe the map builtin → { signature: "fn(xs: [T], ...) -> [U]", ... }

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.

fold([1, 2, 3], 0, fn(acc: i64, x: i64) -> i64 { acc + x })   // sum the list, starting from 0 → 6

format(template: utf8) → utf8

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

format("{} = {}", "x", 42)   // substitute the args into the {} slots → "x = 42"

head(xs: [T]) → T

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

Remarks: Returns none when the collection is empty.

head([1, 2, 3])   // take the first element → 1

hypot(a: f64, b: f64) → f64

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

hypot(3, 4)   // hypotenuse of a 3-4 right triangle → 5.0

join(parts: [utf8], sep: utf8) → utf8

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

join(["a", "b", "c"], "-")   // join with a dash between pieces → "a-b-c"

keys(r: record) → [utf8]

The field names of a record, in deterministic (sorted) order.

keys({ name: "Rex", age: 4 })   // field names, sorted → ["age", "name"]

len(xs: [T]) → usize

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

len([10, 20, 30])   // count the elements → 3

ln(x: f64) → f64

Natural (base-e) logarithm.

ln(1.0)   // natural (base-e) logarithm of 1 → 0.0

log10(x: f64) → f64

Base-10 logarithm.

log10(1000.0)   // base-10 logarithm of 1000 → 3.0

log2(x: f64) → f64

Base-2 logarithm.

log2(8.0)   // base-2 logarithm of 8 → 3.0

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

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

map([1, 2, 3], fn(x: i64) -> i64 { x * 2 })   // double each element → [2, 4, 6]

map_values(r: record, f: fn (T) -> U) → record

Apply a function to every field value of a record, keeping the keys.

map_values({ low: 1, high: 9 }, fn(x: i64) -> i64 { x * 2 })   // double every value, keep the keys → { high: 18, low: 2 }

max(a: f64, b: f64) → f64

The larger of two numbers.

max(3, 7.5)   // the larger of the two → 7.5

merge(a: record, b: record) → record

Combine two records into one; fields of b win on a name clash.

merge({ host: "localhost", port: 80 }, { port: 8080 })   // the second record wins on the port clash → { host: "localhost", port: 8080 }

min(a: f64, b: f64) → f64

The smaller of two numbers.

min(3, 7.5)   // the smaller of the two → 3.0

pow(a: f64, b: f64) → f64

Raise a to the power b.

pow(2, 10)   // 2 raised to the 10th power → 1024.0

replace(s: utf8, old: utf8, new: utf8) → utf8

Replace every occurrence of a substring with another.

replace("hello world", "world", "there")   // replace the matched substring → "hello there"

round(x: f64) → f64

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

round(2.5)   // nearest integer (ties away from zero) → 3.0

sign(x: f64) → f64

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

sign(-3.0)   // negative input -> -1.0 → -1.0

sin(x: f64) → f64

Sine of an angle in radians.

sin(0.0)   // sine of 0 radians → 0.0

slice(xs: utf8 | [T], start: i64, end: i64) → utf8 | [T]

The half-open range [start, end) of a string's characters or a list's elements (bounds are clamped).

slice("hello", 0, 2)   // characters from index 0 up to (not incl.) 2 → "he"

split(s: utf8, sep: utf8) → [utf8]

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

split("a,b,c", ",")   // split on each comma → ["a", "b", "c"]

sqrt(x: f64) → f64

Square root.

sqrt(144)   // square root → 12.0

starts_with(s: utf8, prefix: utf8) → bool

Whether a string begins with a prefix.

starts_with("hello", "he")   // does it begin with this prefix? → true

tail(xs: [T]) → [T]

Every element of a list or tensor except the first.

tail([1, 2, 3])   // everything after the first → [2, 3]

tan(x: f64) → f64

Tangent of an angle in radians.

tan(0.0)   // tangent of 0 radians → 0.0

to_lower(s: utf8) → utf8

Lowercase every character of a string.

to_lower("AbC")   // lowercase every character → "abc"

to_upper(s: utf8) → utf8

Uppercase every character of a string.

to_upper("abc")   // uppercase every character → "ABC"

trim(s: utf8) → utf8

Remove leading and trailing whitespace from a string.

trim("  hi  ")   // strip leading/trailing whitespace → "hi"

trunc(x: f64) → f64

Discard the fractional part, rounding toward zero.

trunc(3.9)   // drop the fractional part → 3.0

type_fields(target: &T) → [record]

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

type_fields(Image)   // reflect the Image type into field records → [{ name: "source", type: "utf8", ... }, ...]

values(r: record) → [T]

The field values of a record, in the same order as keys.

values({ name: "Rex", age: 4 })   // field values, in key order → [4, "Rex"]