List Variables
List variables are one-dimensional matrices, or arrays. They contain elements which can be addressed sequentially (for example, by using the For-Each function), or directly (by referencing the index number).
You can create list variables of simple or complex elements.
For instructions on how to create a list variable, see here.
Example Projects
Two example projects are provided. Each method listed below is demonstrated by a single workflow named with the method name. The documentation of the examples below indicates in which project each method is demonstrated.
To download and open the example projects:
Properties
Property |
Type |
Description |
Can Be Modified |
---|---|---|---|
Is Empty |
Boolean |
Indicates if the list is empty or not. Returns True if empty. |
No |
Number of Elements | Number | The number of elements in the list. | No |
Methods
Adds the specified element to the end of the list.
Parameters
Parameter |
Input Type |
Description |
---|---|---|
value |
(according to the list type) |
The element to add to the end of the list. |
Returns
Nothing. The value is added to the existing list.
Example
(The workflow for this example is included in Example Project 1.)
This example adds the following text elements to the list variable Class_A: Alice, Charlie, Bob; and the following text elements to the list variable Class_B: Charlie, Alice, David.
When the workflow is run, Class_A contains the elements Alice, Charlie, and Bob, and Class_B contains the elements Charlie, Alice, and David.
Appends the elements of the specified list to the current list and outputs the combined list.
Parameters
Parameter |
Input Type |
Description |
---|---|---|
list |
List |
The second list whose elements must be added to the current list. |
Returns
Returns a list composed of the elements of the original list and the appended list.
Example
(The workflow for this example is included in Example Project 1.)
This workflow first populates the list variables Class_A and Class_B (see the example for Add Element at End).
Those two lists are then populated as follows:
The workflow then appends Class_B to the end of Class_A. It assigns the result to the list variable Class_C.
When the workflow is run, Class_C contains six elements: Alice, Charlie, Bob, Charlie, Alice, David. Class_A and Class_B are unchanged.
Creates a list combining all elements from the current list with the elements of the specified list, with no repetitions. (If the specified list includes an element with the same property values as an element in the current list, even though the elements are populated with different objects, only the element from the current list will be included.)
Parameters
Parameter |
Input Type |
Description |
---|---|---|
list |
List |
The second list whose elements must be combined with the current list. |
Returns
Returns the list of combined elements.
Example
(The workflow for this example is included in Example Project 2.)
This workflow first populates the lists Customers_A and Customers_B with the complex variables listed below.
Customers_A:
Variable |
First name |
last name |
customer ID |
---|---|---|---|
c1 |
John |
Smith |
1 |
c2 | Mary | Black | 2 |
c5 | Daniel | Gray | 5 |
Customers_B:
Variable |
First name |
last name |
customer ID |
---|---|---|---|
c3 |
Charles |
Peters |
3 |
c4 | Mary | Black | 2 |
c1 | John | Smith | 1 |
Note:
-
The same object c1 exists in both lists.
-
Variable c2 in Customers_A and variable c4 in Customers_B are different objects with identical values.
The workflow then combines all elements in Customers_A with the elements in Customers_B and assigns the result to the list variable Customers_C.
When the workflow is run, Customers_C contains four elements:
Note:
-
All elements from both lists are included.
-
John Smith (represented by c1) is included only once.
-
Mary Black (represented by both c2 and c4) is included only once.
Creates a list combining the identical elements in both the current and the specified lists, by comparing the property values or the actual objects.
Parameters
Parameter |
Input Type |
Description |
---|---|---|
list |
List |
The second list whose elements must be combined with the current list. |
by value |
Boolean |
Whether to compare the elements in both lists by value (True) or by object (False). |
Returns
Returns the list of identical elements.
Example
(The workflow for this example is included in Example Project 2.)
This workflow first populates the lists Customers_A and Customers_B with complex variables (see example for Combine All Elements).
Those two lists are then populated as follows:
Variable |
First name |
last name |
customer ID |
---|---|---|---|
c1 |
John |
Smith |
1 |
c2 | Mary | Black | 2 |
c5 | Daniel | Gray | 5 |
Variable |
First name |
last name |
customer ID |
---|---|---|---|
c3 |
Charles |
Peters |
3 |
c4 | Mary | Black | 2 |
c1 | John | Smith | 1 |
It then:
-
Combines the identical elements in the two lists with the parameter by value set to True and assigns the result to the list Customers_C.
-
Combines the identical elements in the two lists with the parameter by value set to False and assigns the result to Customers_D.
When the workflow is run, Customers_C contains two elements: John Smith (the identical object from both lists) and Mary Black (two different objects with identical values). Customers_D contains only element: John Smith (the identical object from both lists) .
Creates a list combining all elements in both the current and the specified lists with no repetitions, by comparing the property values or the actual objects.
Parameters
Parameter |
Input Type |
Description |
---|---|---|
list |
List |
The second list whose elements must be combined with the current list. |
by value |
Boolean |
Whether to compare the elements of both lists by value (True) or by the actual objects (False). |
Returns
Returns the list of combined elements.
Example
(The workflow for this example is included in Example Project 2.)
This workflow first populates the lists Customers_A and Customers_B with complex variables (see example for Combine All Elements).
Those two lists are then populated as follows:
Variable |
First name |
last name |
customer ID |
---|---|---|---|
c1 |
John |
Smith |
1 |
c2 | Mary | Black | 2 |
c5 | Daniel | Gray | 5 |
Variable |
First name |
last name |
customer ID |
---|---|---|---|
c3 |
Charles |
Peters |
3 |
c4 | Mary | Black | 2 |
c1 | John | Smith | 1 |
It then:
-
Combines the elements in the two lists with the parameter by value set to True and assigns the result to the list Customers_C.
-
Combines the elements in the two lists with the parameter by value set to False and assigns the result to Customers_D.
When the workflow is run, Customers_C contains four elements:
Note:
-
All elements from both lists are included.
-
John Smith is included only once.
-
Mary Black is included only once.
Customers_D contains five elements:
Note:
-
All elements from both lists are included.
-
John Smith is included only once.
-
Mary Black is included twice, as the two objects containing Mary Black were not compared by value.
Creates a list containing the elements from the current and specified lists which are not shared by both lists, by comparing the property values.
Parameters
Parameter |
Input Type |
Description |
---|---|---|
list |
List |
The second list whose unique elements must be combined with the unique elements in the current list. |
Returns
Returns a list that includes the combined elements.
Example
(The workflow for this example is included in Example Project 2.)
This workflow first populates the lists Customers_A and Customers_B with complex variables (see example for Combine All Elements).
Those two lists are then populated as follows:
Variable |
First name |
last name |
customer ID |
---|---|---|---|
c1 |
John |
Smith |
1 |
c2 | Mary | Black | 2 |
c5 | Daniel | Gray | 5 |
Variable |
First name |
last name |
customer ID |
---|---|---|---|
c3 |
Charles |
Peters |
3 |
c4 | Mary | Black | 2 |
c1 | John | Smith | 1 |
It then combines the elements not shared by both lists and assigns the result to the list Customers_C.
When the workflow is run, Customers_C contains two elements:
Note:
-
Mary Black is not included as a not shared element because the items in the lists are compared by their values, and not by the actual objects.
Creates a list containing the elements from the current and specified lists which are shared by both lists. Elements are considered shared if they are the same object or if they share identical values.
Parameters
Parameter |
Input Type |
Description |
---|---|---|
list |
List |
The second list whose elements must be combined with the elements in the current list. |
Returns
Returns a list of the combined elements.
Example
(The workflow for this example is included in Example Project 2.)
This workflow first populates the lists Customers_A and Customers_B with complex variables (see example for Combine All Elements).
Those two lists are then populated as follows:
Variable |
First name |
last name |
customer ID |
---|---|---|---|
c1 |
John |
Smith |
1 |
c2 | Mary | Black | 2 |
c5 | Daniel | Gray | 5 |
Variable |
First name |
last name |
customer ID |
---|---|---|---|
c3 |
Charles |
Peters |
3 |
c4 | Mary | Black | 2 |
c1 | John | Smith | 1 |
It then combines the shared elements of the two lists and assigns the result to the list Customers_C.
When the workflow is run, Customers_C contains two elements:
Note:
-
The identical object John Smith appears in both lists. Mary Black appears in a different object in each list, but these two objects share identical values and therefore are considered a shared element between the two lists.
Creates a list containing the elements from the current and specified lists which are not shared by both lists, by comparing the actual objects or the property values.
Parameters
Parameter |
Input Type |
Description |
---|---|---|
list |
List |
The second list whose unique elements must be combined with the unique elements in the current list. |
by value |
Boolean |
Whether to compare the elements of the two lists by values (True) or not (False). |
Returns
Returns a list of the combined elements.
Example
(The workflow for this example is included in Example Project 2.)
This workflow first populates the lists Customers_A and Customers_B with complex variables (see example for Combine All Elements).
Those two lists are then populated as follows:
Variable |
First name |
last name |
customer ID |
---|---|---|---|
c1 |
John |
Smith |
1 |
c2 | Mary | Black | 2 |
c5 | Daniel | Gray | 5 |
Variable |
First name |
last name |
customer ID |
---|---|---|---|
c3 |
Charles |
Peters |
3 |
c4 | Mary | Black | 2 |
c1 | John | Smith | 1 |
It then:
-
Combines the unique elements of the two lists with the parameter by value set to True and assigns the result to the list Customers_C.
-
Combines the unique elements of the two lists with the parameter by value set to False and assigns the result to the list Customers_D.
When the workflow is run, Customers_C contains two elements:
Note:
-
Mary Black is not included as a not shared element because the items in the lists are compared by their values, and not by the actual objects.
Customers_D contains four elements:
Note:
-
Mary Black is included twice (once from each list) because the elements here are compared by the actual objects, and each Mary Black is a different object.
Finds the position of the specified element in the list.
Parameters
Parameter |
Input Type |
Description |
---|---|---|
value |
(according to the list type) |
The element to find in the list. |
Returns
Returns the position of the element as a number (1-based). If the element is not found, 0 is returned.
Example
(The workflow for this example is included in Example Project 1.)
This workflow first populates the list variables Class_A and Class_B (see the example for Add Element at End).
Those two lists are then populated as follows:
The workflow then finds the position of the value Charlie. It stores the result in the variable number_out.
When the workflow is run, Class_A contains the elements Alice, Charlie, and Bob, and number_out contains the number 2, indicating that Charlie is the second element in Class_A.
Finds the position of the specified element in the list, by value or by comparing objects.
Parameters
Parameter |
Input Type |
Description |
---|---|---|
variable |
(according to the list type) |
The element whose position to find. |
by value |
Boolean |
Whether to search for the element by value (True) or by actual object (False). |
Returns
Returns the position of the element as a number (1-based). If the variable is not found, 0 is returned.
Example
(The workflow for this example is included in Example Project 2.)
This workflow first populates the lists Customers_A and Customers_B with complex variables (see example for Combine All Elements).
Those two lists are then populated as follows:
Variable |
First name |
last name |
customer ID |
---|---|---|---|
c1 |
John |
Smith |
1 |
c2 | Mary | Black | 2 |
c5 | Daniel | Gray | 5 |
Variable |
First name |
last name |
customer ID |
---|---|---|---|
c3 |
Charles |
Peters |
3 |
c4 | Mary | Black | 2 |
c1 | John | Smith | 1 |
It then:
-
Finds the position of the variable c4 with the parameter by value set to True and assigns the result to the variable number_out.
-
Finds the position of the variable c4 with the parameter by value set to False and assigns the result to the variable number_out_2.
Note:
-
Variables c2 and c4 are different objects that are identical in value (each contains a customer named Mary Black). Variable c2 is included in the list Customers_A.
When the workflow is run, the variable number_out is set to 2, indicating that an element with values matching those of c4 is in the second position of Customers_A. The variable number_out_2 is set to 0, indicating that the object c4is not found in Customers_A.
Retrieves the value of the element at the specified position in the list.
Parameters
Parameter |
Input Type |
Description |
---|---|---|
position |
Number |
The position of the element (1-based). |
Returns
The value of the element at the specified position. The type of value returned depends on the list type.
Example
(The workflow for this example is included in Example Project 1.)
This workflow first populates the list variables Class_A and Class_B (see the example for Add Element at End).
Those two lists are then populated as follows:
The workflow then returns the value of the element at the third position. It stores the result in the variable text_out.
When the workflow is run, Class_A contains the elements Alice, Charlie, and Bob, and text_out contains the text Bob, indicating that the third element in Class_A is Bob.
Inserts the specified element into the list at the specified position.
Parameters
Parameter |
Input Type |
Description |
---|---|---|
value |
(according to the list type) |
The element to insert. |
position |
Number |
The position at which to insert the element (1- based). |
Returns
Nothing. The element is added to the existing list.
Example
(The workflow for this example is included in Example Project 1.)
This workflow first populates the list variables Class_A and Class_B (see the example for Add Element at End).
Those two lists are then populated as follows:
The workflow then inserts the element Edward at the first position.
When the workflow is run, Class_A contains four elements: Edward, Alice, Charlie, and Bob.
Filters the elements of the list so that no elements are repeated and generates an output of the resulting set. The elements are compared to one another by their property values: if two different objects have identical values, they are considered identical, and one object will be filtered out and removed.
Parameters
None.
Returns
Returns the filtered elements as a list.
Example
(The workflow for this example is included in Example Project 2.)
This workflow first populates the list Customers_D with the complex variables below:
Variable |
First name |
last name |
customer ID |
---|---|---|---|
c1 |
John |
Smith |
1 |
c2 | Mary | Black | 2 |
c3 |
Charles |
Peters |
3 |
c4 | Mary | Black | 2 |
c1 |
John |
Smith |
1 |
Note:
-
Variable c1 (John Smith) is included in the list twice.
-
Variables c2 and c4 have identical values (Mary Black).
The workflow then makes a set from Customers_D and assigns the result to the variable Customers_C.
When the workflow is run, Customers_C contains three elements:
Note:
-
John Smith appears once (the duplicate object was removed).
-
Mary Black appears once (different object with duplicate values was removed).
Filters the elements of the list so that no elements are repeated, and generates an output of the resulting set. The elements are compared to one another either by their property values or by the actual objects, and any duplicates are filtered out and removed.
Parameters
Parameter |
Input Type |
Description |
---|---|---|
by value |
Boolean |
Whether to compare the elements within the list by value (True) or by actual objects (False). |
Returns
Returns the filtered elements as a list.
Example
(The workflow for this example is included in Example Project 2.)
This workflow first populates the list Customers_D with the complex variables below:
Variable |
First name |
last name |
customer ID |
---|---|---|---|
c1 |
John |
Smith |
1 |
c2 | Mary | Black | 2 |
c3 |
Charles |
Peters |
3 |
c4 | Mary | Black | 2 |
c1 |
John |
Smith |
1 |
Note:
-
Variable c1 (John Smith) is included in the list twice.
-
Variables c2 and c4 have identical values (Mary Black).
The workflow then:
-
Makes a set from Customers_D with the parameter by value set to True and assigns the result to the variable Customers_C.
-
Makes a set from Customers_D with the parameter by value set to False and assigns the result to the variable Customers_E.
When the workflow is run, Customers_C contains three elements:
Note:
-
John Smith appears once (duplicate object was removed).
-
Mary Black appears once (different object with identical values was removed).
Customers_E contains four elements:
Note:
-
John Smith appears once (duplicate object was removed).
-
Mary Black appears twice (different objects with identical values are not considered duplicates and are not removed).
Removes all elements from the list.
Parameters
None.
Returns
Nothing. The elements are removed from the existing list.
Example
This workflow first populates the list variables Class_A and Class_B (see the example for Add Element at End).
Those two lists are then populated as follows:
The workflow then removes all elements from Class_A.
When the workflow is run, Class_A contains no elements.
Removes the specified element from the list.
Parameters
Parameter |
Input Type |
Description |
---|---|---|
value |
(according to the list type) |
The element to remove from the list. |
Returns
Nothing. The element is removed from the existing list.
Example
(The workflow for this example is included in Example Project 1.)
This workflow first populates the list variables Class_A and Class_B (see the example for Add Element at End).
Those two lists are then populated as follows:
The workflow then removes the element Bob from Class_A.
When the workflow is run, Class_A no longer contains the element Bob.
Removes an element at the specified position in the list.
Parameters
Parameter |
Input Type |
Description |
---|---|---|
position |
Number |
The position of the element to remove (1-based). |
Returns
Nothing. The element is removed from the existing list.
Example
(The workflow for this example is included in Example Project 1.)
This workflow first populates the list variables Class_A and Class_B (see the example for Add Element at End).
Those two lists are then populated as follows:
The workflow then removes the first element from Class_A.
When the workflow is run, Class_A no longer contains the element Alice, which was the first element in the list.
Removes a range of elements from the list, starting and ending at specified positions.
Parameters
Parameter |
Input Type |
Description |
---|---|---|
start position |
Number |
Starting position of the range of elements to remove (1-based, inclusive). |
end position |
Number |
End position of the range of elements to remove (1-based, inclusive). |
Returns
Nothing. The elements are removed from the existing list.
Example
(The workflow for this example is included in Example Project 1.)
This workflow first populates the list variables Class_A and Class_B, appends Class_B to the end of Class_A, and assigns the result to the list variable Class_C (see the example for Append List).
Class_C now contains six elements: Alice, Charlie, Bob, Charlie, Alice, David.
The workflow then removes the elements from the second to the fifth position.
When the workflow is run, Class_C no longer contains the elements Charlie, Bob, Charlie, and Alice, which were in the second through fifth positions in the list.
Replaces the value at the specified position of a list with a new value.
Parameters
Parameter |
Input Type |
Description |
---|---|---|
position |
Number |
The position of the element (1-based). |
value |
(according to the list type) |
The new value. |
Returns
Nothing. The value is replaced in the existing list.
Example
(The workflow for this example is included in Example Project 1.)
This workflow first populates the list variables Class_A and Class_B (see the example for Add Element at End).
Those two lists are then populated as follows:
The workflow then replaces the value at the second position of Class_A with Penelope.
When the workflow is run, the second element of Class_A is Penelope.
Sorts the elements of the list according to a specified property.
Parameters
Parameter |
Input Type |
Description |
---|---|---|
propertyName |
Text |
Name of the property. |
ascending |
Boolean |
Whether to sort the elements of the list in ascending order. |
Returns
Nothing. The elements are sorted in the existing list.
Example
Sorts the elements of the list in ascending or descending order. Text elements are sorted in alphabetical order, and numbers are sorted by magnitude.
Parameters
Parameter |
Input Type |
Description |
---|---|---|
ascending |
Boolean |
Whether to sort the elements in ascending order. |
Returns
Nothing. The elements are sorted in the existing list.
Example
(The workflow for this example is included in Example Project 1.)
This workflow first populates the list variables Class_A and Class_B (see the example for Add Element at End) so that Class_A contains three elements: Alice, Charlie, and Bob. It then sorts Class_A in ascending order.
When the workflow is run, the elements of Class_A are sorted in ascending alphabetical order: Alice, Bob, Charlie.