List Functions
- Kevin Wu
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 )
| Parameter | Description |
|---|---|
| The name of the list |
| 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 )
| Parameter | Description |
|---|---|
| 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 ... )
| Parameter | Description |
|---|---|
| The type of the elements comprising the list |
| 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 ... )
| Parameter | Description |
|---|---|
| The type of the elements comprising the list |
| 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
| Parameter | Description |
|---|---|
| The list to evaluate |
| 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 |
| Condition for matching an item in the list. |
| (Optional) index to start to search the list on. If |
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.
| Parameter | Description |
|---|---|
| A list |
| 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 )
| Parameter | Description |
|---|---|
| A list |
| Where to insert the new 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 )
| Parameter | Description |
|---|---|
| A list |
| Index of the value to remove. The index must be in the range |
Returns | Nothing |
listSet
Replaces an existing element in a list.
void listSet ( list<type> list, int index, type value )
| Parameter | Description |
|---|---|
| A list |
| The position of the element to be replaced |
| 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)
| Parameter | Description |
|---|---|
| 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
| Parameter | Description |
|---|---|
| A list |
| A list of UDRs |
| Name of the UDR field to sort on. This field may contain any primitive type except for |
| Sorting order (optional). Could be one of ascending (default) or descending. |
| 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
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 );