TeaScript Core Library Documentation

Bool : TypeInfo

The boolean type. Values are true and false.

i64 : TypeInfo

Signed 64-bit integer. TeaScript's only signed integral type.

u64 : TypeInfo

Unsigned 64-bit integer.

u8 : TypeInfo

Unsigned 8-bit integer. Most commonly seen with buffers (one byte at a time).

f64 : TypeInfo

64-bit floating-point number.

String : TypeInfo

UTF-8 string type.

Tuple : TypeInfo

Heterogeneous, ordered, optionally-named collection. Used as TeaScript's general-purpose container (records, arrays, stacks, …).

Buffer : TypeInfo

Contiguous byte buffer — see Buffer support for the full API.

Error : TypeInfo

The error type returned by fallible Core Library functions (since API version 1).

Function : TypeInfo

The function type. Matches any TeaScript function value in is checks.

IntegerSequence : TypeInfo

The type of values produced by _seq. Usable in forall loops.

TypeInfo : TypeInfo

The type of every predefined type binding on this page, including itself.

Number : TypeInfo

Fake concept matching any numeric type (i64, u64, u8, f64). Useful in is checks when you want "any number" rather than a specific representation.

Const : TypeInfo

Fake concept matching const-qualified values. Useful in is checks to distinguish a constant from a mutable variable.

NaV : TypeInfo

"Not a Value" — the type of the void value. Used as a function return type when nothing meaningful is returned.

_version_major : i64

Major version of TeaScript.

_version_minor : i64

Minor version of TeaScript.

_version_patch : i64

Patch version of TeaScript.

_version_combined_number : i64

Combined version number for easy version comparisons.

_version_build_date_time : String

Build date and time as a string.

_api_version : i64

Version of the Core Library API.

features : Tuple

A named tuple describing which optional features were compiled into the Library / Host application. Elements: format, color, toml (all Bool), json (i64), and json_adapter (String, the name of the active JSON adapter).

_init_core_stamp : f64

Time stamp in fractional seconds from an unspecified time point during program start.

_core_config : i64

Combined enum teascript::config::eConfig value used to bootstrap the Core Library.

_exit_success : i64

Exit code indicating success (used especially with _exit).

_exit_failure : i64

Exit code indicating failure (used especially with _exit).

void : NaV

"Not a Value." Convenience so you can write return void when a function shall return nothing.

PI : f64

The constant number π.

_out(s: String) -> void

Prints s to stdout.

_err(s: String) -> void

Prints s to stderr.

print(val: Any) -> void

Prints val to stdout, doing to-string conversion of the parameter.

println(val: Any) -> void

Prints val followed by a line feed to stdout, doing to-string conversion of the parameter.

_print_version() -> void

Prints the TeaScript version string (<name> X.Y.Z) followed by a line feed to stdout.

readline() -> String

Reads a line from stdin (blocking until the line is finished) and returns it without the trailing line feed.

_exit(code: Any) -> void

Exits the script (with stack unwinding / scope cleanup) using code as the return value. This function never returns.

_strtonum(s: String) -> i64 | Error

Converts a string to i64. Returns an Error on failure. Works only with real String parameters. An alternative is +str.

_strtonumex(s: String) -> i64 | u8 | u64 | f64 | Error

Converts a string to i64, u8, u64 or f64. Returns an Error on failure. Works only with real String objects.

_numtostr(n: i64) -> String

Converts an i64 to a String. Works only with real i64 parameters. An alternative is num % "".

to_string(val: Any) -> String

Converts val to a string. If val is an integer, _numtostr is an alternative.

to_number(val: Any) -> i64 | u8 | u64 | f64 | Error

Converts val to a number. Returns an Error on failure. If val is a String, _strtonum / _strtonumex is an alternative.

to_f64(val: Any) -> f64 | Bool

Provisional Ensures val is used as f64. val must already be a number; returns an Error on failure. Will be replaced by a cast later. Typical use: to_f64(to_number(some_var)).

to_i64(val: Any) -> i64 | Bool

Provisional Ensures val is used as i64. val must already be a number; returns an Error on failure. Will be replaced by a cast later. Typical use: to_i64(to_number(some_var)).

_eval(code: String) -> Any

Parses and evaluates the string as TeaScript code and returns its result.

eval_file(path: String) -> Any

Parses and evaluates the content of the file and returns its result. All functions and variables defined in the top-level scope stay available.

print_error(e: Any) -> void

Prints e followed by a line feed to stderr, doing to-string conversion (usually e should be a String or Error).

fail() -> void

Exits the script (with stack unwinding / scope cleanup) with error code _exit_failure. Never returns.

fail_with_error(error_code: i64) -> void

Exits the script (with stack unwinding / scope cleanup) using the given error code. Never returns.

fail_with_message(err: Any, error_code: i64) -> void

Prints err to stderr (usually err should be a String or Error), then exits the script (with stack unwinding / scope cleanup) using the given error code. Never returns.

clock() -> f64

Returns the local wall-clock time of the current day in (fractional) seconds.

clock_utc() -> f64

Returns the UTC time of the current day in (fractional) seconds.

_timestamp() -> f64

Returns the elapsed time in (fractional) seconds from an unspecified time point during program start. Monotonically increasing.

sleep(seconds: i64) -> void

Sleeps for at least the given amount of seconds.

random(start: i64, end: i64) -> i64

Creates a random number in [start, end]. Both bounds must be >= 0 and <= UINT_MAX.

min(a: Any, b: Any) -> Any

Returns the smaller of a and b.

max(a: Any, b: Any) -> Any

Returns the larger of a and b.

clamp(val: Any, low: Any, high: Any) -> Any

Returns low if val is less than low, high if val is greater than high, otherwise val. Garbage in, garbage out.

swap(a: Any, b: Any) -> void

Swaps the values of a and b. Both parameters are passed via shared assign.

abs(n: Number) -> Number

Returns the absolute value of n (as the same type as n). n must be a number.

trunc(n: Number) -> f64
_trunc(n: f64) -> f64

Rounds the given number toward zero as f64. For example, 1.9 yields 1.0 and -2.9 yields -2.0. trunc does to-number conversion on input; _trunc is the lower-level primitive that requires n to already be an f64.

floor(n: Number) -> f64

Rounds the given number down to the next smaller integer as f64. For example, 1.9 yields 1.0 and -2.1 yields -3.0.

ceil(n: Number) -> f64

Rounds the given number up to the next greater integer as f64. For example, 1.1 yields 2.0 and -1.9 yields -1.0.

round(n: Number) -> f64

Rounds the given number to the nearest integer as f64. For example, 1.1 yields 1.0; both 1.6 and 1.5 yield 2.0.

pow(base: Any, exp: i64) -> f64

Computes base raised to the integer exponent exp. If exp is a float, it gets truncated. To-number conversion is applied to base. Returns an f64.

sqrt(n: Any) -> f64
_sqrt(n: f64) -> f64

Computes the square root of the given input. sqrt does to-number conversion on input; _sqrt is the lower-level primitive that requires n to already be an f64.

timevals(t: f64,
         HH: i64, MM: i64, S: i64, ms: i64) -> Bool

Computes the hour, minute, second and (optionally) millisecond parts of the given time in seconds (e.g. from clock()). Note: hours can be greater than 23/24 — the value is not cut at the day boundary.

timetostr(t: f64, with_ms: Bool) -> String | Bool

Builds a 24-hour wall-clock string with format HH:MM:SS.mmm (milliseconds are optional). Note: if t exceeds 24 hours the result is not cut.

rolldice(eyes: i64) -> i64

Randomly rolls a die with eyes faces and returns the result.

inc(n: Number (in/out), step: Number := 1) -> Number

Increments n by step (default 1).

dec(n: Number (in/out), step: Number := 1) -> Number

Decrements n by step (default 1).

_seq(start: i64, end: i64, step: i64) -> Sequence

Creates an IntegerSequence of [start, end] with the given step. If end is smaller than start, step must be negative. The sequence starts at start and the next value is current + step. If end cannot be reached exactly by stepping, the value remains at the last current — for example, _seq(1, 10, 2) produces 1, 3, 5, 7, 9. Sequences can be used in forall loops.

_error_get_code(e: Error) -> i64

Returns the code of the Error as i64.

_error_get_name(e: Error) -> String

Returns the name of the Error as a string.

_error_get_message(e: Error) -> String

Returns the message of the Error as a string.

make_runtime_error(message: String) -> Error

Creates a runtime Error with the given message. An alternative is "str" as Error.

_tuple_create(...) -> Tuple

Creates a tuple from the passed parameters. Parameter count is variable; each parameter can be of any type.

_tuple_named_create(...) -> Tuple

Creates a named tuple from the given parameters. Each parameter must be a 2-element tuple whose first element is a String (the name) and whose second element can be any type. Example: _tuple_named_create(("name", "John"), ("age", 31)).

_tuple_size(tup: Tuple) -> i64

Returns the element count of the tuple.

_tuple_same_types(a: Tuple, b: Tuple) -> Bool

Checks whether the two tuples have the same types in exactly the same order (and with the same names).

_tuple_val(tup: Tuple, idx: i64) -> Any

Returns the value at the given index.

_tuple_named_val(tup: Tuple, name: String) -> Any

Returns the value with the given name, or throws if it does not exist.

_tuple_set(tup: Tuple, idx: i64, val: Any) -> void

Sets the value at the given index, or throws if the index does not exist.

_tuple_named_set(tup: Tuple, name: String, val: Any) -> void

Sets the value with the given name, or throws if the name does not exist.

_tuple_append(tup: Tuple, val: Any) -> void

Appends a new value to the end as a new element.

_tuple_named_append(tup: Tuple, name: String, val: Any) -> Bool

Appends a new value with the given name to the end as a new element if that name does not exist yet.

_tuple_insert(tup: Tuple, idx: i64, val: Any) -> void

Inserts a new value at the given index.

_tuple_named_insert(tup: Tuple, idx: i64,
                    name: String, val: Any) -> void

Inserts a value with the given name at the given index.

_tuple_remove(tup: Tuple, idx: i64) -> Bool

Removes the element at the given index; returns whether an element has been removed.

_tuple_named_remove(tup: Tuple, name: String) -> Bool

Removes the element with the given name; returns whether an element has been removed.

_tuple_index_of(tup: Tuple, name: String) -> i64

Returns the index of the element with the given name, or -1 if not found.

_tuple_name_of(tup: Tuple, idx: i64) -> String

Returns the name of the element at the given index, or throws if the index does not exist.

_tuple_swap(tup: Tuple, a: i64, b: i64) -> void

Swaps the elements at the given indices.

tuple_print(tup: Tuple, root_name: String,
            max_nesting: i64) -> void

Recursively prints all (named) elements of tup for debugging. root_name is used as the printed root name; max_nesting caps recursion depth.

tuple_contains(tup: Tuple, idx_or_name: Any) -> Bool

Returns whether tup contains the given name (String) or index (i64).

stack_push(stack: Tuple, val: Any) -> void

Pushes val to the end of the tuple, treating it as a stack. Equivalent to _tuple_append.

stack_pop(stack: Tuple) -> Any

Removes the last element of the tuple and returns its value, treating the tuple as a stack. Returns void if the tuple is empty.

_strlen(s: String) -> i64

Returns the length of the string in bytes (excluding the trailing 0).

_strglyphs(s: String) -> i64

Returns the UTF-8 (Unicode) glyph count of the string (excluding the trailing 0).

_strglyphtobytepos(s: String, glyph: i64) -> i64

Returns the byte position of the given glyph in the string, or -1 if out of range.

_strat(s: String, pos: i64) -> String

Returns a substring consisting of one complete UTF-8 code point where pos points into. Returns an empty string if out of range.

_substr(s: String, from: i64, count: i64) -> String

Returns the substring [from, from + count). count of -1 means "until end of string". Returns an empty string on invalid arguments.

_strfind(s: String, substring: String, offset: i64) -> i64

Searches for substring starting at offset and returns the position of the first occurrence, or -1 if not found.

strfind(s: String, substring: String, offset: i64 := 0) -> i64

Convenience wrapper around _strfind with a default offset of 0.

_strfindreverse(s: String, substring: String,
                offset: i64) -> i64

Searches for substring from the back (starting at offset) and returns the position of the first occurrence, or -1 if not found.

_strreplacepos(str: String, start: i64, count: i64,
               new: String) -> Bool

Replaces the section [start, start + count) in str with new. Returns false on error, e.g. when start is out of range.

strreplacefirst(str: String, what: String, new: String,
                offset: i64 := 0) -> Bool

Replaces the first occurrence of what with new starting from offset. Returns true if a replacement happened.

strreplacelast(str: String, what: String, new: String,
               offset: i64 := 0) -> Bool

Replaces the last occurrence of what with new starting from offset. Returns true if a replacement happened.

strtrim(str: String, set: String,
        leading: Bool, trailing: Bool) -> Bool

Trims the string if it starts or ends with characters in the given set.

strsplit(str: String, sep: String,
         skip_empty: Bool := false) -> Tuple

Splits the given string at every occurring separator and returns a tuple with the elements.

strjoin(tup: Tuple, sep: String,
        add_leading: Bool := false,
        add_trailing: Bool := false) -> String

Joins all elements of a tuple to a string using the given separator.

_strfromascii(char: Number) -> String | Error

Returns a string built from the given ASCII character. For invalid chars (>127) an Error is returned.

utf8_begin(s: String) -> UTF8_Iterator

Creates a UTF-8 iterator for the given string and sets .cur to the first UTF-8 glyph. See the UTF8_Iterator tuple for details.

utf8_end(it: UTF8_Iterator) -> Bool

Returns whether the given UTF-8 iterator is already at the end.

utf8_next(it: UTF8_Iterator) -> UTF8_Iterator

Advances the UTF-8 iterator (.cur) to the next UTF-8 glyph or to the end of the string.

cwd() -> String

Returns the current working directory.

change_cwd(path: String) -> Bool

Changes the current working directory.

tempdir() -> String

Returns the configured temp directory as a string.

path_exists(path: String) -> Bool

Returns whether path exists as a directory or a file.

file_exists(file: String) -> Bool

Returns whether the given file exists.

file_size(file: String) -> i64

Returns the file size in bytes. Returns -1 on error, when the file does not exist, or when the path is not a file.

last_modified(path: String) -> String

Returns the last-modified time as a string for the given path, or an empty string if the path does not exist or on error.

create_dir(path: String, recursive: Bool) -> Bool

Creates directories for the given path. recursive == true creates intermediate directories.

path_delete(path: String) -> Bool

Deletes a file or an (empty) directory.

file_copy(file: String, dest_dir: String,
          overwrite: Bool) -> Bool

Copies file to dest_dir if it does not exist there, or if overwrite is true.

file_copy_newer(file: String, dest_dir: String) -> Bool

Copies file to dest_dir if it does not exist there, or if file is newer than the one already in dest_dir.

readtextfile(file: String) -> String | Error

Reads the content of a UTF-8 text file and returns it in a string. An optional BOM is removed.

writetextfile(file: String, str: String,
              overwrite: Bool, bom: Bool) -> Bool

Writes the content of str to a text file. An optional UTF-8 BOM can be written (last parameter). overwrite indicates whether a prior existing file shall be overwritten (old content is destroyed).

readfile(file: String) -> Buffer | Error

Reads the binary content of the file into a buffer. Returns an Error on failure.

writefile(file: String, content: Buffer,
          overwrite: Bool) -> Bool

Writes the content of the buffer to the file. overwrite indicates whether a prior existing file shall be overwritten (old content is destroyed).

readdirfirst(path: String) -> Tuple

Returns the first directory entry of the given path. See the direntry tuple for details.

readdirnext(entry: Tuple) -> Tuple

Returns the next directory entry. See the direntry tuple for details.

readjsonstring(s: String) -> Any

Creates a corresponding object from the given JSON-formatted string. Returns an Error on failure.

readjsonfile(file: String) -> Any

Creates a corresponding object from the given JSON-formatted file. Returns an Error on failure.

writejsonstring(val: Any) -> String | Error

Creates a JSON-formatted string from the object, or an Error on failure.

writejsonfile(val: Any) -> Bool

Writes a JSON-formatted file from the object. Returns true on success.

json_is_object(val: Any) -> Bool

Checks whether val is a JSON-compatible object.

json_is_array(val: Any) -> Bool

Checks whether val is a JSON-compatible array.

json_object_size(obj: Tuple) -> i64

Returns the element count of the object.

json_array_size(arr: Tuple) -> i64

Returns the element count of the array.

json_make_object(...) -> Tuple

Creates a JSON-compatible object from the passed parameters.

json_make_array(...) -> Tuple

Creates a JSON-compatible array from the passed parameters. Parameter count is variable; each parameter can be any type.

json_array_empty(arr: Tuple) -> Bool

Checks whether the given tuple is an empty JSON array.

json_array_append(arr: Tuple, val: Any) -> void

Appends val to a JSON-compatible array. The tuple must be compatible (i.e. json_is_array returned true).

json_array_insert(arr: Tuple, idx: i64, val: Any) -> Bool

Inserts val at index idx of a JSON-compatible array. The tuple must be compatible (i.e. json_is_array returned true).

json_array_remove(arr: Tuple, idx: i64) -> Bool

Removes the value at index idx from a JSON-compatible array. The tuple must be compatible (i.e. json_is_array returned true).

readbsonbuffer(buf: Buffer) -> Any

Creates a value of appropriate type from the given BSON buffer, or an Error on failure.

writebsonbuffer(val: Any) -> Buffer | Error

Creates a BSON buffer, or an Error on failure.

readtomlstring(s: String) -> Tuple | Error

Creates a named tuple from the given TOML-formatted string, or an Error on failure.

readtomlfile(file: String) -> Tuple | Error

Creates a named tuple from the given TOML-formatted file, or an Error on failure.

writetomlstring(tup: Tuple) -> String | Error

Creates a TOML-formatted string from the named tuple, or an Error on failure.

writetomlfile(tup: Tuple) -> Bool

Writes a TOML-formatted file from the named tuple. Returns true on success.

toml_is_table(val: Any) -> Bool

Checks whether val is a TOML-compatible table.

toml_is_array(val: Any) -> Bool

Checks whether val is a TOML-compatible array.

toml_table_size(tab: Tuple) -> i64

Returns the element count of the table.

toml_array_size(arr: Tuple) -> i64

Returns the element count of the array.

toml_make_table(...) -> Tuple

Creates a TOML-compatible table from the passed parameters.

toml_make_array(...) -> Tuple

Creates a TOML-compatible array from the passed parameters. Parameter count is variable; each parameter can be any type.

toml_array_empty(arr: Tuple) -> Bool

Checks whether the given tuple is an empty TOML array.

toml_array_append(arr: Tuple, val: Any) -> void

Appends val to a TOML-compatible array. The tuple must be compatible (i.e. toml_is_array returned true).

toml_array_insert(arr: Tuple, idx: i64, val: Any) -> Bool

Inserts val at index idx of a TOML-compatible array. The tuple must be compatible (i.e. toml_is_array returned true).

toml_array_remove(arr: Tuple, idx: i64) -> Bool

Removes the value at index idx from a TOML-compatible array. The tuple must be compatible (i.e. toml_is_array returned true).

make_rgb(r: i64, g: i64, b: i64) -> i64

Builds a 32-bit RGB color (garbage in, garbage out).

cprint(rgb: i64, s: String) -> void

Prints the text in the given RGB color. Only available when the library is built with libfmt.

cprintln(rgb: i64, s: String) -> void

Same as cprint but adds a line feed at the end.

format(fmt: String, ...) -> String

Formats the string with libfmt the same way as known from C++.

_buf(size: Number) -> Buffer

Creates an empty buffer (size == 0) with the given capacity.

_buf_size(buf: Buffer) -> u64

Returns the actual amount of used / filled bytes in the buffer.

_buf_capacity(buf: Buffer) -> u64

Returns the amount of allocated memory in bytes for the buffer.

buf_zero(buf: Buffer) -> void

Fills the complete capacity of the buffer with zeroes. Postcondition: size == capacity.

_buf_fill(buf: Buffer, pos: Number,
          count: Number, val: u8) -> Bool

Fills the buffer from pos up to pos + count with val.

_buf_fill32(buf: Buffer, pos: Number,
            count: Number, val: u64) -> Bool

Fills the buffer from pos up to pos + count with val as u32. The passed range must be divisible by 4 (sizeof u32).

_buf_resize(buf: Buffer, size: Number) -> Bool

Resizes the buffer (shrink or grow). New values are added as zero. See also _buf_fill.

_buf_copy(dst: Buffer, dst_off: Number,
          src: Buffer, src_off: Number,
          len: Number) -> Bool

Copies the src buffer into the dst buffer.

_buf_at(buf: Buffer, pos: Number) -> u8

Returns the byte at the given position. Throws on out-of-range.

_buf_get_u8(buf: Buffer, pos: Number) -> u8 | Error

Gets a u8 from the buffer at the given position. Returns an Error on failure.

_buf_get_u16(buf: Buffer, pos: Number) -> u64 | Error

Gets a u16 as u64 from the buffer at the given position. Returns an Error on failure.

_buf_get_u32(buf: Buffer, pos: Number) -> u64 | Error

Gets a u32 as u64 from the buffer at the given position. Returns an Error on failure.

_buf_get_u64(buf: Buffer, pos: Number) -> u64 | Error

Gets a u64 from the buffer at the given position. Returns an Error on failure.

_buf_get_i8(buf: Buffer, pos: Number) -> i64 | Error

Gets an i8 as i64 from the buffer at the given position. Returns an Error on failure.

_buf_get_i16(buf: Buffer, pos: Number) -> i64 | Error

Gets an i16 as i64 from the buffer at the given position. Returns an Error on failure.

_buf_get_i32(buf: Buffer, pos: Number) -> i64 | Error

Gets an i32 as i64 from the buffer at the given position. Returns an Error on failure.

_buf_get_i64(buf: Buffer, pos: Number) -> i64 | Error

Gets an i64 from the buffer at the given position. Returns an Error on failure.

_buf_set_u8(buf: Buffer, pos: Number, val: u8) -> Bool

Sets val as u8 in the buffer at the given position. Returns true on success.

_buf_set_u16(buf: Buffer, pos: Number, val: u64) -> Bool

Sets val as u16 in the buffer at the given position. Returns true on success.

_buf_set_u32(buf: Buffer, pos: Number, val: u64) -> Bool

Sets val as u32 in the buffer at the given position. Returns true on success.

_buf_set_u64(buf: Buffer, pos: Number, val: u64) -> Bool

Sets val as u64 in the buffer at the given position. Returns true on success.

_buf_set_i8(buf: Buffer, pos: Number, val: i64) -> Bool

Sets val as i8 in the buffer at the given position. Returns true on success.

_buf_set_i16(buf: Buffer, pos: Number, val: i64) -> Bool

Sets val as i16 in the buffer at the given position. Returns true on success.

_buf_set_i32(buf: Buffer, pos: Number, val: i64) -> Bool

Sets val as i32 in the buffer at the given position. Returns true on success.

_buf_set_i64(buf: Buffer, pos: Number, val: i64) -> Bool

Sets val as i64 in the buffer at the given position. Returns true on success.

_buf_set_string(buf: Buffer, pos: Number,
                val: String) -> Bool

Writes the string val (without the trailing 0) into the buffer at the given position. Returns true on success.

_buf_get_string(buf: Buffer, pos: Number,
                len: Number) -> String | Error

Reads a string from the buffer at the given position. Bytes must form valid UTF-8. Returns an Error on failure.

_buf_get_ascii(buf: Buffer, pos: Number,
               len: Number) -> String | Error

Reads a string from the buffer at the given position. All values must be in the range [0, 127]. Returns an Error on failure.