List Functions

This section describes functions that are used to manage lists and their elements. Lists can be created to hold any type of data.

The following functions for List described here are:

listAdd

Adds a new element to the end of an existing list.

void listAdd 
 ( list<type> list, 
 any value )
ParameterDescription

list

The name of the list

value

Value to add to the list. The value must be of the same type as the list is designed to accept.

Returns

Nothing

Example - Using listAdd

The following code leaves a list consisting of the two elements 7 and 5.

list <int> myIntList = listCreate(int, 7); 
 listAdd(myIntList, 5);

listClear

Removes all elements from a list.

void listClear 
( list<type> list )
ParameterDescription

list

The list of elements to be removed

Returns

Nothing

listCreate

Creates a list of any type, and (optionally) populates it.

list<type> listCreate 
 ( type, 
 element1, //Optional 
 element2, //Optional 
 ... )
ParameterDescription

type

The type of the elements comprising the list

element<n>

The value of an element to be added to the list. Optional parameters: if none is entered, the list will be empty.

Returns

The list

listCreateSync

Creates a synchronized list of any type, and (optionally) populates it. This function may be useful for global lists in real time workflows, where the same list may be accessed from several threads at the same time.

list<type> listCreateSync 
( type, 
element1, //Optional 
element2, //Optional 
... )
ParameterDescription

type

The type of the elements comprising the list

element<n>

The value of an element to be added to the list. Optional parameters: if none is entered, the list will be empty.

Returns

The list

listFindIndex

Calculates the index of a requested list element.
The condition is tried for each element in the list until there is a match or the end of the list is reached.

int listFindIndex 
 ( list<type> list, 
 varSpec, 
 Condition, 
 int startIndex ) //Optional
ParameterDescription

list

The list to evaluate

varSpec

Variable specification. Defines a variable to hold the list data for the condition evaluation. Can be either a valid variable name in which case the variable type is the same as the list element type, or a type can be explicitly set on the variable in which case the list elements are cast to this type and then assigned to the variable. An incorrect type will cause a runtime ClassCastException.

Condition

Condition for matching an item in the list.

startIndex

(Optional) index to start to search the list on. If startIndex is not specified, the list is searched from the beginning.

Returns

The index of the first matching element. If no element matched the condition, -1 is returned. The first element in the list is indexed 0 (zero).

Example - Using listFindIndex

A list of integers containing the following elements [50, 2, 4, 152, 4] is searched for an element equal to 4:

debug( listFindIndex( myList, i, i == 4 ) );

The output is 2, since it is the index number of the first element equal to 4 in the list.

listGet

Retrieves an element from a given position in the list.

any listGet
 ( list<type> list, 
 int index)

The index must be in the range 0<=index<listSize(list) or the workflow will abort with a runtime error.

ParameterDescription

list

A list

index

Index of the element to retrieve

Returns

The value given at the defined index

listInsert

Inserts a value on a given position in a list. Note that this will NOT overwrite any existing values on the position, but only move the old element up a position.

void listInsert 
 ( list<type> list, 
 int index, 
 type value )
ParameterDescription

list

A list

index

Where to insert the new value

value

The new value

Returns

Nothing

Example - Using listInsert

A list consists of the following elements: [2, 5, 72, 19] and the new value 127 is to be inserted on index position 2. This means the new indexes for the elements containing 72 and 19 are now 3 and 4 respectively:

listInsert( mylist, 2, 127);

myList now looks like this: [2, 5, 127, 72, 19]

listRemove

Removes an element from a list.

void listRemove 
 ( list<type> list, 
 int index )
ParameterDescription

list

A list

index

Index of the value to remove. The index must be in the range 0<=index<listSize ( list ) or the workflow will abort with a runtime error.

Returns

Nothing

listSet

Replaces an existing element in a list.

void listSet
 ( list<type> list, 
 int index,
 type value )
ParameterDescription

list

A list

index

The position of the element to be replaced

value

The new value to replace the existing with

Returns

Nothing

Example - Using listSet

A list consists of the following elements: [2, 5, 72, 19] and the new value 127 should replace the value of the element on index position 2:

listSet( mylist, 2, 127);

myList now looks like this: [2, 5, 127, 19]

listSize

Gets the size of a list.

int listSize ( list<type> list)
ParameterDescription

list

A list

Returns

The number of elements in the list

listSort

Sorts a list of any type. For UDR lists, sorting is based on a field in the UDR.

For all lists except for UDR lists:

void listSort
 ( list<type> list, 
 order ) //Optional

For UDR lists:

void listSort
 ( list<UDRtype> UDRlist, 
 string field,
 order, //Optional
 udrtype ) //Optional
ParameterDescription

list

A list

UDRlist

A list of UDRs

field

Name of the UDR field to sort on. This field may contain any primitive type except for any , bitset and ipaddress .

order

Sorting order (optional). Could be one of ascending (default) or descending.

udrtype

Parameter to determine UDR type if the list is declared to hold generic UDRs. In the following bullets, the first is generic and must have the udrtype specified. The second does not require the udrtype since the UDR type is known from the declaration.

  1. list<drudr> MyList;

  2. list<MyUDRType> MyList;

If a type name is used and the UDR cannot be converted to this type this will be a runtime error.

Returns

Nothing

Example - Using listSort

list<MyUDRType> myList;
// Assume we have added items to the list
listSort( myList, SequenceNumber, descending );