Home | Table of Contents | Container Functions | CloverETL 4.6.1
--- | --- | ---
Prev | Functions Reference | Next

## Container Functions

###### List of functions

append | isEmpty
binarySearch | length
clear | poll
containsAll | pop
containsKey | push
containsValue | remove
copy | reverse
getKeys | sort
getValues | toMap
insert |

When working with containers (`list`, `map`, `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`:

Code | Working?
--- | ---
    'abc'.in(['a', 'b'])
    in(10, [10, 20])
    10.in([10, 20])

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

Code | Comment
--- | ---
    in('abc', $in.0.listField)
| operator syntax for list field
    in('abc', $in.0.mapField)
| operator syntax for map field, searching for key of map entry

| 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 functions `containsKey()` and `containsValue()` 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 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.

Example 61.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.

Example 61.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.

Example 61.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 61.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.

Example 61.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.

Example 61.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.

Example 61.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>[] arg, <element type>[] arg`)`;

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.

Example 61.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 contain values `["a", "b", "c", "d"]`.

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

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.

Example 61.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 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 error.

Example 61.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 notice: The function `getValues()` is available since CloverETL 4.0.0.

Example 61.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 `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 element to insert must be of the same data type. Remember that the list element are indexed starting from 0.

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

Example 61.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 error.

Example 61.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 th function returns `false`.

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

Example 61.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`.

Example 61.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 error.

Example 61.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 error.

Example 61.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 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 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 error.

Example 61.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`)`;

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

Example 61.188. Usage of remove

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

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

Example 61.189. 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 error.

Example 61.190. 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 list of `keys` and lists of `values` to the map. The function `toMap(k[], v)` converts 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 map having `null` for all keys.

Compatibility notice: The function `toMap()` has been introduced in CloverETL 4.0.0.

Example 61.191. 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 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 list of keys (`abcKeys`) and 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. List of the 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, therefor 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

Prev | Up | Next
Mapping Functions | Home | Table of Contents | Record Functions (dynamic field access)