Version

    Container Functions

    When working with containers (list, map and record), you will typically use the 'contained in' function call - in. This call identifies whether a value is contained in a list or a map of other values. There are two syntactic options: 

    boolean myBool;
string myString; 
string[] myList;
map[string, long] myMap;
...

    1. myBool = myString.in(myList)
    2. myBool = in(myString,myList);
    3. myBool = in(myString,myMap);

    In the table below, examine (im)possible ways of using in:

    CodeWorking?
    'abc'.in(['a', 'b'])
    no
    in(10, [10, 20])
    no
    10.in([10, 20])
    no

    As for lists and maps in metadata, use in like this:

    CodeComment
    in('abc', $in.0.listField)
    		operator syntax for list field
    in('abc', $in.0.mapField)
    		operator syntax for map field, searching for a key of map entry

    [Note]Note

    The operator syntax has a disadvantage. Searching through lists will always be slow (since it has to be linear).

    It is better to use the containsKey() and containsValue() functions for searching for keys and values of a map.

    Functions you can use with containers

    append

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

    The append() function adds element to the list.

    The function takes a list of any element data type specified as the first argument and adds it to the end of a list of elements of the same data type specified as the second argument. The function returns the new value of list specified as the first argument.

    This function is an alias of the push(<element type>[], <element type>) function. From the list point of view, append() is much more natural.

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

    Compatibility

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

    Example 67.170. Usage of append

    The function append(["a", "b", "d"], "c") returns [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 67.171. 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(<element type>[] arg);

    The clear() function empties a given list argument of any element data type. It returns void.

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

    Compatibility

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

    Example 67.172. Usage of clear

    The function clear(["a", "b"])returns [].


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

    The clear() function empties a given map argument. It returns void.

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

    Example 67.173. Usage of clear

    There is map[string, string] map2 with values map2["a"] = "aa" and map2["b"] = "bbb". The call of function clear(map2) results into {}.


    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 67.174. 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>] map, <type of key> key);

    The containsKey() function returns true, if the specified map contains a mapping for the specified key.

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

    Compatibility

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

    Example 67.175. Usage of containsKey

    Let us have a map map[integer, integer] map1; map1[1] = 17; map1[5] = 19;.

    The function containsKey(map1, 1) returns true.

    The function containsKey(map1, 2) returns false.


    See also:  containsValue, getKeys

    containsValue

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

    boolean containsValue(<element type>[] list, <element type> 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.

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

    Compatibility

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

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

    Example 67.176. Usage of containsValue

    Let us have a map map[integer, integer] map1; map1[1] = 17; map1[5] = 19;.

    The function containsValue(map1, 23) returns false.

    The function containsValue(map1, 17) returns true.

    The function containsValue([10, 17, 19, 30], 23) returns false.

    The function containsValue([10, 17, 19, 30], 17) returns true.


    See also:  containsKey, 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 67.177. 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 67.178. 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

    getKeys

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

    The getKeys() function returns a list of a given map's keys.

    Remember the list has to be the same type as map's keys.

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

    Compatibility

    The getKeys() function is available since CloverETL 3.3.x.

    Example 67.179. Usage of getKeys

    map[string, integer] myMap;
myMap["first"] = 1; // filling the map with values
string[] listOfKeys = getKeys(myMap);

    The listOfKeys contains [first]


    See also:  containsKey, containsValue, getValues

    getValues

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

    The function getValues() returns values contained in map arg as a list.

    If the arg is an empty map, the function getValues() returns empty list.

    If the arg is null, function getValues() fails.

    Compatibility

    The getValues() function is available since CloverETL 4.0.0.

    Example 67.180. Usage of getValues

     map[string, string] greek;
    greek["a"] = "alpha";
    greek["b"] = "beta";
    string[] values = getValues(greek);

    The function getValues() returns [alpha, beta]. 

      map[string,string] m;
    string[] values = getValues(greek);

    The function getValues() returns empty list. 

      map[string,string] m = null;
    string[] values = getValues(greek);

    The function getValues() having a null argument fails.


    See also:  containsKey, getKeys, toMap,

    insert

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

    The insert() function inserts element into the list.

    The item specified as the third argument is inserted to a position specified as the second argument in a list of elements specified as the first argument. The list specified as the first argument is changed to this new value and it is returned by the function. The list of elements and the element to insert must be of the same data type. Remember that the list elements are indexed starting from 0.

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

    Compatibility

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

    Example 67.181. Usage of insert

    There is a list string[] s1 = ["a", "d", "c"]. The function insert(s1, 1, "b") returns [a, b, d, c]. The original list s1 has been modified too.


    See also:  isNull, push, remove

    isEmpty

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

    The isEmpty() function checks whether a given list is empty.

    If the list is empty, the function returns true, otherwise the function returns false.

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

    Compatibility

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

    Example 67.182. Usage of isEmpty

    The function isEmpty(["a", "b"]) returns false.

    The function isEmpty in the following code returns true. 

    string[] s1;
isEmpty(s1);


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

    The isEmpty() function checks whether a given map is empty.

    If the map is empty, the function returns true otherwise the function returns false.

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

    Example 67.183. Usage of isEmpty

    map[string, integer] map1;
$out.0.field1 = isEmpty(map1);
map1["a"] = 1;
$out.0.field2 = isEmpty(map1);

    The field field1 is true, the field field2 is false.


    See also:  String function: isEmpty, poll, pop

    length

    integer length(structuredtype arg);

    The length() function returns a number of elements forming a given structured data type.

    The argument can be one of following: string, <element type>[], map[<type of key>,<type of value>] or record.

    If a given string, list or map has a null reference, the function returns 0.

    Compatibility

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

    Example 67.184. Usage of length:

    The function length(["a", "d", "c"]) returns 3.


    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 67.185. 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 67.186. 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

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

    The push() function adds the element to the end of the list.

    The element to be added is specified as the second argument and the list is specified as the first argument. Having added the item, the list is returned. The element to add must have the same data type as the elements of the list.

    This function is an alias of the append(<element type>[], <element type>) function. From the stack/queue point of view, push() is much more natural.

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

    Compatibility

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

    Example 67.187. Usage of push

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

    See the following code: 

    string[] s1 = ["a", "d", "c"];
$out.0.field1 = push(s1, "e");
$out.0.field2 = s1;

    The field field2 will contain ["a", "b", "c", "e"] as the s1 has been modified by push.


    See also:  append, insert, pop, remove

    remove

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

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

    The remove() function removes:

    • from a given 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.

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

    • from a given map the key/value pair identified by the key and returns the value.

    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.

    Example 67.188. Usage of remove - list

    The function remove(["a", "b", "c"], 1) returns b. 

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

    The field field1 contains whole list ["a", "b", "c"]. The field field2 contains b. field3 contains ["a", "c"].


    Example 67.189. Usage of remove - map

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

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

$out.0.value = aMap["a"]; // will be 1
$out.1.value = aMap["b"]; // will be null
$out.2.value = aMap["c"]; // will be 3


    See also:  append, insert, poll, push

    reverse

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

    The reverse() function reverses the order of elements of a given list and returns such new value of the list specified as the first argument.

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

    Compatibility

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

    Example 67.190. Usage of reverse

    The function reverse(["a", "b", "c"]) returns ["c", "b", "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 67.191. 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 67.192. 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