Array functions
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
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.
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.
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.
Array
Array(value, defaultValue?) -> Array<Any>
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
.
Examples
Returns [null, null, null, null, null]
.
Returns ["hello","hello"]
Returns [1,1,1]
.
Back
Back(inputArray) -> Any
Function bundle: Core
Returns the last element of an array. If the array is empty, then Back(input
will cause the script evaluation to fail.
Parameter
Return value: Any
Example
Returns 'gray'
.
Count
Count(value) -> Number
Function bundle: Core
Returns the number of items in an array.
Parameter
Return value: Number
Example
Returns 6
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([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
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
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.
Uses the existing i
Arcade function in the filter
. Returns a new array of fields that are not empty.
First
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'
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
.
Returns false
.
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
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
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.
Converts date objects to formatted text
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
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.
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']
.
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']
.
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.
Since 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
).
Resize
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
null
value.
Return value: Null
Examples
Returns ['orange', 'purple', 'gray', null, null]
Returns ['orange', 'purple', 'gray', 'red', 'red']
Returns ['orange']
Reverse
Reverse(inputArray) -> Array<Any>
Function bundle: Core
Reverses the contents of the array in place.
Parameter
Example
Returns ['gray', 'purple', 'orange']
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']
Returns ['red', 'blue']
Returns ['orange', 'purple', 'gray', 'red', 'blue']
Returns ['blue']
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
: sortb
beforea
= 0
: keep the original order ofa
andb
< 0
: sorta
beforeb
Examples
returns ['$', 1, 'A', 'a']
Sort using a user defined function
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']
Returns [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 ]