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
nullto 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.