Adds the second argument to the end of the list specified as the first argument. The function returns the modified list.

This function is an alias of the push function.

If the given list is null, the function fails with an error.

The variant version fails if the first argument is not a list.

Compatibility

The append(E[],E) function is available since CloverETL 3.0.0.

The append(variant,variant) function is available since CloverDX 5.6.0.

append(["a", "b", "d"], "c"); // returns list ["a", "b", "d", "c"]

See also:  insert, pop, push

The binarySearch() function searches a specified list for a specified object using the binary search algorithm.

The elements of the list must be comparable and the list must be sorted in ascending order. If it is not sorted, the results are undefined.

Returns the index of the search key (≥ 0) if it is contained in the list. Otherwise, returns a negative number defined as (-(insertion point) - 1). The insertion point is defined as the point at which the key would be inserted into the list.

If the list contains multiple objects equal to the search key, there is no guarantee which one will be found.

The function fails if either of the arguments is null or if <element type> is not comparable.

Compatibility

The isEmpty() function is available since CloverETL 4.1.0-M1.

See also:  containsValue

Empties the given list or map.

If the given argument is null, the function fails with an error.

Compatibility

The clear(list[E]) and clear(map[K,V]) functions are available since CloverETL 3.0.0.

The clear(variant) function is available since CloverDX 5.7.0.

list[string] listOfStrings = ["a", "b"];
clear(listOfStrings); // listOfStrings is now an empty list: []

map[string, string] mapOfStrings = {"a" -> "aa", "b" -> "bbb"};
clear(mapOfStrings); // mapOfStrings is now an empty map: {}

variant varList = ["John", 34];
clear(varList); // varList is now an empty list: []

variant varMap = {"name" -> "John", "age" -> 34};
clear(varMap); // varMap is now an empty map: {}

See also:  poll, pop, remove

The containsAll() function returns true if the list specified as the first argument contains every element of the list specified as the second argument, i.e. the second list is a sublist of the first list.

If one of the given list has a null reference, the function fails with an error.

Compatibility

The containsAll(E[],E[]) function is available since CloverETL 3.3.x.

See also:  containsKey, containsValue

Returns true, if the specified map (or variant containing a map) contains a mapping for the specified key.

If the given map is null, the function fails with an error.

Compatibility

The containsKey(map[K,V],K) function is available since CloverETL 3.3.x.

The containsKey(variant,variant) function is available since CloverDX 5.6.0.

containsKey({1 -> 17, 5 -> 10}, 1); // returns true
containsKey({1 -> 17, 5 -> 10}, 2); // returns false

See also:  containsValue, findAllValues, getKeys

The containsValue(map, value) function returns true if the specified map maps one or more keys to the specified value.

The containsValue(list, value) function returns true if the specified list contains the specified value.

The containsValue(variant, variant) function works as one of the two functions above, depending on whether the first argument contains a list or a map.

If the first argument is null, the function fails with an error.

Compatibility

The containsValue(map[K,V],V) function is available since CloverETL 3.3.x.

The function containsValue(list[E],E) is available since CloverETL 4.0.0.

The function containsValue(variant, variant) is available since CloverDX 5.7.0.

map[integer, integer] mapOfIntegers = {1 -> 17, 5 -> 19};
boolean mapContains23 = containsValue(mapOfIntegers, 23); // false
// mapOfIntegers contains 17 under the key 1
boolean mapContains17 = containsValue(mapOfIntegers, 17); // true
// 5 is a key, not a value
boolean mapContains5 = containsValue(mapOfIntegers, 5); // false
 
list[integer] listOfIntegers = [10, 17, 19, 30];
boolean listContains23 = containsValue(listOfIntegers, 23); // false
boolean listContains17 = containsValue(listOfIntegers, 17); // true
 
variant varMap = {"name" -> "John", "age" -> 34};
boolean varMapContainsHarry = containsValue(varMap, "Harry"); // false
boolean varMapContainsJohn = containsValue(varMap, "John"); // true
boolean varMapContains34 = containsValue(varMap, 34); // true
// "name" is a key, not a value
boolean varMapContainsName = containsValue(varMap, "name"); // false
 
variant varList = ["John", 34];
boolean varListContainsHarry = containsValue(varList, "Harry"); // false
boolean varListContainsJohn = containsValue(varList, "John"); // true
boolean varListContains34 = containsValue(varList, 34); // true

See also:  containsKey, findAllValues, getValues, binarySearch

The copy() function copies items from one list to another.

The function accepts two list arguments of the same data types. The function takes the second argument, adds it to the end of the first list and returns the new value of the list specified as the first argument.

If one of the given lists has a null reference, the function fails with an error.

Compatibility

The copy(E[],E[]) function is available since CloverETL 3.0.0.

The copy() function accepts two map arguments of the same data type. The function takes the second argument, adds it to the end of the first map replacing existing key mappings and returns the new value of the map specified as the first argument.

If one of the given maps has a null reference, the function fails with an error.

If some key exists in both maps, the result will contain value from the second one.

map[string, string] map1;
map1["a"] = "aa";
map1["b"] = "bbb";
map[string, string] map2;
map2["c"] = "cc";
map2["d"] = "ddd";

$out.0.field1 = map1;
$out.0.field2 = map2;
$out.0.field3 = copy(map1, map2);
$out.0.field4 = map1;
$out.0.field5 = map2;

See also:  append, insert, poll, push

Returns the list of all values associated with the specified key at any level of the structure specified as the first argument.

Returns an empty list if nothing was found.

The container can be of any data type, however if this object contains no map the result will be an empty list.

If the key is a record or a byte array, the function fails with an error.

Compatibility

The findAllValues(variant, variant) function is available since CloverDX 5.7.0.

variant json = { // usually obtained by parseJson('...');
    "name" -> "CloverDX",
    "addresses" -> [
        {"city" -> "Arlington", "street" -> "2111 Wilson Blvd"},
        {"city" -> "London", "street" -> "1 Lyric Square"}
    ]
};
variant cities = json.findAllValues("city");
    // returns the list ["Arlington", "London"]

variant numbers = {1 -> 2, 3 -> 4};
numbers.findAllValues(3); // returns [4]
numbers.findAllValues(0); // returns an empty list

variant objects = [
        {
            "id" -> 1,
            "content" -> {
                "id" -> 2,
                "content" -> "aaa"
            }
        },
        {
            "id" -> 3,
            "content" -> "bbb"
        }
];
objects.findAllValues("content");
    // returns [{"id" -> 2, "content" -> "aaa"}, "aaa", "bbb"]
    // the result contains all values associated with the key "content",
    // including the nested object

findAllValues("randomString", "r");
    // returns an empty list - "randomString" is not a map

See also:  containsKey, containsValue, getKeys, getValues

Returns the list of keys of the specified map.

The returned list is of the same type as the map's keys.

If a given map is null, the function fails with an error.

The variant version fails if the argument is not a map.

Compatibility

The getKeys(map[K,V]) function is available since CloverETL 3.3.x.

The getKeys(variant) function is available since CloverDX 5.6.0.

map[string, integer] myMap = {"first" -> 1, "second" -> 2};
list[string] listOfKeys = getKeys(myMap); // ["first", "second"]

$out.0.variantField = myMap;
listOfKeys = getKeys($out.0.varianField); // ["first", "second"]

variant myMapVariant = {1 -> true, "hello" -> false};
variant listOfVariantKeys = getKeys(myMapVariant); // [1, "hello"]

See also:  containsKey, containsValue, findAllValues, getValues

Returns the values contained in the specified map as a list.

If the argument is an empty map, the function returns an empty list.

If the argument is null, the function fails.

Compatibility

The getValues(map[K, V]) function is available since CloverETL 4.0.0.

The getValues(variant) function is available since CloverDX 5.7.0.

map[string, string] greek = {"a" -> "alpha", "b" -> "beta"};
list[string] greekValues = getValues(greek); // ["alpha", "beta"]

map[string, string] emptyMap = {};
list[string] emptyMapValues = getValues(emptyMap); // an empty list: []

variant varMap = {"name" -> "John", "age" -> 34};
variant varMapValues = getValues(varMap); // the list ["John", 34]

$out.0.variantField = varMap;
variant varMapValues = getValues($out.0.variantField); // the list ["John", 34]

See also:  containsKey, findAllValues, getKeys, toMap

Returns true if the specified collection contains the specified element.

If the collection is a map, returns true if the map contains the element as a key.

Compatibility

The in(map[K,V], V) function is available since CloverETL 3.3.x.

The function in(list[E], E) is available since CloverETL 3.3.x.

The function in(any type, variant) is available since CloverDX 5.7.0.

"abc".in(["abc", "b"]); // returns true
                     
in(10, [10, 20]); // returns true

10.in([10, 20]); // returns true

// assumes that $in.0 contains listField of type list[string]
in("abc", $in.0.listField); // returns true if "abc" is in the list

// assumes that $in.0 contains mapField of type map[string, string]
in("abc", $in.0.mapField); // returns true if "abc" is a key in the map

Note

Note that searching for an element in a large list may be slow in comparison with searching for a key in a map, because list elements need to be checked one by one. For lists and maps of a specific numeric type, e.g. list[number] or a map with keys of type number, the searched-for element is automatically converted to the target type if possible, e.g. integers are converted to numbers. For variant, there is no such automatic type conversion, the types must exactly match for the function to return true. integer i = 2; list[number] numbers = [2.1, 2.0, 2.2]; // 2 is automatically converted to number 2.0 boolean result = i.in(numbers); // true variant varNumbers = [2.1, 2.0, 2.2]; // no automatic conversion, the types must exactly match result = i.in(varNumbers); // false

See also:  containsValue, containsKey

Inserts one or more elements into the list at the specified position, indexed from 0. Moves the element currently at that position (if any) and all subsequent elements to the right. Returns the modified list.

If the list given as the first argument is null, the function fails with an error.

Compatibility

The insert(list[E], integer, E...) and insert(list[E], integer, list[E]) functions are available since CloverETL 3.0.0.

The insert(variant, integer, variant...) function is available since CloverDX 5.7.0.

list[string] originalList = ["a", "d", "b"];
list[string] modifiedList = insert(originalList, 1, "c");
// both originalList and modifiedList are now ["a", "c", "d", "b"]
 
// inserting multiple elements:
list[string] multiple = insert(["a", "b", "a", "b"], 2, "c", "d", "e");
// ["a", "b", "c", "d", "e", "a", "b"]
 
// inserting a list of elements:
list[string] twoLists = insert(["a", "b", "a", "b"], 2, ["c", "d"]);
// ["a", "b", "c", "d", "a", "b"]

// variant:
variant varList = ["John", 34, true];
variant varModified = insert(varList, 2,
     {"street" -> "Wilson Blvd"}, ["John", "Thompson"]);
// both varList and varModified are now
//   ["John", 34, {"street" -> "Wilson Blvd"}, ["John", "Thompson"], true]

See also:  isNull, push, remove

Returns true if the specified list, map or string is empty.

If the argument is null, the function fails with an error.

Compatibility

The isEmpty(list[E]) and isEmpty(map[K,V]) functions are available since CloverETL 3.0.0.

The isEmpty(variant) function is available since CloverDX 5.7.0.

// list:
boolean b1 = isEmpty(["a", "b"]); // false
list[string] emptyList = [];
boolean b2 = isEmpty(emptyList); // true

// map:
boolean b3 = isEmpty({"a" -> "alpha"}); // false
map[string, integer] emptyMap = {};
boolean b4 = isEmpty(emptyMap); // true

// variant:
variant varMap = {"b" -> "beta"}; // map with one key-value pair
boolean b5 = isEmpty(varMap); // false
variant varList = []; // empty list
boolean b6 = isEmpty(varList); // true

See also:  String function: isEmpty, poll, pop

Returns the number of elements forming a given structured data type.

The argument can be one of following: string, list, map, record or variant containing any of these types.

For maps the function returns the number of key-value pairs and for nested lists it returns the size of the top-level list.

If the argument is null, the function returns 0.

Compatibility

The length(E[]) and length(map[K,V]) functions are available since CloverETL 3.0.0.

The length(variant) function is available since CloverDX 5.6.0.

length(["a", "d", "c"]); // returns 3
list[list[string]] listOfLists = [
                                    ["a", "d"], 
                                    ["d", "e", "f"]
                                 ];
length(listOfLists); // returns 2

See also:  String functions: length, Record functions: length

The poll() function removes the first element from a given list and returns this element.

The list specified as the argument changes to this new value (without the removed first element).

If a given list has a null reference, the function fails with an error.

Compatibility

The poll(E[]) function is available since CloverETL 3.0.0.

See also:  append, insert, pop, remove

The pop() function removes the last element from a given list and returns this element.

The list specified as the argument changes to this new value (without the removed last element).

If a given list has a null reference, the function fails with an error.

Compatibility

The pop(E[]) function is available since CloverETL 3.0.0.

See also:  append, isEmpty, poll, push, remove

Adds an element to the end of the specified list. Returns the modified list.

This function is an alias of the append function.

If the given list is null, the function fails with an error.

The variant version fails if the first argument is not a list.

Compatibility

The push(list[E], E) function is available since CloverETL 3.0.0.

The push(variant, variant) function is available since CloverDX 5.7.0.

// list:
list[string] originalList = ["a", "b", "c"];
list[string] modifiedList = push(originalList, "d");
// both originalList and modifiedList are now ["a", "b", "c", "d"]
 
// variant:
variant varList = ["John", 34, true];
variant varModified = push(varList, {"street" -> "Wilson Blvd"});
// both varList and varModified are now ["John", 34, true, {"street" -> "Wilson Blvd"}]

See also:  append, insert, pop, remove

The function removes:

If the given list or map is null, the function fails with an error.

Compatibility

The remove(E[], integer) function is available since CloverETL 3.0.0.

The remove(map[K,V], K) function is available since CloverDX 5.0.0.

The remove(variant, variant) function is available since CloverDX 5.6.0.

remove(["a", "b", "c"], 1); // returns "b"

list[string] s = ["a", "b", "c"];

list[string] backup = s; // assigns a copy of 's' to 'backup'
string removed = remove(s, 1); // removes "b" from 's' and assigns it to 'removed'
// s == ["a", "c"]
list[string] modified = s; // assigns a copy of modified 's' to 'modified'

// backup == ["a", "b", "c"]
// removed == "b"
// modified == ["a", "c"]

map[string, integer] aMap = {"a" -> 1, "b" -> 2, "c" -> 3};

integer deletedValue = remove(aMap, "b");

integer aValue = aMap["a"]; // 1
integer bValue = aMap["b"]; // null
integer cValue = aMap["c"]; // 3

See also:  append, insert, poll, push

Reverses the order of elements of the given list and returns the modified list.

If the argument is null, the function fails with an error.

The variant version fails if the argument is not a list.

Compatibility

The reverse(list[E]) function is available since CloverETL 3.1.2.

The reverse(variant) function is available since CloverDX 5.7.0.

// list:
list[string] originalList = ["a", "b", "c", "d"];
list[string] modifiedList = reverse(originalList);
// both originalList and modifiedList are now ["d", "c", "b", "a"]
 
// variant:
variant varList = [["a"], ["b", "c"], ["ab"], ["c", "d"]];
variant varModified = reverse(varList);
// both varList and varModified are now [["c", "d"], ["ab"], ["b", "c"], ["a"]]

See also:  sort, String functions: reverse

The sort() function sorts the elements of a given list in ascending order according to their values and returns such new value of the list specified as the first argument.

Null values are listed at the end of the list, if present.

If a given list has a null reference, the function fails with an error.

Compatibility

The sort() function is available since CloverETL 3.0.0.

See also:  reverse

The function toMap(k[], v[]) converts a list of keys and lists of values to the map. The function toMap(k[], v) converts a list of keys and value to the map.

The keys is a list containing the keys of the returned map.

The values is a list of values corresponding to the keys. If only one value is defined, the value corresponds to all keys in the returned map.

The data types of list of keys must correspond to the data type of key in the map, the data type(s) of value(s) must correspond to the data type of values in the map.

The length of the list of keys (keys argument) must be equal to the length of list of the values (values argument).

If the parameter keys is null, the function fails.

If the parameter values is null, the function toMap(<type of key>[],<type of value>[]) fails.

If the parameter value is null, the function toMap(<type of key>[],<type of value>) returns a map having null for all keys.

Compatibility

The toMap() function is available since CloverETL 4.0.0.

    string[] alphaValues = ["alpha", "bravo", "charlie", "delta"];
    string[] abcKeys = ["a", "b", "c", "d"];
    map[string, string] alphabet = toMap(abcKeys, alphaValues);

    string[] alphaValues = ["alpha", "bravo", "charlie", "delta"];
    string[] abcKeys = ["a", "b", "c"];
    map[string, string] alphabet = toMap(abcKeys, alphaValues);

    string[] s = null;
    map[string, string] result = toMap(abcKeys, s);

    string[] keys;
    string[] values;
    map[string, string] result = toMap(keys, values);

    string[] products = ["ProductA", "ProductB", "ProductC"];
    map[string, string] availability = toMap(products, "available");

    string[] keys = ["a", "b", "c"];
    string val = null;
    map[string, string] result = toMap(keys, val);

    string[] keys;
    string valueNull = null;
    map[string, string] result = toMap(keys, valueNull);

See also:  getKeys, getValues, record2map