## Built-in data tools

This page describes the built-in data tools:

- abs

- ceil

- contains

- del

- delidx

- empty

- endswith

- entries

- enumerate

- floor

- fmt

- indexof

- join

- keys

- lastindexof

- ln

- log

- lower

- ltrim

- max

- min

- pow

- range

- replace

- reverse

- round

- rtrim

- size

- sorted

- split

- sqrt

- startswith

- str

- strdup

- subset

- trim

- upper

- values

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