A set of functions for working with and manipulating array values.
All
All(inputArray, testFunction) -> Boolean
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
-
testFunction: Function - The function used to test each element in the array
test. 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:Function(value: Any) -> Boolean - 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 i test
// 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 i Arcade function as the test. This is valid because i takes a single parameter and returns a boolean value. This expression returns true if all of the fields are empty.
var myArray = [ $feature.field1, $feature.field2, $feature.field3, $feature.field4];
All(myArray, isEmpty)Any
Any(inputArray, testFunction) -> Boolean
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
-
testFunction: Function - The function used to test each element in the array
test. 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:Function(value: Any) -> Boolean - 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 i test.
// 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 i Arcade function as the test. This is valid because i takes a single parameter and returns a boolean value. This expression returns true if any of the fields are empty.
var myArray = [ $feature.field1, $feature.field2, $feature.field3, $feature.field4];
Any(myArray, isEmpty)Array
This function has 2 signatures:
Array(arrayLength, defaultValue?) -> Array<Any>
Function bundle: Core
Returns a new array of a given length.
Parameters
- arrayLength: 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.
Examples
Returns [null, null, null, null, null].
Array(5)Returns ["hello","hello"]
Array(2, "hello")Returns [1,1,1].
Array(3, 1)Array(inputArray, deep?) -> Array<Any>
Function bundle: Core
Returns either a shallow or deep copy of an input array.
Parameters
- inputArray: Array<Any> - The array to be copied.
- deep (Optional): Boolean - When
true, creates a deep copy of each element in the input array, meaning elements in the output array will not share the same references as the elements of the input array. Default value isfalse.
Examples
Creates a shallow copy of the input array
var person1 = {
firstName: "Jane",
lastName: "Doe"
};
var person2 = {
firstName: "John",
lastName: "Smith"
};
var people = [ person1, person2 ];
// create a shallow copy of the array
var copiedArray = Array(people);
people[0] == copiedArray[0];
// returns true
// this is a shallow copy of the array, so the elements share the same referencesCreates a deep copy of the input array
var deepCopy = Array(people, true);
people[0] == deepCopy[0]
// returns false
// this is a deep copy of the array, so the elements do NOT share the same referencesBack
Back(inputArray) -> Any
Function bundle: Core
Returns the last element of an array. If the input array is empty, then the expression evaluation will fail.
Parameter
Return value: Any
Example
Returns 'gray'.
var colors = ['orange', 'purple', 'gray']
Back(colors)Count
Count(value) -> Number
Function bundle: Core
Returns the number of items in an array.
Parameter
Return value: Number
Example
Returns 6
Count([12,21,32,44,58,63])Distinct
This function has 2 signatures:
Distinct(values) -> Array<Any>
Function bundle: Core
Returns a set of distinct, or unique, values for an array of values.
Parameter
Example
Distinct([1,1,2,1,1,2,2,3,4,5])
// Returns [1,2,3,4,5]Distinct([value1, ..., valueN]?) -> Array<Any>
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.
Example
Distinct('high','medium','low',0,'high','high','low')
// Returns ['high','medium','low',0]Erase
Erase(inputArray, index) -> Null
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
var colors = ['orange', 'purple', 'gray']
Erase(colors, 1)
// colors = ['orange','gray']var colors = ['orange', 'purple', 'gray']
Erase(colors, -1)
// colors = ['orange','purple']Filter
Filter(inputArray, filterFunction) -> Array<Any>
Function bundle: Core
Creates a new array with the elements filtered from the input array that pass a test from the provided function.
Parameters
-
filterFunction: Function - The function used to filter elements in the array
filter. 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:Function(value: Any) -> Boolean - 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 i filter.
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 i Arcade function in the filter. Returns a new array of fields that are not empty.
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 resultFirst
First(inputArray) -> Any
Function bundle: Core
Returns the first element in an array. Returns null if the array is empty.
Parameter
Return value: Any
Example
prints 'orange'
First(['orange', 'purple', 'gray'])Front
Front(inputArray) -> Any
Function bundle: Core
Returns the first element of an array. If the input array is empty, then the expression evaluation will fail.
Parameter
Return value: Any
Example
Returns 'orange'.
var colors = ['orange', 'purple', 'gray']
Front(colors)Includes
Includes(inputArray, value) -> Boolean
Function bundle: Core
Determines whether an array contains a given value. Returns true if the value is found within the array.
Parameters
Return value: Boolean
Examples
Returns true.
Includes(['orange', 'purple', 'gray'], 'purple')Returns false.
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
Return value: Number
Example
prints 2
var num = [1,2,3,4];
return indexof(num, 3);Insert
Insert(inputArray, index, value) -> Null
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
var colors = ['orange', 'purple', 'gray']
Insert(colors, 1, 'yellow')
// colors = ['orange','yellow','purple','gray']var colors = ['orange', 'purple', 'gray']
Insert(colors, -1, 'yellow')
// colors = ['orange','purple','yellow','gray']Map
Map(inputArray, mappingFunction) -> Array<Any>
Function bundle: Core
Creates a new array based on results of calling a provided function on each element in the input array.
Parameters
-
mappingFunction: Function - The function to call on each element in the array
mapping. 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:Function(value: Any) -> Any - 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.
// 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
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
Function bundle: Core
Tests whether none of the elements in a given array pass a test from the provided function. Returns true if the test returns false for all items in the input array.
Parameters
-
testFunction: Function - The function to test each element in the array
test. 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:Function(value: Any) -> Boolean - 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 i test
// 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 i Arcade function as the test. This is valid because i takes a single parameter and returns a boolean value. This expression returns true if none of the fields are empty.
var myArray = [ $feature.field1, $feature.field2, $feature.field3, $feature.field4];
None(myArray, isEmpty)Pop
Pop(inputArray) -> Any
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
Return value: Any
Example
Returns 'gray'. The input array will now equal ['orange', 'purple'].
Pop(['orange', 'purple', 'gray'])Push
Push(inputArray, value) -> Number
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'].
Push(['orange', 'purple', 'gray'], 'red')Reduce
Reduce(inputArray, reducerFunction, initialValue?) -> Any
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
-
reducerFunction: Function - The reducer function that will aggregate the array values
reducer.Function(previous Value: Any, array Value: Any) -> Any -
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 initial parameter, the first two elements of the cities array are passed into the add function as arguments.
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 913921Since the initial 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).
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 3898747Resize
Resize(inputArray, newSize, value?) -> Null
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
nullvalue.
Return value: Null
Examples
Returns ['orange', 'purple', 'gray', null, null]
var colors = ['orange', 'purple', 'gray']
Resize(colors, 5)
return colorsReturns ['orange', 'purple', 'gray', 'red', 'red']
var colors = ['orange', 'purple', 'gray']
Resize(colors, 5, 'red')
return colorsReturns ['orange']
var colors = ['orange', 'purple', 'gray']
Resize(colors, 1)
return colorsReverse
Reverse(inputArray) -> Array<Any>
Function bundle: Core
Reverses the contents of the array in place.
Parameter
Example
Returns ['gray', 'purple', 'orange']
Reverse(['orange', 'purple', 'gray'])Slice
Slice(inputArray, startIndex?, endIndex?) -> Array<Any>
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.
Examples
Returns ['purple', 'gray']
Slice(['orange', 'purple', 'gray', 'red', 'blue'], 1, 3)Returns ['red', 'blue']
Slice(['orange', 'purple', 'gray', 'red', 'blue'], 3)Returns ['orange', 'purple', 'gray', 'red', 'blue']
Slice(['orange', 'purple', 'gray', 'red', 'blue'])Returns ['blue']
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
-
comparatorFunction (Optional): Function - A user defined function to be used for the sort
ordering. The function receives two elements and should retun a number that indicates the sorting order of the two elements:Function(a: Any, b: Any) -> Number
> 0: sortbbeforea
= 0: keep the original order ofaandb
< 0: sortabeforeb
Examples
returns ['$', 1, 'A', 'a']
Sort([1, 'a', '$', 'A'])Sort using a user defined function
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>
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.
Examples
Returns ['orange', 'purple', 1, 2, 'red']
Splice(['orange', 'purple'], 1, 2, 'red')Returns [1, 2, 3, 4]
Splice([1,2], [3,4])Top
Top(inputArray, numItems) -> Array<Any>
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.
Example
returns [ 43,32,19 ]
Top([ 43,32,19,0,3,55 ], 3)