burn / docs

Standard library

Built-in functions

The basics of the language are always available: printing, conversions and the operations on strings, arrays and maps. Everything else lives in a standard library module and needs its import.

Built-ins can be called as functions or, when the first argument is the receiver, as methods: len(names) and names.length, upper(s) and s.upper().

Output and input

Function Description
print(values...) prints the values separated by spaces and a newline
eprint(values...) the same, to standard error
write(value) prints without a newline
input(prompt = "") reads a line from standard input
readStdin() reads everything left on standard input

Conversion

Function Description
toString(x), str(x) any value as a string
toInt(x), parseInt(s) string, float or bool to int (runtime error for invalid strings)
toFloat(x), parseFloat(s) string or int to float
isInt(s), isNumber(s) check a string before converting
toInt(s, radix), isInt(s, radix) read an integer written in base 2 to 36, e.g. toInt("ff", 16) is 255
toString(n, radix) write an integer in base 2 to 36, e.g. toString(255, 2) is "11111111"
typeOf(x) the runtime type name, e.g. "int", "[string]", "Person"
x as uint8, x as float32, ... convert between number types, checked at runtime

Strings

len, upper, lower, trim, split(s, sep), join(array, sep), substring(s, start, end?), charAt(s, i), contains(s, part), indexOf(s, part), replace(s, from, to), startsWith, endsWith, repeat(s, n), chars(s), reverse(s), charCode(s), fromCharCode(n). Indexing (s[0]) returns a one character string. Lengths and indexes count Unicode characters. bytes(s) returns the UTF-8 bytes as a [uint8], and fromBytes(bytes) decodes them back into a string.

Arrays

len, push(a, v), append(a, v) (returns the array), pop(a), insert(a, i, v), remove(a, i), contains(a, v), indexOf(a, v), join(a, sep), reverse(a), sort(a), slice(a, start, end?), copy(a), clear(a), and a + b to concatenate.

Maps

len, keys(m), values(m), has(m, k), get(m, k, default), remove(m, k), m[k], m[k] = v.

Numbers

x.wrappingAdd(y), x.wrappingSub(y) and x.wrappingMul(y) wrap around at the edges of the integer type instead of failing on overflow.

Other names and helpers

  • println is the same as print.
  • length(x) and size(x) are the same as len(x); x.length reads it as a property.
  • toUpper, toUpperCase and toLower, toLowerCase are the same as upper and lower.
  • gc() runs the cycle collector at once. Programs never need it, since cycles are collected automatically; it is there for measurements.
  • annotationsOf(value) returns the annotations declared on the value's type (annotations).

In the standard library

These functions are part of the standard library. Import their module to use them; the compiler says which import is missing, and burn fix or the editor's quick fix adds it. They are still fast built-ins underneath.

Module Functions
std/math sqrt, pow, abs, floor, ceil, round, min, max, sin, cos, tan, asin, acos, atan, atan2, log, log10, exp
std/random random, randomInt, seed
std/time now, nowMs, millis, clock, sleep
std/json parseJSON, toJSON
std/fs readFile, writeFile, appendFile, fileExists
std/process env, args, exit, panic
std/testing assert
std/strings isLetter, isDigit, isAlphanumeric, isWhitespace 
import "std/math"
import "std/testing"

assert(sqrt(16.0) == 4.0)

burn eval and burn repl have all of them without imports.

Math

sqrt, pow, abs, floor, ceil, round, min, max, sin, cos, tan, asin, acos, atan, atan2, log, log10, exp from std/math, and random() (float in [0, 1)), randomInt(min, max) and seed(n) from std/random. floor, ceil and round return int; pow, min, max and abs keep the integer type when all arguments are integers, and min, max and abs keep float32.

Time

now() (seconds as float), nowMs() / millis() (milliseconds as int), clock() (monotonic nanoseconds), sleep(ms), from std/time.

JSON

parseJSON(text) returns any: objects become {string: any}, arrays [any]. Read values with indexing (data["name"], data.tags[0]) and narrow them with is. toJSON(value) serializes any value. Both are in std/json.

Files, environment and process

readFile(path), writeFile(path, text), appendFile(path, text) and fileExists(path) from std/fs; env(name), args(), exit(code = 0) and panic(message) from std/process; assert(condition, message?) from std/testing.

Character classes

isLetter, isDigit, isAlphanumeric and isWhitespace from std/strings check that every character of a non-empty string belongs to the class (Unicode letters and numbers; isDigit accepts 0 to 9).