Container Functions

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

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

```
myBool = myString.in(myList)
					
```
```
myBool = in(myString,myList);
				  
```
```
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

	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.

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)