This article is for Data Center. Visit Cloud
Array Functions
ALL
ALL(A, $)
Checks that $ returns a truthy value for all elements in the array.
Parameter | Type | Description |
---|---|---|
|
| Array of elements to be used in $. |
$ | User Function | Function to be applied to each element. |
→ Result | Boolean | Returns true if $ returns a truthy value for all elements in the array. Otherwise, returns false. If the array is empty, returns true. |
Examples:
ALL(fi
xVersions, $.startDate > TODAY())→
Returns true if all fixVersions start after the current date.
ANY
ANY(A, $)
Checks if the array has at least one element for which $ returns true.
Parameter | Type | Description |
---|---|---|
|
| Array of elements to be used in $. |
$ | User Function | Function to be applied to each element. |
→ Result | Boolean | Returns true if $ returns a truthy value for at least one elements in the array. Otherwise, returns false. If the array is empty, returns false. |
Examples:
ANY(fixVersions, $.startDate < TODAY())
Returns true if any fixVersions started before the current date.→
ARRAY
ARRAY(Element1, Element2, ..., ElementN)
Creates an array from a list of elements.
Parameter | Type | Description |
---|---|---|
|
| Elements to be added to the array. |
→ Result | Array | Array containing all of the elements. |
Example:
ARRAY(1, 2, 3) → ARRAY(1, 2, 3)
COMPACT
COMPACT(A)
Removes all undefined values from the array.
Parameter | Type | Description |
---|---|---|
|
| Array to be compacted. |
→ Result | Array | Compacted array. |
Note: error values and empty arrays are preserved.
Examples:
COMPACT(ARRAY(1, 2, undefined, 3)) → ARRAY(1, 2, 3)
CONTAINS
CONTAINS(A, Element)
Searches an array for a specified element. The comparison is done in the same way function EQ (=) works.
Parameter | Type | Description |
---|---|---|
|
| Array to search in. |
Element | Any | Element to look for. |
→ Result | Boolean | Returns true if the array contains the specified element. Otherwise, returns false. |
Examples:
CONTAINS(ARRAY(1, 2, 3), 2) → 1
CONTAINS(ARRAY(1, 2, 3), 5) → 0
fixVersions.CONTAINS("v1") →
returns 1 if one of the versions in the Fix Version/s field is "v1"
Please note that CONTAINS
does not perform text matching.For example, if Fix Version/s field contains version "v1.1", the above example – fixVersion.CONTAINS("v1")
– will return 0. You can apply text matching to look for elements that match a particular pattern, for example: fixVersion.ANY($.MATCH("v1*"))
CONTAINS_ALL
CONTAINS_ALL(A, Elements_Array)
Searches an array for all of the elements passed in the Elements_Array parameter.
Parameter | Type | Description |
---|---|---|
|
| Array to search in. |
Elements_Array | Array | Array of elements to look for. |
→ Result | Boolean | Returns true (1) if |
Duplicates are not taken into account, so CONTAINS_ALL(ARRAY(1), ARRAY(1,1)) → 1
.
Examples:
CONTAINS_ALL(ARRAY(1, 2, 3), ARRAY(1, 2, 3)) → 1
CONTAINS_ALL(ARRAY(1, 2, 3), ARRAY(1, 2, 4)) → 0
CONTAINS_ANY
CONTAINS_ANY(A, Elements_Array)
Searches an array for any of the elements passed in the Elements_Array parameter.
Parameter | Type | Description |
---|---|---|
|
| Array to search in. |
Elements_Array | Array | Array of elements to look for. |
→ Result | Boolean | Returns true (1) if |
Examples:
CONTAINS_ANY(ARRAY(1, 2, 3), ARRAY(2, 9, 7)) → 1
CONTAINS_ANY(ARRAY(1, 2, 3), ARRAY(4, 9, 7)) → 0
FILTER
FILTER(A, $)
Filters the values in an array and produces a new array that retains only elements for which the user function $ returns a true value (considered as a Boolean).
Parameter | Type | Description |
---|---|---|
|
| Array of elements to be filtered. |
$ | User Function | Function to be applied to each element. |
→ Result | Array | New filtered array. |
Example:
ARRAY(100, 200, 300).FILTER(x -> x < 250) → ARRAY(100, 200)
worklogs.FILTER($.author = ME())
→ Returns an array containing worklog values created by the current user
FIRST
FIRST(A)
Returns first element of the array, or undefined if the array is empty.
Parameter | Type | Description |
---|---|---|
|
| Array of elements. |
→ Result | Any | First element contained in the array. If empty, returns undefined. |
Example:
FIRST(ARRAY(1, 2,3)) → 1
FLATTEN
FLATTEN(A)
Given an array of arrays, makes a single array, using one-step flattening (each element in the sub-arrays is added to the top array as a single element).
Parameter | Type | Description |
---|---|---|
|
| Array of arrays, or array containing arrays and non-array values. |
→ Result | Array | A single array, containing all elements. |
Example:
FLATTEN(ARRAY(ARRAY(1, 2), 100, ARRAY(2, 3), 10)) → ARRAY(1, 2, 100, 2, 3, 10)
GET
GET(A, Index)
Retrieves an element from an array based on its index. Array indexes are 0-based. Returns undefined if index is out of array bounds.
Parameter | Type | Description |
---|---|---|
|
| Array to search. |
Index | Integer | Numeric index, 0-based: 0 corresponds to the first value in A , 1 corresponds to the second, and so on. |
→ Result | Any | The value corresponding to |
Example:
GET(ARRAY(1, 25, 2, 18, 100), 1) → 25
GROUP
GROUP(A, $)
Groups array elements into buckets based on the value produced by the user function $ for each element. The result is an array of groups (key-value maps).
Parameter | Type | Description |
---|---|---|
|
| Array of elements to be grouped. |
$ | User Function | Function to be applied to each element. |
→ Result | Array | Array of groups. Each group G has G.group which contains the value that the user function produced, and G.elements, which contains an array of all elements that produced that value. The order of groups corresponds to the order of the grouping values as they first appear in the source array. |
Example:
Suppose the worklogs attribute contains the following work logs for the issue:
- Author: Bob, Time Spent: 1 hour, Date: Feb-1
- Author: Alice, Time Spent: 2 hours, Date: Feb-1
- Author: Bob, Time Spent: 3 hours, Date: Feb-2
Let's write this using the following pseudo-formula:
worklogs = ARRAY( (author: Bob, timeSpent: 1h, startDate: Feb-1), (author: Alice, timeSpent: 2h, startDate: Feb-1), (author: Bob, timeSpent: 3h, startDate: Feb-2) )
Then the following examples show grouping these work logs by author and by date:
worklogs.GROUP($.author) →
ARRAY(
(group: Bob, elements: ARRAY( (author: Bob, timeSpent: 1h, startDate: Feb-1), (author: Bob, timeSpent: 3h, startDate: Feb-2) )),
(group: Alice, elements: ARRAY( (author: Alice, timeSpent: 2h, startDate: Feb-1) ))
)worklogs.GROUP($.startDate) →
ARRAY(
(group: Feb-1, elements: ARRAY( (author: Bob, timeSpent: 1h, startDate: Feb-1), (author: Alice, timeSpent: 2h, startDate: Feb-1) )),
(group: Feb-2, elements: ARRAY( (author: Bob, timeSpent: 3h, startDate: Feb-2) ))
)
The expressions above show the key-value map values using a pseudo-formula. It is used only to demonstrate the values; Expr currently does not support this language or any way to create arbitrary key-value maps.
INDEX_OF
INDEX_OF(A, Element)
Finds the first occurrence of an element in the array. The comparison is done in the same way function EQ (=) works.
Parameter | Type | Description |
---|---|---|
|
| Array to be searched. |
Element | Any | Element to search for. |
→ Result | Integer | Returns an index of a first occurrence of a specified element in an array. If the element is not found, returns undefined. |
Note: the array is zero-based, so the first element is at Index = 0.
Example:
INDEX_OF(ARRAY(1,3,3,3,5), 3) → 1
INDEXES
INDEXES(A)
Creates an array of indexes of A
, starting with 0. For example, an array with 3 elements would return ARRAY(0, 1, 2).
Parameter | Type | Description |
---|---|---|
|
| Array of elements. |
→ Result | Array | Array of indexes, starting at 0. |
Example:
INDEXES(ARRAY("Cat","DOG","BIRD")) → ARRAY(0,1,2)
IS_ARRAY
IS_ARRAY(Value)
Returns true if the value is an array.
Parameter | Type | Description |
---|---|---|
|
| Value to check. |
→ Result | Boolean | Returns true (1) if the Value is an array; false (0) if the Value is not not an array. |
Examples:
IS_ARRAY(ARRAY(1,2,3)) → 1
IS_EMPTY
IS_EMPTY(A)
Returns true if the array is empty.
Parameter | Type | Description |
---|---|---|
|
| Array of elements. |
→ Result | Boolean | Returns true (1) if the array is empty; false (0) if the array is not empty. Note: will return true for undefined, but false for an empty text string (""). |
Examples:
IS_EMPTY(ARRAY("Cat","DOG","BIRD")) → 0
IS_EMPTY(ARRAY()) → 1
JOIN
JOIN(A)
JOIN(A, Sep, Gs, Ge)
Produces a text string representing any value. If the given value is an array, the text representation is composed by converting each element to text (per Text parameter conversion) and joining them together using ", " as a separator. Then the joined text is put into group parentheses Gs and Ge. If an array element is an array itself, the procedure repeats recursively.
A non-default separator may be passed as the Sep parameter.
Parameter | Type | Description |
---|---|---|
|
| Value to convert to text. |
Sep (Optional) | Text | Optional separator to replace ", ". |
Gs (Optional) | Text | Optional separator to replace "(". |
Ge (Optional) | Text | Optional separator to replace ")". |
→ Result | Text | Text comprised of all values in the array. |
Example:
JOIN(ARRAY("Cat","Dog","Bird")) → (Cat, Dog, Bird)
JOIN(ARRAY(ARRAY("Cat","Dog","Bird")), ARRAY("Sheep", "Pig")), " + " , "{" , "}" ) → {{Cat + Dog + Bird} + {Sheep + Pig}}
JOIN("Cat") → (Cat)
LAST
LAST(A)
Returns the last element of the array, or undefined if the array is empty.
Parameter | Type | Description |
---|---|---|
|
| Array of any type. |
→ Result | Any | Last element contained in the array. If empty, returns undefined. |
Example:
LAST(ARRAY(1, 2, 3)) → 3
LAST_INDEX_OF
LAST_INDEX_OF(A, Element)
Finds the last occurrence of an element in the array.
Parameter | Type | Description |
---|---|---|
|
| Array to be searched. |
Element | Any | Element to search for. |
→ Result | Integer | Returns an index of a last occurrence of a specified element in an array. If the element is not found, returns undefined. |
Note: the array is zero-based, so the first element is at Index = 0.
Example:
LAST_INDEX_OF(ARRAY(1,2,2,2,3), 2) → 3
MAP
MAP(A, $)
Applies the user function to every element of the array.
Parameter | Type | Description |
---|---|---|
|
| Array of elements to be mapped. |
$ | User Function | Function to be applied to each element. |
→ Result | Array | Array containing the results. |
Example:
ARRAY(1, 2, 3).MAP(x -> x * 100) → ARRAY(100, 200, 300)
affectedVersions.MAP($.releaseDate - $.startDate)
MERGE_ARRAYS
MERGE_ARRAYS(Array1, Array2, ..., ArrayN)
Produces a single array with the elements of all parameter arrays. Equal to ARRAY(a1, a2, ...).FLATTEN()
.
Parameter | Type | Description |
---|---|---|
|
| Arrays to be grouped. |
→ Result | Array | Single array containing all elements. |
Example:
MERGE_ARRAYS(ARRAY(1, 2, 3),ARRAY(4,5,6),ARRAY(7)) → ARRAY(1,2,3,4,5,6,7)
NONE
NONE(A, $)
Checks that $ returns false for all elements in the array.
Parameter | Type | Description |
---|---|---|
|
| Array of elements to be used in $. |
$ | User Function | Function to be applied to each element. |
→ Result | Boolean | Returns |
This function is the inverse of ANY()
Examples:
NONE(fixVersions, $.startDate < TODAY())
Returns true if no fixVersions started before the current date.→
RECURSIVE_FLATTEN
RECURSIVE_FLATTEN(A)
Performs recursive flattening and compacting of the array. The resulting array is guaranteed to be flat and not contain undefined values.
Parameter | Type | Description |
---|---|---|
|
| Array of arrays. |
→ Result | Array | A single array, containing all elements with no undefined values. |
Examples:
RECURSIVE_FLATTEN(ARRAY(ARRAY(1, undefined, 2), ARRAY(2, 3), 100)) → ARRAY(1, 2, 2, 3, 100)
REDUCE
REDUCE(A, $)
Reduces an array to a single value based on $.
Parameter | Type | Description |
---|---|---|
|
| Array to be reduced. |
$ | User Function | Function containing two parameters. |
→ Result |
|
|
Examples:
ARRAY(2, 3, 2, 1, 2).REDUCE((a, b) -> a * b) → 24
REVERSE
REVERSE(A)
Reverses the order of elements in the array.
Parameter | Type | Description |
---|---|---|
|
| Array of elements. |
→ Result | Array | Array with elements in reverse order. |
Example:
REVERSE(ARRAY(1, 2, 3, 4)) → ARRAY(4, 3, 2, 1)
SEQUENCE
SEQUENCE(from, to)
Creates an array of integer numbers, starting with from and ending with to (inclusive). If to is less than from, the sequence will be descending.
Parameter | Type | Description |
---|---|---|
|
| Starting integer. |
to | Integer | Ending integer. |
→ Result | Array | Array of integers. |
Examples:
SEQUENCE(3, 6) → ARRAY(3, 4, 5, 6)
SEQUENCE(6, 3) → ARRAY(6, 5, 4, 3)
SIZE
SIZE(A)
Returns the number of elements in the array.
Parameter | Type | Description |
---|---|---|
|
| Array of elements. |
→ Result | Integer | Number of elements contained in the array. |
Example:
SIZE(ARRAY(1, 2, 3, 4)) → 4
SIZE(ARRAY(1, ARRAY(2, 3, 4), undefined)) → 3
SORT
SORT(A)
Sorts the array using a natural order of elements: numbers, text values, item values, and then array values (which are compared with respect to all the non-array elements). Item values are compared first by item type (lexicographically, so a user would come before a version because "u" comes before "v") and then either by the item's natural order, if it exists, or by the item's text representation, if it doesn't.
Parameter | Type | Description |
---|---|---|
|
| Array of elements to be sorted. |
→ Result | Array | Sorted array. |
Example:
SORT(ARRAY(3,1,2)) → ARRAY(1,2,3)
SORT_BY
SORT_BY(A, $)
Sorts the array by comparing the values produced by calling the user function $ for each array element. Results of the user function $ calls are compared the same way as the SORT function.
Parameter | Type | Description |
---|---|---|
|
| Array of elements to be sorted. |
$ | User Function | Function to be applied to each element. |
→ Result | Array | Sorted array. |
Example:
SORT_BY(fixVersions, $.releaseDate)
SUBARRAY
SUBARRAY(A, from, to)
Produces an array with elements from the given array. Parameters from (inclusive) and to (exclusive) define the range. Indexes are zero-based.
Parameter | Type | Description |
---|---|---|
A | Array | Array of elements. |
|
| Starting index (inclusive). |
to | Integer | Ending index (exclusive). |
→ Result | Array | Array containing elements between |
Examples:
SUBARRAY(ARRAY("Cat", "Dog", "Mouse", "Bird", "Sheep"), 1, 3) → ARRAY("Dog", "Mouse")
UNIQUE
UNIQUE(A)
Removes duplicates from the array. The order of non-duplicate elements is preserved.
Parameter | Type | Description |
---|---|---|
|
| Array of elements. |
→ Result | Array | Array with duplicates removed. |
Note: the equality is strict, so "0" and 0 would be different elements.
Example:
UNIQUE(ARRAY(1, 2, 1, 3, 3, 4)) → ARRAY(1, 2, 3, 4)
WITHOUT
WITHOUT(A, Value)
Returns a new array with all the elements from the input array except those equal to Value.
Parameter | Type | Description |
---|---|---|
|
| Array of elements. |
Value | Any | Element to be removed. |
→ Result | Array | New array with |
Equality is done using the same logic as the = operator and CONTAINS.
Example:
WITHOUT(ARRAY(1, 2, 1, 3, 3, 4), 1) → ARRAY(2, 3, 3, 4)