Built-in data tools

This page describes the built-in data tools:

abs tool

tool int    abs(int x)
tool long   abs(long x)
tool double abs(double x)

Returns the absolute value of an integer, long, or double number.

Parameters

x

The integer, long, or double number.

Returns

The absolute value.

Runtime errors

  • If the operation results in overflow (for integer and long numbers only).

ceil tool

tool long ceil(double x)

Returns the given double number rounded to a whole long number, towards positive infinity.

Parameters

x

The double number.

Returns

The double number rounded to a whole long number, towards positive infinity.

Runtime errors

  • If the operation results in overflow.

contains tool

tool bool contains(string whole, string part)
tool bool contains<T>(list T $list, T elem)
tool bool contains<T>(set T $set, T elem)
tool bool contains<K,V>(map(K:V) $map, K key)

Returns whether a given string is contained in another given string, a given value is contained in a given list, a given value is contained in a given set, or a given value is a key of a given map.

Type parameters

T

The type of the elements of the list or set.

K

The type of the keys of the map.

V

The type of the values of the map.

Parameters

whole, list, set, map

The whole string, the list, the set, or the map.

part, elem, key

The part string (potentially contained in the whole string), or the value (potential element of the list or set, or potential key of the map).

Returns

true if the part string is contained in the whole string, if the value is contained in the list, if the value is contained in the set, or if the value is a key of the map, false otherwise.

del tool

tool list T   del<T>(list T $list, T elem)
tool set T    del<T>(set T $set, T elem)
tool map(K:V) del<K,V>(map(K:V) $map, K key)

Returns the given list with all occurrences of the given element removed from it, the given set with the given element removed from it, or the given map with the given entry with the given key removed from it. If the element or key does not exist, the list, set or map is returned unmodified.

Type parameters

T

The type of the elements of the list or set.

K

The type of the keys of the map.

V

The type of the values of the map.

Parameters

list, set, map

The list, set, or map.

elem, key

The element or key to remove. May be null.

Returns

The list with all occurrences of the element removed from it, the set with the element removed from it, or the map with the entry with the given key removed from it.

delidx tool

tool list T delidx<T>(list T $list, int index)

Removes an element from a list, and returns the list without that element.

Type parameters

T

The type of the elements of the list.

Parameters

list

The list.

index

The 0-based index into the list of the element to remove. Negative indices are allowed, and count from the right.

Returns

The list with the element removed from it.

Runtime errors

  • If the index is out of bounds for the list.

empty tool

tool bool empty(string x)
tool bool empty<T>(list T x)
tool bool empty<T>(set T x)
tool bool empty<K,V>(map(K:V) x)

Returns whether a given string, list, set, or map is empty (no characters, elements, or entries).

Type parameters

T

The type of the elements of the list or set.

K

The type of the keys of the map.

V

The type of the values of the map.

Parameters

x

The string, list, set, or map.

Returns

true if the given string, list, set, or map is empty, false otherwise.

endswith tool

tool bool endswith(string whole, string suffix)

Returns whether the first given string ends with the second given string. For an empty suffix, always returns true.

Parameters

whole

The first given string.

suffix

The second given string.

Returns

true if the first given string ends with the second given string, false otherwise.

entries tool

tool list tuple(K, V) entries<K,V>(map(K:V) $map)

Returns a list with 2-tuples of keys and values for all entries of the given map.

Type parameters

K

The type of the keys of the map.

V

The type of the values of the map.

Parameters

map

The map.

Returns

The list with 2-tuples of keys and values for all entries of the given map.

enumerate tool

tool list tuple(int, T) enumerate<T>(list T $list)

Returns a list with 2-tuples of 0-based indices and elements for all elements of the given list.

Type parameters

T

The type of the elements of the list.

Parameters

list

The list.

Returns

The list with 2-tuples of 0-based indices and elements for all elements of the given list.

floor tool

tool long floor(double x)

Returns the given double number rounded to a whole long number, towards negative infinity.

Parameters

x

The double number.

Returns

The double number rounded to a whole long number, towards negative infinity.

Runtime errors

  • If the operation results in overflow.

fmt tool

tool string fmt(string pattern, object?... args)

Formats a text based on a pattern and arguments.

See also the str tool, as str(value) is equal to fmt("%s", value).

Parameters

pattern

The format pattern.

args

The arguments.

Returns

The formatted text.

Runtime errors

  • If the format pattern is invalid.

  • If the format pattern and arguments don’t match.

indexof tool

tool int indexof(string whole, string part)
tool int indexof(string whole, string part, int offset)
tool int indexof<T>(list T $list, T elem)
tool int indexof<T>(list T $list, T elem, int offset)

Returns the 0-based index of the first occurrence of the second given string or value, in the first given string or list. The tool looks for an occurrence from left to right of the first given string or elements of the first given list. If an offset is given, the tool only looks for an occurrence at or after that 0-based offset. If no offset is not given, the tool starts looking at the first (left most) character or list element.

Returns -1 if the second given string or value doesn’t occur in the first given string or list, at or after the 0-based offset if given, or at all if no offset is given. For an empty second string, always returns 0 if no offset is given. For an empty second string, if an offset is given, always returns the offset, unless there is no character at the given offset, in which -1 is always returned.

Type parameters

T

The type of the elements of the list.

Parameters

whole, list

The first given string, or the list.

part, elem

The second given string, or the value.

offset

The optional 0-based offset.

Returns

The 0-based index of the first occurrence, at or after the given offset if given, or -1.

join tool

tool string join(string... texts)
tool string join(list string texts)
tool string join(list string texts, string separator)

Returns the given texts joined together. They can be joined without any separator, or using a given separator.

Parameters

texts

The texts to join.

separator

The optional separator text to use.

Returns

The joined texts.

keys tool

tool set K keys<K,V>(map(K:V) $map)

Returns a set with the keys of the given map.

Type parameters

K

The type of the keys of the map.

V

The type of the values of the map.

Parameters

map

The map.

Returns

The set with the keys of the map.

lastindexof tool

tool int lastindexof(string whole, string part)
tool int lastindexof(string whole, string part, int offset)
tool int lastindexof<T>(list T $list, T elem)
tool int lastindexof<T>(list T $list, T elem, int offset)

Returns the 0-based index of the last occurrence of the second given string or value, in the first given string or list. The tool looks for an occurrence from left to right of the first given string or elements of the first given list. If an offset is given, the tool only looks for an occurrence at or before that 0-based offset. If no offset is not given, the tool starts looking at the first (left most) character or list element.

Returns -1 if the second given string or value doesn’t occur in the first given string or list, at or before the 0-based offset if given, or at all if no offset is given. For an empty second string, always returns the size of the first given string, if no offset is given. For an empty second string, if an offset is given, always returns the offset, unless there is no character at the given offset, in which -1 is always returned.

Type parameters

T

The type of the elements of the list.

Parameters

whole, list

The first given string, or the list.

part, elem

The second given string, or the value.

offset

The optional 0-based offset.

Returns

The 0-based index of the last occurrence, at or before the given offset if given, or -1.

ln tool

tool double ln(double x)

Returns the natural logarithm of a double number.

Parameters

x

The double number.

Returns

The natural logarithm of the double number.

Runtime errors

  • If the double number is not positive.

log tool

tool double log(double x)

Returns the logarithm (base 10) of a double number.

Parameters

x

The double number.

Returns

The logarithm (base 10) of the double number.

Runtime errors

  • If the double number is not positive.

lower tool

tool string lower(string text)

Returns the given text, converted to lower case. Uses a US English locale.

Parameters

text

The text.

Returns

The text, in lower case.

ltrim tool

tool string ltrim(string text)

Returns the given text with whitespace at the left/start of the text removed.

Parameters

text

The text.

Returns

The text with whitespace at the left/start of the text removed.

max tool

tool int    max(int... x)
tool long   max(long... x)
tool double max(double... x)
tool int    max(list int x)
tool long   max(list long x)
tool double max(list double x)

Returns the maximum of some integer, long, or double numbers. If no numbers are given, the minimum representable finite integer, long, or double value is returned.

Parameters

x

The integer, long, or double numbers.

Returns

The maximum number.

min tool

tool int    min(int... x)
tool long   min(long... x)
tool double min(double... x)
tool int    min(list int x)
tool long   min(list long x)
tool double min(list double x)

Returns the minimum of some integer, long, or double numbers. If no numbers are given, the maximum representable finite integer, long, or double value is returned.

Parameters

x

The integer, long, or double numbers.

Returns

The minimum number.

pow tool

tool double pow(double base, double exponent)

Returns the exponentiation (power) of two double numbers.

Parameters

base

The base double number.

exponent

The exponent double number.

Returns

The exponentiation result.

Runtime errors

  • If the operation results in double overflow, or NaN.

range tool

tool list int range(int count)
tool list int range(int begin, int $end)
tool list int range<T>(list T $list)

Returns a list of numbers representing the range [0..count-1], [begin..end], or [0..size(list)-1]. That is, for count = 5 the list [0, 1, 2, 3, 4] is returned, for begin = -3 and end = 2 the list [-3, -2, -1, 0, 1, 2] is returned, and for a list with 5 elements the list [0, 1, 2, 3, 4] is returned.

Type parameters

T

The type of the elements of the list.

Parameters

count

The number of elements in the resulting list. Negative counts are treated as zero.

begin

The lower bound of the range.

end

The upper bound of the range.

list

The list.

Returns

The range [0..count-1], [begin..end], or [0..size(list)-1].

replace tool

tool string replace(string text, string oldtext, string newtext)
tool list T replace<T>(list T $list, T oldelem, T newelem)

Returns the string or list with old sub strings or elements replaced by new text or elements. For strings, the replacement proceeds from the beginning of the string to the end. That is, replacing "aa" with "b" in the string "aaa" will result in "ba" rather than "ab". For lists, the replacement is performed for all matching old elements.

Type parameters

T

The type of the elements of the list.

Parameters

text, list

The text (string) or list in which to replace text or elements.

oldtext, oldelem

The text (sub string) or element to replace. For list elements, it may be null.

newtext, newelem

The replacement text or element. For list elements, it may be null.

Returns

The text or list with all replacements applied.

reverse tool

tool string reverse(string text)
tool list T reverse<T>(list T $list)

Returns the reverse of the given string or list.

Type parameters

T

The type of the elements of the list.

Parameters

text, list

The string or list.

Returns

The reverse string or list.

round tool

tool long round(double x)

Returns the given double number rounded to the closest whole long number, with ties being rounded toward positive infinity.

Parameters

x

The double number.

Returns

The rounded number.

Runtime errors

  • If the operation results in overflow.

rtrim tool

tool string rtrim(string text)

Returns the given text with whitespace at the right/end of the text removed.

Parameters

text

The text.

Returns

The text with whitespace at the right/end of the text removed.

size tool

tool int size(string x)
tool int size<T>(list T x)
tool int size<T>(set T x)
tool int size<K,V>(map(K:V) x)

Returns the size (number of characters, elements, or entries) of the given string, list, set, or map.

Type parameters

T

The type of the elements of the list or set.

K

The type of the keys of the map.

V

The type of the values of the map.

Parameters

x

The string, list, set, or map.

Returns

The size.

sorted tool

tool list T sorted<T>(list T $list)
tool list T sorted<T>(set T $set)

Returns the given list, or the given set as a list, with the elements sorted in ascending order.

Type parameters

T

The type of the elements of the list or set.

Parameters

list

The list.

set

The set.

Returns

The sorted list.

split tool

tool list string split(string text, string? separator = null, bool removeEmpty = true)

Splits the given text at all non-overlapping occurrences of the given separator.

Parameters

text

The text to split.

separator

The separator text. May be empty or null to split on whitespace.

removeEmpty

Whether to remove empty parts (in case the text starts or ends with the separator, or in case the text contains consecutive separators), or not.

Returns

The parts of the original text resulting from splitting the original text at the separators.

sqrt tool

tool double sqrt(double x)

Returns the square root of a double number.

Parameters

x

The double number.

Returns

The square root.

Runtime errors

  • If the double number is negative.

startswith tool

tool bool startswith(string whole, string prefix)

Returns whether the first given string starts with the second given string. For an empty prefix, always returns true.

Parameters

whole

The first given string.

prefix

The second given string.

Returns

true if the first given string starts with the second given string, false otherwise.

str tool

tool string str(object? value)

Converts the given value into a textual representation, closely resembling the ToolDef syntax.

Values of type string as returned as provided. Values of type string included in containers such as lists are escaped and surrounded by double quotes, as in the ToolDef syntax.

See also the fmt tool, as str(value) is equal to fmt("%s", value).

Parameters

value

The value to convert to a textual representation.

Returns

The textual representation.

strdup tool

tool string strdup(string text, int count)

Duplicates a string a given number of times.

Parameters

text

The string to duplicate.

count

The number of times that the input string should occur in the output.

Returns

The concatenation of count times the text.

Runtime errors

  • If the count is negative.

subset tool

tool bool subset<T>(set T part, set T whole)

Returns whether the first given set is a subset (proper subset or equal) of the second given set.

Type parameters

T

The type of the elements of the sets.

Parameters

part

The first set.

whole

The second set.

Returns

true if the first given set is a subset of the second given set, false otherwise.

trim tool

tool string trim(string text)

Returns the given text with whitespace at the left/start and right/end of the text removed.

Parameters

text

The text.

Returns

The text with whitespace at the left/start and right/end of the text removed.

upper tool

tool string upper(string text)

Returns the given text, converted to upper case. Uses a US English locale.

Parameters

text

The text.

Returns

The text, in upper case.

values tool

tool set V values<K,V>(map(K:V) $map)

Returns a set with the values of the given map.

Type parameters

K

The type of the keys of the map.

V

The type of the values of the map.

Parameters

map

The map.

Returns

The set with the values of the map.