Document toolboxDocument toolbox

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. 

ParameterTypeDescription

A

Array

Array of elements to be used in $.

$User FunctionFunction to be applied to each element.
ResultBoolean

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(fixVersions, $.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.

ParameterTypeDescription

A

Array

Array of elements to be used in $.

$User FunctionFunction to be applied to each element.
ResultBoolean

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.

ParameterTypeDescription

Element1, Element2, ..., ElementN

Any

Elements to be added to the array.

ResultArray

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.

ParameterTypeDescription

A

Array

Array to be compacted.

ResultArray

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.

ParameterTypeDescription

A

Array

Array to search in.

ElementAnyElement to look for.
ResultBoolean

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.

ParameterTypeDescription

A

Array

Array to search in.

Elements_ArrayArrayArray of elements to look for.
ResultBoolean

Returns true (1) if A contains all elements contained in Elements)Array. Otherwise, returns false (0).

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.

ParameterTypeDescription

A

Array

Array to search in.

Elements_ArrayArrayArray of elements to look for.
ResultBoolean

Returns true (1) if A contains any elements contained in Elements_Array. Otherwise, returns false (0).

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).

ParameterTypeDescription

A

Array

Array of elements to be filtered.

$User FunctionFunction to be applied to each element.
ResultArray

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.

ParameterTypeDescription

A

Array

Array of elements.

ResultAny

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). 

ParameterTypeDescription

A

Array

Array of arrays, or array containing arrays and non-array values.

ResultArray

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.

ParameterTypeDescription

A

Array

Array to search.

IndexIntegerNumeric index, 0-based: 0 corresponds to the first value in A, 1 corresponds to the second, and so on.
ResultAny

The value corresponding to Index.

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).

ParameterTypeDescription

A

Array

Array of elements to be grouped.

$User FunctionFunction to be applied to each element.
ResultArray

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.

ParameterTypeDescription

A

Array

Array to be searched.

ElementAnyElement to search for.
ResultInteger

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).

ParameterTypeDescription

A

Array

Array of elements.

ResultArray

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.

ParameterTypeDescription

Value

Any

Value to check.

ResultBoolean

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.

ParameterTypeDescription

A

Array

Array of elements.

ResultBoolean

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.

ParameterTypeDescription

A

Any

Value to convert to text.

Sep (Optional)TextOptional separator to replace ", ".
Gs (Optional)TextOptional separator to replace "(".
Ge (Optional)TextOptional separator to replace ")".
ResultText

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.

ParameterTypeDescription

A

Array

Array of any type.

ResultAny

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. 

ParameterTypeDescription

A

Array

Array to be searched.

ElementAnyElement to search for.
ResultInteger

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.

ParameterTypeDescription

A

Array

Array of elements to be mapped.

$User FunctionFunction to be applied to each element.
ResultArray

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().

ParameterTypeDescription

Array1, Array2, ..., ArrayN

Array

Arrays to be grouped.

ResultArray

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. 

ParameterTypeDescription

A

Array

Array of elements to be used in $.

$User FunctionFunction to be applied to each element.
ResultBoolean

Returns true (1) or false (0). If the array is empty, returns true (1).

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.

ParameterTypeDescription

A

Array

Array of arrays.

ResultArray

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 $

ParameterTypeDescription

A

Array

Array to be reduced.

$User FunctionFunction containing two parameters.
Result

Any

  • Applies the function to the first two elements in the array. Then applies the function again, using the resulting value and the third element. And so on.
  • For an empty array, returns undefined.
  • For an array with one element, returns that element.

Examples:

  • ARRAY(2, 3, 2, 1, 2).REDUCE((a, b) -> a * b) → 24

REVERSE

REVERSE(A)

Reverses the order of elements in the array.

ParameterTypeDescription

A

Array

Array of elements.

ResultArray

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.

ParameterTypeDescription

from

Integer

Starting integer.

toIntegerEnding integer.
ResultArray

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.

ParameterTypeDescription

A

Array

Array of elements.

ResultInteger

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.

ParameterTypeDescription

A

Array

Array of elements to be sorted.

ResultArray

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.

ParameterTypeDescription

A

Array

Array of elements to be sorted.

$User FunctionFunction to be applied to each element.
ResultArray

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.

ParameterTypeDescription
AArrayArray of elements.

from

Integer

Starting index (inclusive).

toIntegerEnding index (exclusive).
ResultArray

Array containing elements between from and to.

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.

ParameterTypeDescription

A

Array

Array of elements.

ResultArray

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

ParameterTypeDescription

A

Array

Array of elements.

ValueAnyElement to be removed.
ResultArray

New array with Value removed.

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)