Version

    Container Functions

    Functions you can use with containers

    append

    <element type>[] append(<element type>[] arg, <element type> list_element);

    variant append(variant arg, variant list_element);

    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.

    Example 69.176. Usage of append

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


    See also:  insert, pop, push

    binarySearch

    integer binarySearch(<element type>[] arg, <element type> key);

    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.

    Example 69.177. Usage of binarySearch

    binarySearch(["a", "b", "d"], "b") returns 1, because the index of "b" is 1.

    binarySearch(["a", "b", "d"], "c") returns -3, because "c" would be inserted at position 2.


    See also:  containsValue

    clear

    void clear(list[<element type>] arg);

    void clear(map[<type of key>,<type of value>] arg);

    void clear(variant arg);

    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.

    Example 69.178. Usage of clear

    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

    containsAll

    boolean containsAll(<element type>[] list, <element type>[] subList);

    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.

    Example 69.179. Usage of containsAll

    The function containsAll([1, 3, 5], [3,5]) returns true.

    The function containsAll([1,3,5], [2,3,5]) returns false.


    See also:  containsKey, containsValue

    containsKey

    boolean containsKey(map[<type of key>,<type of value>] arg, <type of key> key);

    boolean containsKey(variant arg, variant key);

    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.

    Example 69.180. Usage of containsKey

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


    See also:  containsValue, findAllValues, getKeys

    containsValue

    boolean containsValue(map[<type of key>,<type of value>] map, <type of value> value);

    boolean containsValue(list[<element type>] list, <element type> value);

    boolean containsValue(variant listOrMap, variant value);

    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.

    Example 69.181. Usage of containsValue

    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

    copy

    <element type>[] copy(<element type>[] to, <element type>[] from);

    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.

    Example 69.182. Usage of copy

    There are two lists. The list s1 = ["a", "b"] and the list s2 = ["c", "d"]. The function copy(s1, s2) returns ["a", "b", "c", "d"]. The list s1 has been modified and contains values ["a", "b", "c", "d"].


    map[<type of key>, <type of value>] copy(map[<type of key>, <type of value>] to, map[<type of key>, <type of value>] from);

    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.

    Example 69.183. Usage of copy

    Let us have following lines of code.

    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;

    The field field1 contains {a=aa, b=bbb}. The field field2 contains {c=cc, d=ddd}. The field field3 contains {a=aa, b=bbb, c=cc, d=ddd}. The field field4 contains {a=aa, b=bbb, c=cc, d=ddd}. The function copy copies values from the second argument (map2) to the first argument (map1). The field field5 contains {c=cc, d=ddd}.


    See also:  append, insert, poll, push

    findAllValues

    variant findAllValues(variant container, variant key);

    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.

    Example 69.184. Usage of findAllValues

    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

    getKeys

    <type of key>[] getKeys(map[<type of key>, <type of value>] arg);

    variant getKeys(variant arg);

    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.

    Example 69.185. Usage of getKeys

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


    See also:  containsKey, containsValue, findAllValues, getValues

    getValues

    list[<type of value>] getValues(map[<type of key>, <type of value>] arg);

    variant getValues(variant arg);

    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.

    Example 69.186. Usage of getValues

    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]


    See also:  containsKey, findAllValues, getKeys, toMap

    in

    boolean in(<any type> element, <collection type> collection);

    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.

    Example 69.187. Usage of in

    "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

    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

    insert

    list[<element type>] insert(list[<element type>] targetList, integer position, <element type> newElements...);

    list[<element type>] insert(list[<element type>] targetList, integer position, list[<element type>] newElements);

    variant insert(variant targetList, integer position, variant newElements...);

    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.

    Example 69.188. Usage of insert

    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

    isEmpty

    boolean isEmpty(list[<element type>] arg);

    boolean isEmpty(map[<type of key>, <type of value>] arg);

    boolean isEmpty(variant arg);

    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.

    Example 69.189. Usage of isEmpty

    // 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

    length

    integer length(structuredtype arg);

    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.

    Example 69.190. Usage of length:

    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

    poll

    <element type> poll(<element type>[] arg);

    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.

    Example 69.191. Usage of poll

    The function poll(["a", "d", "c"]) returns a. The list given as argument contains ["d", "c"] after the function call.


    See also:  append, insert, pop, remove

    pop

    <element type> pop(<element type>[] arg);

    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.

    Example 69.192. Usage of pop

    • The function pop(["a", "b", "c"]) returns c.

    • The function pop modifies list s1:

      string[] s1 = ["a", "b", "c"];
      $out.0.field1 = s1;
      $out.1.field2 = pop(s1);
      $out.0.field3 = s1;

      field1 on first output port contains ["a", "b", "c"].

      field2 on second output port contains c.

      field3 on first output port contains ["a", "b"].


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

    push

    list[<element type>] push(list[<element type>] targetList, <element type> newElement);

    variant push(variant targetList, variant newElement);

    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.

    Example 69.193. Usage of push

    // 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

    remove

    <element type> remove(<element type>[] arg, integer position);

    variant remove(variant arg, variant position);

    <value type> remove(map[<key type>, <value type>] arg, <key type> key);

    variant remove(variant arg, variant key);

    The function removes:

    • from a given list (or variant containing a list) the element at the specified position and returns the removed element.

      The list specified as the first argument changes its value to the new one. List elements are indexed starting from 0.

    • from a given map (or variant containing a map) the key/value pair identified by the key and returns the value.

    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 CloverETL 5.0.0.

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

    Example 69.194. Usage of remove - list

    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"]
    


    Example 69.195. Usage of remove - map

    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

    reverse

    list[<element type>] reverse(list[<element type>] arg);

    variant reverse(variant arg);

    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.

    Example 69.196. Usage of reverse

    // 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

    sort

    <element type>[] sort(<element type>[] arg);

    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.

    Example 69.197. Usage of sort

    The function sort(["a", "e", "c"]) returns ["a", "c", "e"].


    See also:  reverse

    toMap

    map[<type of key>,<type of value>] toMap(<type of key>[] keys, <type of value>[] values);

    map[<type of key>,<type of value>] toMap(<type of key>[] keys, <type of value> value);

    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.

    Example 69.198. Usage of toMap

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

    The map alphabet has the value alpha accessible under the key "a", bravo accessible under the key "b", etc.

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

    The function toMap() in this example fails as the list of keys (abcKeys) and the list of values (alphaValues) are of the different size.

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

    The function toMap() fails in this example. The list of values cannot be null.

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

    The result is an empty map. The second argument of the function is a single value; therefore, it can be null.

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

    The variable availability contains {ProductA=available, ProductB=available, ProductC=available}. All products all available.

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

    The map result has three values: {a=null, b=null, c=null}.

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

    The result is an empty list.


    See also:  getKeys, getValues, record2map