Array Operations
AppendItem()
This function adds an element at the end of an array and returns the modified array.
Return type: array
Parameter | Data Type | Description |
|---|---|---|
1 | Array | Underlying array |
2 | (variable) | Element to be attached |
Examples
AppendItem([1, 2], 3) returns [1,2,3].
AppendItem([], "A") and AppendItem( , "A") return ["A"].
AppendItem([1, 2], [3, 4]) returns [1,2,[3,4]], as the macro is not suitable for appending multiple single values.
Contains()
This function checks if an element is contained in an array.
Return type: Boolean
Parameter | Data Type | Description |
|---|---|---|
1 | Array | Array to be searched |
2 | (variable) | Value of the element to search for When comparing text values, case sensitivity is ignored. |
Examples
Contains(["A", "B"], "b") returns TRUE.
Contains([1, 2], "1") returns TRUE (works because the text representations of the values are implicitly compared).
Contains([2025-01-01, 2025-12-31], "2025-01-01") returns FALSE (does not work because the internal text representation of the date values has a different syntax).
ContainsAny()
This function checks if any element from an array of search values is contained in another array.
Return type: Boolean
Parameter | Data Type | Description |
|---|---|---|
1 | Array | Array to be searched |
2 | Array | Array of search values When comparing text values, case sensitivity is ignored. |
Examples
ContainsAny(["A", "B", "C"], ["c", "d"]) returns TRUE.
ContainsAny([1, 2, 3], [4, 5]) returns FALSE.
ContainsLike()
This function checks whether a text element matching a pre-defined pattern is contained in an array.
Return type: Boolean
Parameter | Data Type | Description |
|---|---|---|
1 | Array | Array of text values to be searched |
2 | Text | Wildcard expression of the search pattern, analogous to operator |
Examples
ContainsLike(["ABC", "DEF"], "a*") returns TRUE.
ContainsWhere()
This function checks if an element that fulfills a given condition is contained in another array.
Return type: Boolean
Parameter | Data Type | Description |
|---|---|---|
1 | Array | Array to be searched |
2 | Bool | Macro expression for checking the condition The macro expression is executed for the individual elements in the array and must return a Boolean value. The value to be checked and the position number of the respective element are addressed in this expression via the variables |
Examples
ContainsWhere(["ABC", "DEF", "GHI"], RegExIsMatch(@Value, "^g.*")) returns TRUE.
ContainsWhere(["ABC", "DEF", "GHI"], RegExIsMatch(@Value, "^g.*") & (@Index < = 2)) returns FALSE (because the RegEx match is at index number 3).
Distinct()
This function reduces all multiple elements in an array to one of each element.
Return type: array
Parameter | Data Type | Description |
|---|---|---|
1 | Array | Underlying array |
2 | Bool | Boolean value determining whether values with the same content and different capitalization will be considered identical when comparing text values Default value: |
Examples
Distinct(["A", "a", "A", "B"]) returns ["A", "B"].
Distinct(["A", "a", "A", "B"], FALSE) returns ["A", "a", "B"].
IsArray()
This function checks if a value is an array.
Return type: Boolean
Parameter | Data Type | Description |
|---|---|---|
1* | (variable) | Value to be checked |
Examples
IsArray([1, 2]) and IsArray([]) returns TRUE.
IsArray(1) returns FALSE.
GetItem()
This function reads the element from a given position in an array.
If the position does not exist, an empty string is returned (default data type). This is independent of the actual data type of the array values, because these values can vary, even within an array.
The return type varies.
Parameter | Data Type | Description |
|---|---|---|
1 | Array | Underlying array |
2 | Number | Postion of the element Counting starts at 1. Default value: |
Examples
GetItem([123, 456], 2) returns 456.
GetItem([123, 456], 3) returns "".
GetItemWhere(), GetItemsWhere()
These functions read the element or elements from an array that fulfill a given condition.
GetItemWhere() returns only the value of the first item found (return type varies) or an empty string if no item was found. GetItemsWhere() returns an array of all values found or an empty array if no item was found.
Parameter | Data Type | Description |
|---|---|---|
1 | Array | Array to be searched |
2 | Bool | Macro expression for checking the condition The macro expression is executed for the individual elements in the array and must return a Boolean value. The value to be checked and the position number of the respective element are addressed in this expression via the variables |
Examples
GetItemWhere(["ABC", "DEF", "GHI"], RegExIsMatch(@Value, "^(a|d).*")) returns "ABC".
GetItemsWhere(["ABC", "DEF", "GHI"], RegExIsMatch(@Value, "^(a|d).*")) returns ["ABC", "DEF"].
GetItemWhere(["RST", "UVW", "XYZ"], RegExIsMatch(@Value, "^(a|d).*")) returns "".
GetItemsWhere(["RST", "UVW", "XYZ"], RegExIsMatch(@Value, "^(a|d).*")) returns [].
GetLastItem()
This function reads the element from the last position in an array.
If the position does not exist, an empty string is returned.
The return type varies.
Parameter | Data Type | Description |
|---|---|---|
1 | Array | Underlying array |
Examples
GetLastItem([1, 2]) returns 2.
GetLastItem([]) returns "".
InsertItem()
This function adds an element at a given position in an array and returns the modified array.
Return type: array
Parameter | Data Type | Description |
|---|---|---|
1 | Array | Underlying array |
2 | (variable) | Element to be inserted |
3 | Number | Number of the position at which the element is to be inserted The current element at this position and all subsequent elements are moved back one position as a result. The maximum valid value is one counter above the current length of the array. If the position specification is below or above the valid value range, the element is inserted at the beginning of the array or appended to the end. Counting starts at 1. Default value: |
Examples
InsertItem(["A", "B"], "C") returns ["C", "A", "B"].
InsertItem(["A", "B"], "C", 999) returns ["A", "B", "C"].
ItemCount()
This function returns the number of elements in an array.
Return type: number
Parameter | Data Type | Description |
|---|---|---|
1 | Array | Underlying array |
Examples
ItemCount(["A", "B"]) returns 2.
ItemCountWhere()
This function returns the number of elements in an array that fulfill a given condition.
Return type: number
Parameter | Data Type | Description |
|---|---|---|
1 | Array | Array to be searched |
2 | Bool | Macro expression for checking the condition The macro expression is executed for the individual elements in the array and must return a Boolean value. The value to be checked and the position number of the respective element are addressed in this expression via the variables |
Examples
ItemCountWhere(["ABC", "DEF", "GHI"], RegExIsMatch(@Value, "^(a|d).*")) returns 2.
ItemCountWhere(["ABC", "DEF", "GHI"], RegExIsMatch(@Value, "^(a|d).*") & (@Index & gt;= 2)) returns 1 (as the first RegEx hit is at index number 1).
ItemNo()
This function returns the position number of the first element in an array that has a given value. Counting starts at 1.
If the element is not included, the function will return the value 0.
Return type: number
Parameter | Data Type | Description |
|---|---|---|
1 | Array | Underlying array |
2 | (variable) | Value of element searched for In the search for text values, case sensitivity is ignored. |
Examples
ItemNo(["A", "B"], "b") returns 2.
ItemNo(["A", "B"], "c") returns 0.
ItemNo([1, 2], "1") returns 1 (works because the text representations of the values are implicitly compared).
ItemNoWhere()
This function returns the position number of the first element in an array that fulfills a given condition. Counting starts at 1.
If the element is not included, the function will return the value 0.
Return type: number
Parameter | Data Type | Description |
|---|---|---|
1 | Array | Array to be searched |
2 | Bool | Macro expression for checking the condition The macro expression is executed for the individual elements in the array and must return a Boolean value. The value to be checked and the position number of the respective element are addressed in this expression via the variables |
Examples
ItemNoWhere(["ABC", "DEF"], RegExIsMatch(@Value, "^a.*")) returns 1.
RemoveItem()
This function removes an element with a defined value from an array and returns the modified array.
Parameter | Data Type | Description |
|---|---|---|
1 | Array | Underlying array |
2 | (variable) | Value of element to be removed In the search for text values, case sensitivity is ignored. |
Examples
RemoveItem(["A", "a", "B"], "A") returns ["B"].
RemoveItemAt()
This function removes an element at a defined position from an array and returns the modified array.
Parameter | Data Type | Description |
|---|---|---|
1 | Array | Underlying array |
2 | Number | Number of array element to be removed Counting starts at 1. |
Examples
RemoveItemAt(["A", "B", "C"], 2) returns ["A", "C"].
RemoveItemAt(["A", "B", "C"], 4) returns ["A", "B", "C"] (item number not found).
ReplaceItemWhere(), ReplaceItemsWhere()
These functions replace the first or all elements in an array that fulfill a given condition with the same replacement value and return the modified array.
Parameter | Data Type | Description |
|---|---|---|
1 | Array | Array to be searched |
2 | Bool | Macro expression for checking the condition The macro expression is executed for the individual elements in the array and must return a Boolean value. The value to be checked and the position number of the respective element are addressed in this expression via the variables |
Examples
RemoveItemWhere(["ABC", "DEF"], RegExIsMatch(@Value, "^(a|d).*")) returns ["DEF"].
RemoveItemsWhere(["ABC", "DEF"], RegExIsMatch(@Value, "^(a|d).*")) returns [].
ReplaceItem()
In an array, this function replaces an element that has a defined value with another element. Then it returns the modified array.
Parameter | Data Type | Description |
|---|---|---|
1 | Array | Underlying array |
2 | (variable) | The value of the element to be replaced When searching for text values, upper/lower case is ignored. If multiple elements of the searched value are found, all elements will be replaced with the same replacement value. |
3 | (variable) | Replacement value |
Examples
ReplaceItem(["A", "a", "B"], "A", "C") returns ["C", "C", "B"].
ReplaceItemAt()
In an array, this function replaces an element that has a defined position with another element. Then it returns the modified array.
Parameter | Data Type | Description |
|---|---|---|
1 | Array | Underlying array |
2 | Number | Number of array element to be replaced Counting starts at 1. |
3 | (variable) | Replacement value |
Examples
ReplaceItemAt(["A", "B", "C"], 2, "D") returns ["A", "D", "C"].
ReplaceItemAt(["A", "B", "C"], 4, "D") returns ["A", "B", "C"] (item number not found).
ReplaceItemWhere(), ReplaceItemsWhere()
These functions replace the first or all elements in an array that fulfill a given condition with the same replacement value and return the modified array.
Parameter | Data Type | Description |
|---|---|---|
1 | Array | Array to be searched |
2 | Bool | Macro expression for checking the condition The macro expression is executed for the individual elements in the array and must return a Boolean value. The value to be checked and the position number of the respective element are addressed in this expression via the variables |
3 | (variable) | Replacement value |
Examples
ReplaceItemWhere(["ABC", "DEF", "GHI"], RegExIsMatch(@Value, "^(a|d).*"), "XXX") returns ["XXX", "DEF", "GHI"].
ReplaceItemsWhere(["ABC", "DEF"], RegExIsMatch(@Value, "^(a|d).*"), "XXX") returns ["XXX", "XXX", "GHI"].
Sort()
This function sorts the elements in an array in ascending order.
Return type: array
Parameter | Data Type | Description |
|---|---|---|
1 | Array | Underlying array |
2 | Bool | Boolean value determining whether values with the same content and different capitalization will be considered identical when comparing text values Default value: |
Examples
Sort([3, 1, 2]) returns [1,2,3].
Sort(["C", "A", "B", "b"]) returns ["A", "B", "b", "C"].
Sort(["C", "A", "B", "b"], FALSE) returns ["A", "b", "B", "C"].
ToArray()
This function generates an array with a corresponding number of elements from a scalar value of any type or a string of delimited text values.
If the input value is an array, a nested array will be created. The IsArray field macro can be used to check in advance whether the input value is an array.
Return type: array
Parameter | Data Type | Description |
|---|---|---|
1 | (variable) | Scalar values or delimited value list |
2 | Text | Delimiter used in the value list Default value: |
Examples
ToArray(1) returns [1].
ToArray("A,B,C", ",") returns ["A", "B", "C"].
ToArray() returns [].