Standard Library

Zolo includes a comprehensive standard library built on top of the Lua runtime. All functions are available automatically without imports.

String Functions¶

All string functions are in the string namespace:

Function	Description	Example
`string.trim(s)`	Remove leading/trailing whitespace	`string.trim(" hi ")` → `"hi"`
`string.trim_start(s)`	Remove leading whitespace	`string.trim_start(" hi")` → `"hi"`
`string.trim_end(s)`	Remove trailing whitespace	`string.trim_end("hi ")` → `"hi"`
`string.starts_with(s, prefix)`	Check if starts with prefix	`string.starts_with("hello", "he")` → `true`
`string.ends_with(s, suffix)`	Check if ends with suffix	`string.ends_with("hello", "lo")` → `true`
`string.contains(s, substr)`	Check if contains substring	`string.contains("hello", "ell")` → `true`
`string.split(s, sep)`	Split into array	`string.split("a,b,c", ",")` → `["a","b","c"]`
`string.replace(s, old, new)`	Replace occurrences	`string.replace("aa", "a", "b")` → `"bb"`
`string.chars(s)`	Split into characters	`string.chars("hi")` → `["h","i"]`
`string.pad_start(s, len, fill)`	Pad at start	`string.pad_start("42", 5, "0")` → `"00042"`
`string.pad_end(s, len, fill)`	Pad at end	`string.pad_end("hi", 5, ".")` → `"hi..."`
`string.is_empty(s)`	Check if empty	`string.is_empty("")` → `true`

Array Functions¶

All array functions are in the Array namespace:

Creation and Basic Operations¶

Function	Description
`Array.new(...)`	Create array from arguments
`Array.len(arr)`	Get array length
`Array.push(arr, val)`	Add element to end
`Array.pop(arr)`	Remove and return last element
`Array.shift(arr)`	Remove and return first element
`Array.unshift(arr, val)`	Add element to start
`Array.slice(arr, from, to)`	Extract sub-array
`Array.concat(a, b)`	Concatenate two arrays
`Array.reverse(arr)`	Reverse array
`Array.sort(arr, cmp?)`	Sort array (optional comparator)
`Array.flat(arr)`	Flatten nested arrays
`Array.join(arr, sep)`	Join elements into string

Functional Operations¶

Function	Description	Example
`Array.map(arr, fn)`	Transform each element	`Array.map([1,2,3], \|x\| x * 2)` → `[2,4,6]`
`Array.filter(arr, fn)`	Keep matching elements	`Array.filter([1,2,3,4], \|x\| x > 2)` → `[3,4]`
`Array.reduce(arr, fn, init)`	Reduce to single value	`Array.reduce([1,2,3], \|a,b\| a + b, 0)` → `6`
`Array.each(arr, fn)`	Execute for each element	`Array.each(items, \|x\| print(x))`
`Array.find(arr, fn)`	Find first matching	`Array.find([1,2,3], \|x\| x > 1)` → `2`
`Array.find_index(arr, fn)`	Find index of first matching	`Array.find_index([1,2,3], \|x\| x > 1)` → `1`
`Array.contains(arr, val)`	Check if element exists	`Array.contains([1,2,3], 2)` → `true`
`Array.any(arr, fn)`	Check if any match	`Array.any([1,2,3], \|x\| x > 2)` → `true`
`Array.all(arr, fn)`	Check if all match	`Array.all([1,2,3], \|x\| x > 0)` → `true`
`Array.zip(a, b)`	Pair elements from two arrays	`Array.zip([1,2], ["a","b"])` → `[(1,"a"),(2,"b")]`
`Array.enumerate(arr)`	Add indices	`Array.enumerate(["a","b"])` → `[(0,"a"),(1,"b")]`

Using with Pipe¶

use std::Array

let result = [1, 2, 3, 4, 5]
    |> Array.map(|x| x * x)
    |> Array.filter(|x| x > 5)
    |> Array.reduce(|a, b| a + b, 0)
// result = 9 + 16 + 25 = 50

Map Functions¶

All map functions are in the Map namespace:

Function	Description
`Map.new()`	Create empty map
`Map.from(tbl)`	Create from table
`Map.set(m, key, val)`	Set key-value pair
`Map.get(m, key)`	Get value by key
`Map.has(m, key)`	Check if key exists
`Map.remove(m, key)`	Remove key-value pair
`Map.keys(m)`	Get all keys as array
`Map.values(m)`	Get all values as array
`Map.entries(m)`	Get all key-value pairs
`Map.len(m)`	Get number of entries
`Map.each(m, fn)`	Iterate over entries
`Map.clear(m)`	Remove all entries

Example¶

use std::Map

let scores = Map.new()
Map.set(scores, "Alice", 95)
Map.set(scores, "Bob", 87)

print(Map.get(scores, "Alice"))  // 95
print(Map.has(scores, "Carol"))  // false

Map.each(scores, |key, val| {
    print("{key}: {val}")
})

Set Functions¶

All set functions are in the Set namespace:

Function	Description
`Set.new()`	Create empty set
`Set.from(arr)`	Create from array
`Set.add(s, val)`	Add element
`Set.has(s, val)`	Check membership
`Set.remove(s, val)`	Remove element
`Set.len(s)`	Get size
`Set.to_array(s)`	Convert to array
`Set.union(a, b)`	Union of two sets
`Set.intersect(a, b)`	Intersection of two sets
`Set.difference(a, b)`	Elements in a but not b
`Set.each(s, fn)`	Iterate over elements

Example¶

use std::Set

let fruits = Set.from(["apple", "banana", "cherry"])
Set.add(fruits, "date")
print(Set.has(fruits, "apple"))   // true
print(Set.len(fruits))            // 4

let tropical = Set.from(["banana", "mango", "papaya"])
let common = Set.intersect(fruits, tropical)  // {"banana"}

Option Functions¶

The Option type represents a value that may or may not exist:

Function	Description
`Option.Some(val)`	Create Some with a value
`Option.None()`	Create None (no value)
`Option.is_some(opt)`	Check if has a value
`Option.is_none(opt)`	Check if empty
`Option.unwrap(opt)`	Extract value (errors if None)
`Option.unwrap_or(opt, default)`	Extract value or use default
`Option.map(opt, fn)`	Transform the value if present
`Option.and_then(opt, fn)`	Flat map (chain optionals)
`Option.or_else(opt, fn)`	Provide alternative if None
`Option.from(val)`	Create from value (nil → None)

Example¶

use std::Option

let maybe = Option.Some(42)
let nothing = Option.None()

print(Option.is_some(maybe))         // true
print(Option.unwrap_or(nothing, 0))  // 0

let doubled = Option.map(maybe, |x| x * 2)
print(Option.unwrap(doubled))        // 84

Result Functions¶

The Result type represents success or failure:

Function	Description
`Result.Ok(val)`	Create success
`Result.Err(err)`	Create error
`Result.is_ok(r)`	Check if success
`Result.is_err(r)`	Check if error
`Result.unwrap(r)`	Extract value (errors if Err)
`Result.unwrap_or(r, default)`	Extract value or use default
`Result.unwrap_err(r)`	Extract error value
`Result.map(r, fn)`	Transform success value
`Result.map_err(r, fn)`	Transform error value
`Result.and_then(r, fn)`	Chain results
`Result.or_else(r, fn)`	Handle error case
`Result.from_pcall(fn, ...)`	Create from protected call

Example¶

use std::Result

fn divide(a: int, b: int) -> Result<int, str> {
    if b == 0 {
        Result.Err("division by zero")
    } else {
        Result.Ok(a / b)
    }
}

let result = divide(10, 2)
print(Result.unwrap(result))  // 5

let bad = divide(10, 0)
print(Result.is_err(bad))     // true
print(Result.unwrap_or(bad, -1))  // -1

Iterator Functions¶

Lazy iterators for efficient data processing:

Function	Description
`Iter.from(arr)`	Create from array
`Iter.range(start, stop, step?)`	Create range iterator
`Iter.map(iter, fn)`	Lazy map
`Iter.filter(iter, fn)`	Lazy filter
`Iter.take(iter, n)`	Take first n elements
`Iter.skip(iter, n)`	Skip first n elements
`Iter.zip(a, b)`	Zip two iterators
`Iter.enumerate(iter)`	Add indices
`Iter.fold(iter, init, fn)`	Reduce to single value
`Iter.collect(iter)`	Collect to array
`Iter.each(iter, fn)`	Execute for each
`Iter.count(iter)`	Count elements
`Iter.flat_map(iter, fn)`	Lazy flat map
`Iter.chain(a, b)`	Concatenate iterators
`Iter.find(iter, fn)`	Find first matching
`Iter.any(iter, fn)`	Check if any match
`Iter.all(iter, fn)`	Check if all match

Example¶

use std::Iter

let result = Iter.range(0, 100)
    |> Iter.map(|x| x * x)
    |> Iter.filter(|x| x % 2 == 0)
    |> Iter.take(5)
    |> Iter.collect()
// [0, 4, 16, 36, 64]

Built-in Functions¶

These functions are available globally:

Function	Description
`print(...)`	Print to stdout
`type(val)`	Get type as string
`tostring(val)`	Convert to string
`tonumber(val)`	Convert to number
`assert_eq(a, b, msg?)`	Assert equality
`assert_ne(a, b, msg?)`	Assert inequality

BigInt Support¶

Zolo has native BigInt support for arbitrarily large integers:

let big = BigInt.from("99999999999999999999999")
let zero = BigInt.zero()
let one = BigInt.one()

Math Functions¶

For the full float-precision guide — ~= operator, within clauses, decimal/bigdecimal types, NaN/infinity handling, and the float-equality lint — see Float Precision & Decimal Types.

All math functions are in the math namespace and available without imports.

Approximate equality¶

Function	Description
`math.approx_eq(a, b)`	Approximate equal with adaptive default tolerance
`math.approx_eq_abs(a, b, tol)`	`\|a - b\| <= tol`
`math.approx_eq_rel(a, b, rtol)`	`\|a - b\| / max(\|a\|, \|b\|) <= rtol`
`math.approx_eq_ulps(a, b, n)`	Bit-pattern (ULP) distance ≤ n

These are the function-call equivalents of the ~= operator and its within clauses. Use the functions when you need a first-class callable (e.g., passing to Array.filter).

use std::Array
use std::math

// Operator and function are equivalent
print(0.1 + 0.2 ~= 0.3)                    // true
print(math.approx_eq(0.1 + 0.2, 0.3))      // true

// First-class usage
let near = Array.filter(samples, |m| math.approx_eq_abs(m, 0.3, 0.01))

Float predicates¶

Function	Description
`math.is_nan(x)`	True if `x` is NaN
`math.is_finite(x)`	True if `x` is neither NaN nor infinite
`math.is_infinite(x)`	True if `x` is ±∞
`math.is_inf(x)`	Alias for `math.is_infinite`

Arithmetic¶

Function	Description
`math.abs(x)`	Absolute value
`math.abs_diff(x, y)`	`\|x - y\|`
`math.floor(x)`	Largest integer ≤ x
`math.ceil(x)`	Smallest integer ≥ x
`math.round(x)`	Round to nearest integer
`math.trunc(x)`	Truncate toward zero
`math.sqrt(x)`	Square root
`math.pow(x, y)`	`x` to the power `y`
`math.min(x, y)`	Smaller of two values
`math.max(x, y)`	Larger of two values
`math.clamp(x, lo, hi)`	Clamp `x` to `[lo, hi]`
`math.sign(x)`	−1, 0, or 1
`math.fract(x)`	Fractional part (`x - trunc(x)`)
`math.log(x)`	Natural logarithm
`math.log2(x)`	Base-2 logarithm
`math.log10(x)`	Base-10 logarithm
`math.exp(x)`	`e^x`

Trigonometry¶

Function	Description
`math.sin(x)`	Sine (radians)
`math.cos(x)`	Cosine (radians)
`math.tan(x)`	Tangent (radians)
`math.asin(x)`	Arc sine
`math.acos(x)`	Arc cosine
`math.atan(x)`	Arc tangent
`math.atan2(y, x)`	Arc tangent of `y/x`

Constants¶

Constant	Value	Description
`math.pi`	3.14159...	π
`math.tau`	6.28318...	2π
`math.e`	2.71828...	Euler's number
`math.phi`	1.61803...	Golden ratio
`math.epsilon`	~2.22e-16	f64 machine epsilon (= `float.EPSILON`)
`math.infinity`	+∞	Positive infinity (= `float.INFINITY`)
`math.huge`	+∞	Lua-compatible alias for `math.infinity`
`math.nan`	NaN	IEEE 754 NaN sentinel (= `float.NAN`)