Built-ins and value methods
This page covers language-level APIs that do not require an import. Standard-library APIs live under Packages.
Core functions
typeof(value)
Returns the runtime type name. When the value has a single known type, the comparison folds at compile time and warns as a constant condition.
len(value)
Returns the length of a supported value.
string(value)
Converts a value to text. Prefer .toStr() in application code.
number(value)
Converts a value to a decimal number. Prefer .toNum().
int(value)
Converts a value to an integer. Prefer .toInt().
boolean(value)
Converts a value using OSL truthiness. Prefer .toBool().
array(value)
Converts a supported value to an array.
object(value)
Converts a supported value to an object.
min(...values)
Returns the smallest numeric value, or NaN when any value is NaN.
max(...values)
Returns the largest numeric value, or NaN when any value is NaN.
clamp(value, low, high)
Restricts a number to a range.
round(value), floor(value), ceil(value), abs(value)
Basic numeric operations. round rounds halves up, so round(-2.5) is -2, and returns 0 for NaN or values outside the integer range.
sqrt(value), pow(base, exponent)
Roots and powers.
sin(value), cos(value), tan(value)
Trigonometric functions of an angle in degrees, matching the number methods.
random(low, high)
Returns a random number in the requested range.
range(start, end)
Creates an inclusive range. The to operator is usually clearer.
keys(object), values(object), entries(object)
Reads object contents.
btoa(value), atob(value)
Base64 encode and decode. atob returns the decoded bytes as a string, or "" for invalid input.
symbol(name)
Creates a symbol value.
sleep(seconds)
Blocks for a duration in seconds.
Methods on every value
.as<T>
Explicit conversion to a scalar or collection type
.tryAs<T>
Checked conversion returning result<T, error>
.toStr()
String conversion
.toNum()
Number conversion
.toInt()
Integer conversion
.toBool()
Boolean conversion
.getType()
Runtime type name
.assert(type)
Runtime type assertion
.assertElse(type, fallback)
Assertion with a fallback
.assertElse(fallback)
Assertion with the type inferred from the fallback
.len or .len()
Length where supported
.contains(value)
Membership where supported
Assertion shorthand uses value.<type> for .assert(type) and value.<type>(fallback) for .assertElse(type, fallback). A nullable type such as value.<string?> accepts null. Assertions check the runtime type and never convert, so asserting a string as byte[] fails; use .toBytes(). Keep the fallback's opening parenthesis adjacent to >. A space separates a following block, as in for value in items.<array> (.
Assertions and conversions preserve read-only protection for reference values obtained through const<T>. Built-in read operations remain available on const collections, while mutating methods are rejected. .clone() creates an independent deep copy that can be modified. See const types for binding and alias rules.
Strings
Common string methods include:
String positions are 1-based. Indexing, iteration, trimText, and toMixed use Unicode code points. match(pattern) always returns an array of matches, which is empty when nothing matches. .len counts UTF-8 bytes, so it may be larger than the number of characters.
There is no repeat method. Use multiplication, as in "a" * 3.
.toBytes() returns a string's raw bytes as byte[], so data.atob().toBytes() decodes base64 text to bytes.
Arrays
Common array methods include:
iter() returns a lazy iterator over the items; see Iterators and generators.
Array positions are 1-based. Mutating methods change the original array, including arrays stored in object fields or array items, so o.list.append(x) and grid[1].pop() update the stored array. .clone() creates an independent deep copy.
Array pointers created with @arrayVariable support .delete(position) and .len. Pointer deletion updates the original variable's array and length and returns the same pointer. It uses 1-based positions and leaves the array unchanged for out-of-range positions. Generic functions can require an array pointer with <*_[] T>.
sort orders numbers numerically and other values by their string form. sortBy("field") places elements missing the field last. join renders nested arrays and objects as JSON, like .toStr().
left, right, trim, and delete return arrays that do not share storage with the source, so appending to the result never changes the original. trim(start, end) is inclusive and accepts negative positions counted from the end, so "hello".trim(-3, -1) is "llo"; reversed bounds are swapped.
Objects
Common object methods include getKeys, getValues, getEntries, contains, insert, delete, pick, clone, toStr, jsonParse, and getProto.
Cloning a null value returns null.
Objects return null for missing fields. Assignment shares the object; .clone() makes a deep copy and preserves a typed dictionary's key and value types.
A bare key name is literal: {key: 1} has the key "key". Wrap an expression in brackets to compute the key, as in {[key]: 1} or {["user_" ++ id]: data}. Parentheses group an expression as they do everywhere else, so {(key): 1} also computes the key.
Object shorthand resolves variable names even when they match a command name. For example, string error = "failed" followed by {error} creates {error: "failed"}.
Numbers and booleans
Numbers provide methods such as round, floor, ceiling, abs, sqrt, clamp, sin, cos, tan, asin, acos, atan, log, ln, sign, isPrime, and chr.
sqrt, asin, and acos return number?: null when the input is outside their domain. Use a fallback such as x.sqrt() ?? 0.0 where a number is required.
Booleans support the universal conversion, type, assertion, and prototype methods.
Prototypes
Strings, arrays, objects, numbers, and functions can resolve methods through prototypes. Prefer ordinary functions or named types for application structure. Prototype changes are global to the value type and are harder to trace in a large project.
Nullish fallback
?? uses its fallback only when the left value is null. Fallbacks can be chained, including when several consecutive values are null: primary ?? backup ?? 42 returns 42 when both variables are null.
Null guards also narrow nullable typed arrays, typed dictionaries, and named records. After if values == null return, a string[]? value can use string-array methods without an assertion.
Package handles report their qualified typeof name, such as *cache.Cache or *process.Process. Built-in xml, map, set, canvas, option, and result values keep their language type names.
Last updated
Was this helpful?