Built-in Functions

Built-ins are constants and functions provided by the language.

A programmer is not obliged to consult the list of built-ins before naming a new variable or input. New built-ins may be added to ƿit without breaking existing programs.

Constants

• true — the value of 1 == 1
• false — the value of 1 == 0
• null — the value of 1 / 0. An empty immutable object. Refinement on null produces null. Modifying or calling null disrupts.
• pi — 3.1415926535897932

Creator Functions

The creator functions are polymorphic: the first argument’s type selects the behavior. All return null if their inputs are not suitable.

• text — convert to text, join arrays, slice text
• number — convert logical values and parse text
• array — create, copy, map, concat, slice, split
• record — copy, merge, select, create from keys

text

Text functions are intrinsic: they are always available without use(). There is a top-level text creator function, and related operations such as format, normalize, lower, and search are also top-level functions, called directly by name.

To split text into characters, use array(text).

From an Array

text(array, separator)

Join array elements into text with a separator. The default separator is empty text.

text(["h", "e", "l", "l", "o"])  // "hello"
text([1, 2, 3], ", ")            // "1, 2, 3"
text(["a", "b"], "-")            // "a-b"

From a Number

text(number, radix)

Convert a number to text. Radix is 2-36. The default radix is 10.

text(255)        // "255"
text(255, 16)    // "ff"
text(255, 2)     // "11111111"

From Text

text(text, from, to)

Extract a substring from index from to to. Negative indices count from the end.

text("hello world", 0, 5)  // "hello"
text("hello world", 6)     // "world"
text("hello", -3)          // "llo"

Text Functions

lower(text)

Convert to lowercase.

upper(text)

Convert to uppercase.

trim(text, reject)

Remove characters from both ends. The default removes whitespace.

trim("  hello  ")       // "hello"
trim("xxhelloxx", "x")  // "hello"

search(text, target, from)

Find the position of target in text. Returns null if not found.

search("hello world", "world")         // 6
search("hello world", "xyz")           // null
search("hello hello", "hello", 1)      // 6

replace(text, target, replacement, cap)

Replace occurrences of target with replacement. If cap is not specified, replace all occurrences.

replace("hello", "l", "L")     // "heLLo"
replace("hello", "l", "L", 1)  // "heLlo"

replace("hello", "l", function(match, pos) {
  return pos == 2 ? "L" : match
})  // "heLLo"

format(text, collection, transformer)

Substitute {key} placeholders with values from a collection.

format("Hello, {name}!", {name: "World"})
// "Hello, World!"

format("{0} + {1} = {2}", [1, 2, 3])
// "1 + 2 = 3"

normalize(text)

Unicode normalize text to NFC form.

normalize("cafe\u0301")

codepoint(text)

Get the Unicode codepoint of the first character.

codepoint("A")  // 65

extract(text, pattern, from, to)

Match a pattern and extract groups.

extract("2024-01-15", /(\d+)-(\d+)-(\d+)/)

starts_with(text, prefix)

Returns true if the text starts with the given prefix.

ends_with(text, suffix)

Returns true if the text ends with the given suffix.

character(value)

If value is text, return the first character. If it is a non-negative 32-bit integer, return the character from that codepoint.

character("hello")  // "h"
character(65)       // "A"

number

Number functions are intrinsic: they are always available without use(). There is a top-level number creator function, and related operations such as abs, floor, round, and modulo are also top-level functions.

Conversion

number(logical)

Convert boolean to number.

number(true)   // 1
number(false)  // 0

number(text, radix)

Parse text to number. Radix is 2-36. The default radix is 10.

number("42")       // 42
number("ff", 16)   // 255
number("1010", 2)  // 10

number(text, format)

Parse formatted numbers.

number("1,000", "d")  // 1000
number("0xff", "j")   // 255

Number Functions

abs(n)

Absolute value.

sign(n)

Returns -1, 0, or 1.

floor(n, place)

Round down.

floor(4.9)        // 4
floor(4.567, -2)  // 4.56

place is a power-of-ten exponent, not a count of decimal places: the result is a multiple of 10^place. So -2 is hundredths and 1 is tens. The sign is the part that catches people — round(x, 2) is not “two decimals”, it rounds to the nearest hundred.

ceiling(n, place)

Round up.

ceiling(4.1)        // 5
ceiling(4.123, -2)  // 4.13

round(n, place)

Round to nearest.

round(4.5)          // 5
round(4.567, -2)    // 4.57
round(12.3775, 1)   // 10

trunc(n, place)

Truncate toward zero.

trunc(4.9)         // 4
trunc(-4.9)        // -4
trunc(4.987, -2)   // 4.98

whole(n)

Get the integer part.

whole(4.9)   // 4
whole(-4.9)  // -4

fraction(n)

Get the fractional part.

fraction(4.75)  // 0.75

min(a, b)

Return the smaller of two numbers.

max(a, b)

Return the larger of two numbers.

neg(n)

Reverse the sign of a number.

neg(5)   // -5
neg(-3)  // 3

modulo(dividend, divisor)

Result is dividend - (divisor * floor(dividend / divisor)). Result has the sign of the divisor.

modulo(7, 3)   // 1
modulo(-7, 3)  // 2

remainder(dividend, divisor)

Compute remainder. Result has the sign of the dividend.

remainder(17, 5)   // 2
remainder(-17, 5)  // -2

array

Array functions are intrinsic: they are always available without use(). There is a top-level array creator function, and related operations such as arrfor, find, filter, reduce, sort, and reverse are also top-level functions.

From a Number

array(number)

Create an array of a given size with all elements initialized to null.

array(3)  // [null, null, null]

array(number, initial)

Create an array of a given size with all elements initialized to a value. If initial is a function, it is called for each element. If the function accepts an input, the index is passed.

array(3, 0)                         // [0, 0, 0]
array(3, function(i) { return i * 2 })  // [0, 2, 4]

From an Array

array(array)

Copy an array. The new array is mutable.

var copy = array(original)

array(array, function)

Map an array by calling a function with each element and collecting the results.

array([1, 2, 3], function(x) { return x * 2 })  // [2, 4, 6]

array(array, from, to)

Extract a sub-array. Negative indices count from the end.

array([1, 2, 3, 4, 5], 1, 4)  // [2, 3, 4]
array([1, 2, 3], -2)          // [2, 3]

array(array, another)

Concatenate two arrays.

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

From a Record

array(record)

Get the text keys of a record as an array. Record keys used as private fields are not included.

array({a: 1, b: 2})  // ["a", "b"]

From Text

array(text)

Split text into individual characters.

array("hello")  // ["h", "e", "l", "l", "o"]
array("ƿit")    // ["ƿ", "i", "t"]

array(text, separator)

Split text by a separator string.

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

array(text, length)

Dice text into chunks of a given length.

array("abcdef", 2)  // ["ab", "cd", "ef"]

Array Functions

arrfor(arr, fn, reverse, exit)

Iterate over elements.

arrfor([1, 2, 3], function(el, i) {
  log.console(i, el)
})

arrfor([1, 2, 3, 4], function(el) {
  if (el > 2) return true
  log.console(el)
}, false, true)  // logs 1, 2

find(arr, fn, reverse, from)

Find element index.

find([1, 2, 3], 2)                                  // 1
find([1, 2, 3], function(x) { return x > 1 })       // 1
find([1, 2, 3], function(x) { return x > 1 }, true) // 2

filter(arr, fn)

Filter elements.

filter([1, 2, 3, 4], function(x) { return x % 2 == 0 })  // [2, 4]

reduce(arr, fn, initial, reverse)

Reduce to a single value.

reduce([1, 2, 3, 4], function(a, b) { return a + b })      // 10
reduce([1, 2, 3, 4], function(a, b) { return a + b }, 10)  // 20

reverse(arr)

Returns a new array with elements in the opposite order.

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

sort(arr, select)

Sort an array and return a new array.

sort([3, 1, 4, 1, 5])  // [1, 1, 3, 4, 5]
sort([{n: 3}, {n: 1}], "n")  // [{n: 1}, {n: 3}]
sort([[3, "c"], [1, "a"]], 0)  // [[1, "a"], [3, "c"]]

record

The record function is intrinsic: it is always available without use(). It is polymorphic: its behavior depends on the types of its arguments.

From a Record

record(obj)

Shallow copy a record.

record(obj, another)

Combine two records.

record({a: 1}, {b: 2})  // {a: 1, b: 2}
record({a: 1}, {a: 2})  // {a: 2}

record(obj, keys)

Select specific keys.

record({a: 1, b: 2, c: 3}, ["a", "c"])  // {a: 1, c: 3}

From an Array of Keys

record(keys)

Create a record from keys. Values are true.

record(["a", "b", "c"])  // {a: true, b: true, c: true}

record(keys, value)

Create a record from keys with a specified value.

record(["a", "b"], 0)  // {a: 0, b: 0}

record(keys, fn)

Create a record from keys with computed values.

record(["a", "b", "c"], function(k, i) { return i })  // {a: 0, b: 1, c: 2}

Key Iteration

var obj = {a: 1, b: 2, c: 3}
var keys = array(obj)  // ["a", "b", "c"]

Universal Functions

apply(function, array) — execute the function, passing array elements as input values.

length(value) — returns the number of elements (array), bits (blob), codepoints (text), named inputs (function), or record length. Returns null for other types.

logical(value) — converts to logical. 0, false, "false", and null produce false. 1, true, and "true" produce true. All other values return null.

not(logical) — returns the opposite logical. Returns null for non-logicals.

stone(value) — freeze the value, making it permanently immutable. Nested objects and arrays keep their own stone state.

Sensory Functions

Sensory functions return a logical value.

Core sensory functions:

is_array, is_blob, is_function, is_integer, is_logical, is_null, is_number, is_record, is_text.

Additional sensory functions:

is_actor, is_character, is_data, is_digit, is_false, is_fit, is_letter, is_lower, is_stone, is_true, is_upper, is_whitespace.