Array functions

A set of functions for working with and manipulating array values.

All

All(inputArray, testFunction) -> Boolean

Since version 1.16

Function bundle: Core

Indicates whether all of the elements in a given array pass a test from the provided function. Returns true if the function returns true for all items in the input array.

Parameters

• inputArray: Array<Any> - The input array to test.

• testFunction: Function - The function used to test each element in the array testFunction(value: Any) -> Boolean. The function must return a truthy value if the element passes the test. The function can be a user-defined function or a core Arcade function defined with the following parameter:

  • value: Any - Represents the value of an element in the array.

Return value: Boolean
true if the test function returns a truthy value for all the elements.

Examples

Returns false because some of the elements in the input array do not pass the isEven test

1
2
3
4
5
6
7
8
// isEven is used to test if each element in the array is even
// it returns true if the element is divisible by two, false if is not
function isEven(value) { return value % 2 == 0 }
// The isEven function will execute for each element in the array,
// returning the following values: false, true, false, true, false
// Since some of the values in the array did not pass the test
// (return true), the return value will be false
All([1,2,3,4,5], isEven)

Uses the existing isEmpty Arcade function as the testFunction. This is valid because isEmpty takes a single parameter and returns a boolean value. This expression returns true if all of the fields are empty.

1
2
var myArray = [ $feature.field1, $feature.field2, $feature.field3, $feature.field4];
All(myArray, isEmpty)

Any

Any(inputArray, testFunction) -> Boolean

Since version 1.16

Function bundle: Core

Tests whether any of the elements in a given array pass a test from the provided function. Returns true if the function returns true for at least one item in the input array.

Parameters

• inputArray: Array<Any> - The input array to test.

• testFunction: Function - The function used to test each element in the array testFunction(value: Any) -> Boolean. The The function must return a truthy value if the element passes the test. The function can be a user-defined function or a core Arcade function defined with the following parameter:

  • value: Any - Represents the value of an element in the array.

Return value: Boolean
true if the test function returns a truthy value for any of the elements.

Examples

Returns true because at least one element in the input array passes the isEven test.

1
2
3
4
5
6
7
8
// isEven is used to test if each element in the array is even
// it returns true if the element is divisible by two, false if is not
function isEven(value) { return value % 2 == 0 }
// The isEven function will execute for each element in the array,
// returning the following values: false, true, false, true, false
// Since at least one value in the array passed the test
// (return true), the return value will be true
Any([1,2,3,4,5], isEven)

Uses the existing isEmpty Arcade function as the testFunction. This is valid because isEmpty takes a single parameter and returns a boolean value. This expression returns true if any of the fields are empty.

1
2
var myArray = [ $feature.field1, $feature.field2, $feature.field3, $feature.field4];
Any(myArray, isEmpty)

Array

Array(value, defaultValue?) -> Array<Any>

Since version 1.12

Function bundle: Core

Returns a new array of a given length.

Parameters

• value: Number - The desired length for the new array.
• defaultValue (Optional): Any - The value for each element in the array. If no value is specified, the default will be null.

Return value: Array<Any>

Examples

Returns [null, null, null, null, null].

1
Array(5)

Returns ["hello","hello"]

1
Array(2, "hello")

Returns [1,1,1].

1
Array(3, 1)

Back

Back(inputArray) -> Any

Since version 1.12

Function bundle: Core

Returns the last element of an array. If the array is empty, then Back(inputArray) will cause the script evaluation to fail.

Parameter

• inputArray: Array<Any> - The array to get the last value from.

Return value: Any

Example

Returns 'gray'.

1
2
var colors = ['orange', 'purple', 'gray']
Back(colors)

Count

Count(value) -> Number

Function bundle: Core

Returns the number of items in an array.

Parameter

• value: Array<Any> - An array on which to perform the operation.

Return value: Number

Example

Returns 6

1
Count([12,21,32,44,58,63])

Distinct

This function has 2 signatures:

• Distinct(values) -> Array<Any>
• Distinct([value1, ..., valueN]?) -> Array<Any>

Distinct(values) -> Array<Any>

Since version 1.1

Function bundle: Core

Returns a set of distinct, or unique, values for an array of values.

Parameter

• values: Array<Any> - An array of values on which to perform the operation.

Return value: Array<Any>

Example

1
2
Distinct([1,1,2,1,1,2,2,3,4,5])
// Returns [1,2,3,4,5]

Distinct([value1, ..., valueN]?) -> Array<Any>

Since version 1.1

Function bundle: Core

Returns a set of distinct, or unique, values for a list of values.

Parameter

• [value1, ..., valueN] (Optional): Any - A list of values on which to perform the operation.

Return value: Array<Any>

Example

1
2
Distinct('high','medium','low',0,'high','high','low')
// Returns ['high','medium','low',0]

Erase

Erase(inputArray, index) -> Null

Since version 1.12

Function bundle: Core

Removes a value from an array at a given index. Existing elements positioned at or above the given index will shift down one index value. The array decreases in size by one.

Parameters

• inputArray: Array<Any> - The array to remove the value from.
• index: Number - The index of the value to remove from the array. If a negative index is provided, it will be used as an offset from the end of the array.

Return value: Null

Examples

1
2
3
var colors = ['orange', 'purple', 'gray']
Erase(colors, 1)
// colors = ['orange','gray']

1
2
3
var colors = ['orange', 'purple', 'gray']
Erase(colors, -1)
// colors = ['orange','purple']

Filter

Filter(inputArray, filterFunction) -> Array<Any>

Since version 1.16

Function bundle: Core

Creates a new array with the elements filtered from the input array that pass a test from the provided function.

Parameters

• inputArray: Array<Any> - The input array to filter.

• filterFunction: Function - The function used to filter elements in the array filterFunction(value: Any) -> Boolean. The The function must return a truthy value if the element passes the test. This function can be a user-defined function or a core Arcade function defined with the following parameter:

  • value: Any - Represents the value of an element in the array.

Return value: Array<Any>
Returns an array with the elements that passe the test function.

Examples

Returns a new array comprised of elements that passed the isEven filter.

1
2
3
4
function isEven(i) { return i % 2 == 0 }
Filter([1,2,3,4,5], isEven) // Returns [2,4]
// Since 2 and 4 are even, they are the only values
// included in the output array.

Uses the existing isEmpty Arcade function in the filterFunction. Returns a new array of fields that are not empty.

1
2
3
4
5
6
7
8
var myArray = [ $feature.field1, $feature.field2, $feature.field3, $feature.field4];

function isNotEmpty(value){
  return !isEmpty(value);
}
Filter(myArray, isNotEmpty)
// Returns only values that are defined,
// excluding empty values from the result

First

First(inputArray) -> Any

Function bundle: Core

Returns the first element in an array. Returns null if the array is empty.

Parameter

• inputArray: Array<Any> - The array from which to return the first item.

Return value: Any

Example

prints 'orange'

1
First(['orange', 'purple', 'gray'])

Includes

Includes(inputArray, value) -> Boolean

Since version 1.12

Function bundle: Core

Determines whether an array contains a given value. Returns true if the value is found within the array.

Parameters

• inputArray: Array<Any> - The input array.
• value: Any - The value to look for in the given array.

Return value: Boolean

Examples

Returns true.

1
Includes(['orange', 'purple', 'gray'], 'purple')

Returns false.

1
Includes(['orange', 'purple', 'gray'], 'red')

IndexOf

IndexOf(inputArray, item) -> Number

Function bundle: Core

Returns the zero-based index location of the input item in an array. If item does not exist, then -1 is returned.

Parameters

• inputArray: Array<Any> - The array to search.
• item: Any - The item to locate in the array.

Return value: Number

Example

prints 2

1
2
var num = [1,2,3,4];
return indexof(num, 3);

Insert

Insert(inputArray, index, value) -> Null

Since version 1.12

Function bundle: Core

Inserts a new value into an array at a given index. Existing elements positioned at or above the given index will shift up one index value. The array increases in size by one.

Parameters

• inputArray: Array<Any> - The array to insert the new value into.
• index: Number - The index of the array where the new value should be inserted. An index of 0 will insert the value at the beginning of the array. An index that equals the size of the array will insert the value at the end of the array. An index greater than the size of the array will cause an error. If a negative index is provided, it will be used as an offset from the end of the array.
• value: Any - The value to insert into the array.

Return value: Null

Examples

1
2
3
var colors = ['orange', 'purple', 'gray']
Insert(colors, 1, 'yellow')
// colors = ['orange','yellow','purple','gray']

1
2
3
var colors = ['orange', 'purple', 'gray']
Insert(colors, -1, 'yellow')
// colors = ['orange','purple','yellow','gray']

Map

Map(inputArray, mappingFunction) -> Array<Any>

Since version 1.16

Function bundle: Core

Creates a new array based on results of calling a provided function on each element in the input array.

Parameters

• inputArray: Array<Any> - The input array to map.

• mappingFunction: Function - The function to call on each element in the array mappingFunction(value: Any) -> Any. The function must return a new item that will be part of the returned array. The function can be a user-defined function or a core Arcade function defined with the following parameter:

  • value: Any - Represents the value of an element in the array.

Return value: Array<Any>
The items returned by the mapping function.

Examples

Converts all of the elements in the array from Fahrenheit to Celsius and returns them in a new array.

1
2
3
4
5
6
7
8
9
// This function will take in values from the input array and convert them to Celsius
function toCelsius(f) {
  return Round((f - 32) * 5/9, 2)
}
// The toCelsius function executes for each each item
// in the input array.
// Map returns the resulting array of converted values.
Map([82, 67, 96, 55, 34], toCelsius)
// returns [27.78, 19.44, 35.56, 12.78, 1.11]

Converts date objects to formatted text

1
2
3
4
var dates = [ Date(1996, 11, 10), Date(1995, 1, 6), Date(1992, 2, 27), Date(1990, 10, 2)];
function formatDates(dateVal) { return Text(dateVal, 'MMM D, Y') }
Map(dates, formatDates);
// returns ['Dec 10, 1996', 'Feb 6, 1995', 'Mar 27, 1992', 'Nov 2, 1990']

None

None(inputArray, testFunction) -> Boolean

Since version 1.16

Function bundle: Core

Tests whether none of the elements in a given array pass a test from the provided function. Returns true if the testFunction returns false for all items in the input array.

Parameters

• inputArray: Array<Any> - The input array to test.

• testFunction: Function - The function to test each element in the array testFunction(value: Any) -> Boolean. The function must return a falsy value if the element doesn't pass the test. The function can be a user-defined function or a core Arcade function defined with the following parameter:

  • value: Any - Represents the value of an element in the array.

Return value: Boolean
true if all the elements in the array don't pass the test function.

Examples

Returns false because some of the elements in the input array pass the isEven test

1
2
3
4
5
6
7
8
// isEven is used to test if each element in the array is even
// it returns true if the element is divisible by two, false if is not
function isEven(value) { return value % 2 == 0 }
// The isEven function will execute for each element in the array,
// returning the following values: false, true, false, true, false
// Since at least one value in the array passed the test
// (return true), the return value will be false
None([1,2,3,4,5], isEven)

Uses the existing isEmpty Arcade function as the testFunction. This is valid because isEmpty takes a single parameter and returns a boolean value. This expression returns true if none of the fields are empty.

1
2
var myArray = [ $feature.field1, $feature.field2, $feature.field3, $feature.field4];
None(myArray, isEmpty)

Pop

Pop(inputArray) -> Any

Since version 1.12

Function bundle: Core

Removes and returns the element at the end of the array. If the array is empty, then an error is thrown.

Parameter

• inputArray: Array<Any> - The input array from which the last element will be removed and returned.

Return value: Any

Example

Returns 'gray'. The input array will now equal ['orange', 'purple'].

1
Pop(['orange', 'purple', 'gray'])

Push

Push(inputArray, value) -> Number

Since version 1.12

Function bundle: Core

Adds an element to the end of an array and returns the new length of the array.

Parameters

• inputArray: Array<Any> - The array to have elements pushed to.
• value: Any - The value to add as the last element of the input array.

Return value: Number

Example

Returns 4. The input array will now equal ['orange', 'purple', 'gray', 'red'].

1
Push(['orange', 'purple', 'gray'], 'red')

Reduce

Reduce(inputArray, reducerFunction, initialValue?) -> Any

Since version 1.16

Function bundle: Core

Executes a provided "reducer" function on each element in the array, passing in the return value from the calculation of the previous element.

Parameters

• inputArray: Array<Any> - The input array to reduce.

• reducerFunction: Function - The reducer function that will aggregate the array values reducerFunction(previousValue: Any, arrayValue: Any) -> Any.

  • previousValue: Any - The first time the function executes, this will be the first element in the input array or the initialValue, if provided.
  • arrayValue: Any - Represents the current value of an element in the input array.

• initialValue (Optional): Any - An item to pass into the first argument of the reducer function.

Return value: Any
The value that was assembled by the reducer function for each element in the array.

Examples

Without the initialValue parameter, the first two elements of the cities array are passed into the add function as arguments.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
var cities = [{
   name: 'Columbus',
   pop: 913921
}, {
   name: 'Cincinnati',
   pop: 307266
}, {
   name: 'Dayton',
   pop: 140343
}, {
   name: 'Cleveland',
   pop: 376599
}];
// the first time this function is called it will take the first two elements of the array as x and y
// The subsequent times the function is executed, it will take the return value
// from the previous function call as x and the next array value as y
function mostPopulated(city1, city2) {
   IIf (city1.pop > city2.pop, city1, city2)
}
var largestCity = Reduce(cities, mostPopulated)
Console(largestCity.name + ' is the biggest city in the list with a population of ' + largestCity.pop)
// Columbus is the biggest city in the list with a population of 913921

Since the initialValue parameter is set, that value will be the function's first argument (city1), and the first element of the cities will be the function's second argument (city2).

1
2
3
4
5
6
7
8
var los_angeles = { name: 'Los Angeles', pop: 3898747 }
// since an initialValue is provided, it will be passed into the maxPop function as x
// and the first value of the array will be passed in as y for the initial function call
// The subsequent times the function is executed, it will take the return value
// from the previous function call as x and the next array value as y
var largestCity = Reduce(cities, mostPopulated, los_angeles)
Console(largestCity.name + ' is the biggest city in the list with a population of ' + largestCity.pop)
// Los Angeles is the biggest city in the list with a population of 3898747

Resize

Resize(inputArray, newSize, value?) -> Null

Since version 1.12

Function bundle: Core

Changes the number of elements in an array to the specified size. It can be used to expand the array or truncate it early. After resizing, attempting to index beyond the new last element will result in an error, except for the case of indexing the next element, which will continue to expand the array by one element.

Parameters

• inputArray: Array<Any> - The array to be resized.
• newSize: Number - The number of elements desired in the resized array.
• value (Optional): Any - The optional value that will be used for any new elements added to the array. If no value is specified, the newly added elements will have a null value.

Return value: Null

Examples

Returns ['orange', 'purple', 'gray', null, null]

1
2
3
var colors = ['orange', 'purple', 'gray']
Resize(colors, 5)
return colors

Returns ['orange', 'purple', 'gray', 'red', 'red']

1
2
3
var colors = ['orange', 'purple', 'gray']
Resize(colors, 5, 'red')
return colors

Returns ['orange']

1
2
3
var colors = ['orange', 'purple', 'gray']
Resize(colors, 1)
return colors

Reverse

Reverse(inputArray) -> Array<Any>

Function bundle: Core

Reverses the contents of the array in place.

Parameter

• inputArray: Array<Any> - The array to be reversed.

Return value: Array<Any>

Example

Returns ['gray', 'purple', 'orange']

1
Reverse(['orange', 'purple', 'gray'])

Slice

Slice(inputArray, startIndex?, endIndex?) -> Array<Any>

Since version 1.12

Function bundle: Core

Returns a portion of an array between two indexes as a new array.

Parameters

• inputArray: Array<Any> - The array to be sliced.
• startIndex (Optional): Number - The index from which to start the slice. Defaults to 0. If a negative index is provided, it will be used as an offset from the end of the array.
• endIndex (Optional): Number - The index where the slice will end. The value at this index will not be included in the returned array. Defaults to the array size.

Return value: Array<Any>

Examples

Returns ['purple', 'gray']

1
Slice(['orange', 'purple', 'gray', 'red', 'blue'], 1, 3)

Returns ['red', 'blue']

1
Slice(['orange', 'purple', 'gray', 'red', 'blue'], 3)

Returns ['orange', 'purple', 'gray', 'red', 'blue']

1
Slice(['orange', 'purple', 'gray', 'red', 'blue'])

Returns ['blue']

1
Slice(['orange', 'purple', 'gray', 'red', 'blue'], -1)

Sort

Sort(inputArray, comparatorFunction?) -> Array<Any>

Function bundle: Core

Sorts an array by ASCII value. If all the items in the array are the same type, an appropriate sort function will be used. If they are different types, the items will be converted to text. If the array contains dictionaries, and no user defined function is provided, no sort will happen. If the array contains null values, they will not be converted to text and will be returned at the end of the sorted array.

Parameters

• inputArray: Array<Any> - The array to sort.

• comparatorFunction (Optional): Function - A user defined function to be used for the sort orderingFunction(a: Any, b: Any) -> Number. The function receives two elements and should retun a number that indicates the sorting order of the two elements:
  > 0: sort b before a
= 0: keep the original order of a and b
< 0: sort a before b

  • a: Any - The first element for comparison.
  • b: Any - The second element for comparison.

Return value: Array<Any>

Examples

returns ['$', 1, 'A', 'a']

1
Sort([1, 'a', '$', 'A'])

Sort using a user defined function

1
2
3
4
5
6
7
8
9
10
var peopleArray = [{ 'NAME': 'Sam', 'AGE': 25 }, {'NAME': 'Bob', 'AGE': 27 },{ 'NAME': 'Emma', 'AGE': 24 }];
function compareAge(a,b){
  if (a['AGE']<b['AGE'])
    return -1;
  if (a['AGE']>b['AGE'])
    return 1;
  return 0;
}
return Sort(peopleArray, compareAge);
// returns '[{ 'AGE': 24, 'NAME': 'Emma' }, { 'AGE': 25, 'NAME': 'Sam' }, { 'AGE': 27, 'NAME': 'Bob' } ]'

Splice

Splice([value1, ..., valueN]?) -> Array<Any>

Since version 1.12

Function bundle: Core

Concatenates all parameters together into a new array.

Parameter

• [value1, ..., valueN] (Optional): Any - An ongoing list of values to be spliced into a new array.

Return value: Array<Any>

Examples

Returns ['orange', 'purple', 1, 2, 'red']

1
Splice(['orange', 'purple'], 1, 2, 'red')

Returns [1, 2, 3, 4]

1
Splice([1,2], [3,4])

Top

Top(inputArray, numItems) -> Array<Any>

Since version 1.3

Function bundle: Core

Truncates the input array and returns the first given number of elements.

Parameters

• inputArray: Array<Any> - The array to truncate.
• numItems: Number - The number of items to return from the beginning of the array.

Return value: Array<Any>

Example

returns [ 43,32,19 ]

1
Top([ 43,32,19,0,3,55 ], 3)