//////////////////////////////////////////////////////////////////////////////
// Copyright (c) 2010, 2026 Contributors to the Eclipse Foundation
//
// See the NOTICE file(s) distributed with this work for additional
// information regarding copyright ownership.
//
// This program and the accompanying materials are made available
// under the terms of the MIT License which is available at
// https://opensource.org/licenses/MIT
//
// SPDX-License-Identifier: MIT
//////////////////////////////////////////////////////////////////////////////

include::../_part_attributes.asciidoc[]

:leveloffset: -2

[[lang-ref-builtins-data]]
== Built-in data tools

This page describes the built-in data tools:

* <<lang-ref-builtins-data-abs,abs>>
* <<lang-ref-builtins-data-ceil,ceil>>
* <<lang-ref-builtins-data-contains,contains>>
* <<lang-ref-builtins-data-del,del>>
* <<lang-ref-builtins-data-delidx,delidx>>
* <<lang-ref-builtins-data-empty,empty>>
* <<lang-ref-builtins-data-endswith,endswith>>
* <<lang-ref-builtins-data-entries,entries>>
* <<lang-ref-builtins-data-enumerate,enumerate>>
* <<lang-ref-builtins-data-floor,floor>>
* <<lang-ref-builtins-data-fmt,fmt>>
* <<lang-ref-builtins-data-indexof,indexof>>
* <<lang-ref-builtins-data-join,join>>
* <<lang-ref-builtins-data-keys,keys>>
* <<lang-ref-builtins-data-lastindexof,lastindexof>>
* <<lang-ref-builtins-data-ln,ln>>
* <<lang-ref-builtins-data-log,log>>
* <<lang-ref-builtins-data-lower,lower>>
* <<lang-ref-builtins-data-ltrim,ltrim>>
* <<lang-ref-builtins-data-max,max>>
* <<lang-ref-builtins-data-min,min>>
* <<lang-ref-builtins-data-pow,pow>>
* <<lang-ref-builtins-data-range,range>>
* <<lang-ref-builtins-data-replace,replace>>
* <<lang-ref-builtins-data-reverse,reverse>>
* <<lang-ref-builtins-data-round,round>>
* <<lang-ref-builtins-data-rtrim,rtrim>>
* <<lang-ref-builtins-data-size,size>>
* <<lang-ref-builtins-data-sorted,sorted>>
* <<lang-ref-builtins-data-split,split>>
* <<lang-ref-builtins-data-sqrt,sqrt>>
* <<lang-ref-builtins-data-startswith,startswith>>
* <<lang-ref-builtins-data-str,str>>
* <<lang-ref-builtins-data-strdup,strdup>>
* <<lang-ref-builtins-data-subset,subset>>
* <<lang-ref-builtins-data-trim,trim>>
* <<lang-ref-builtins-data-upper,upper>>
* <<lang-ref-builtins-data-values,values>>

indexterm:[abs]

[[lang-ref-builtins-data-abs]]
=== abs tool

[source, tooldef]
----
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).

indexterm:[ceil]

[[lang-ref-builtins-data-ceil]]
=== ceil tool

[source, tooldef]
----
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.

indexterm:[contains]

[[lang-ref-builtins-data-contains]]
=== contains tool

[source, tooldef]
----
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.

indexterm:[del]

[[lang-ref-builtins-data-del]]
=== del tool

[source, tooldef]
----
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.

indexterm:[delidx]

[[lang-ref-builtins-data-delidx]]
=== delidx tool

[source, tooldef]
----
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.

indexterm:[empty]

[[lang-ref-builtins-data-empty]]
=== empty tool

[source, tooldef]
----
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.

indexterm:[endswith]

[[lang-ref-builtins-data-endswith]]
=== endswith tool

[source, tooldef]
----
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.

indexterm:[entries]

[[lang-ref-builtins-data-entries]]
=== entries tool

[source, tooldef]
----
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.

indexterm:[enumerate]

[[lang-ref-builtins-data-enumerate]]
=== enumerate tool

[source, tooldef]
----
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.

indexterm:[floor]

[[lang-ref-builtins-data-floor]]
=== floor tool

[source, tooldef]
----
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.

indexterm:[fmt]

[[lang-ref-builtins-data-fmt]]
=== fmt tool

[source, tooldef]
----
tool string fmt(string pattern, object?... args)
----

Formats a text based on a pattern and arguments.

See also the <<lang-ref-builtins-data-str,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.

// TODO: Include format pattern syntax and details, etc. See also CIF documentation.

indexterm:[indexof]

[[lang-ref-builtins-data-indexof]]
=== indexof tool

[source, tooldef]
----
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`.

indexterm:[join]

[[lang-ref-builtins-data-join]]
=== join tool

[source, tooldef]
----
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.

indexterm:[keys]

[[lang-ref-builtins-data-keys]]
=== keys tool

[source, tooldef]
----
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.

indexterm:[lastindexof]

[[lang-ref-builtins-data-lastindexof]]
=== lastindexof tool

[source, tooldef]
----
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`.

indexterm:[ln]

[[lang-ref-builtins-data-ln]]
=== ln tool

[source, tooldef]
----
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.

indexterm:[log]

[[lang-ref-builtins-data-log]]
=== log tool

[source, tooldef]
----
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.

indexterm:[lower]

[[lang-ref-builtins-data-lower]]
=== lower tool

[source, tooldef]
----
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.

indexterm:[ltrim]

[[lang-ref-builtins-data-ltrim]]
=== ltrim tool

[source, tooldef]
----
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.

indexterm:[max]

[[lang-ref-builtins-data-max]]
=== max tool

[source, tooldef]
----
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.

indexterm:[min]

[[lang-ref-builtins-data-min]]
=== min tool

[source, tooldef]
----
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.

indexterm:[pow]

[[lang-ref-builtins-data-pow]]
=== pow tool

[source, tooldef]
----
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`.

indexterm:[range]

[[lang-ref-builtins-data-range]]
=== range tool

[source, tooldef]
----
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]`.

indexterm:[replace]

[[lang-ref-builtins-data-replace]]
=== replace tool

[source, tooldef]
----
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 all non-overlapping 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 `+"aaaaa"+` will result in `"bba"`.
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.

indexterm:[reverse]

[[lang-ref-builtins-data-reverse]]
=== reverse tool

[source, tooldef]
----
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.

indexterm:[round]

[[lang-ref-builtins-data-round]]
=== round tool

[source, tooldef]
----
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.

indexterm:[rtrim]

[[lang-ref-builtins-data-rtrim]]
=== rtrim tool

[source, tooldef]
----
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.

indexterm:[size]

[[lang-ref-builtins-data-size]]
=== size tool

[source, tooldef]
----
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.

indexterm:[sorted]

[[lang-ref-builtins-data-sorted]]
=== sorted tool

[source, tooldef]
----
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.

indexterm:[split]

[[lang-ref-builtins-data-split]]
=== split tool

[source, tooldef]
----
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.

indexterm:[sqrt]

[[lang-ref-builtins-data-sqrt]]
=== sqrt tool

[source, tooldef]
----
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.

indexterm:[startswith]

[[lang-ref-builtins-data-startswith]]
=== startswith tool

[source, tooldef]
----
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.

indexterm:[str]

[[lang-ref-builtins-data-str]]
=== str tool

[source, tooldef]
----
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 <<lang-ref-builtins-data-fmt,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.

indexterm:[strdup]

[[lang-ref-builtins-data-strdup]]
=== strdup tool

[source, tooldef]
----
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.

indexterm:[subset]

[[lang-ref-builtins-data-subset]]
=== subset tool

[source, tooldef]
----
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.

indexterm:[trim]

[[lang-ref-builtins-data-trim]]
=== trim tool

[source, tooldef]
----
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.

indexterm:[upper]

[[lang-ref-builtins-data-upper]]
=== upper tool

[source, tooldef]
----
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.

indexterm:[values]

[[lang-ref-builtins-data-values]]
=== values tool

[source, tooldef]
----
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.
