array() | array(size,value=null)

Returns a new array of size elements filled with 'value'

If size is omitted it is assumed to be 0.

arrayappend(array, value)

Appends value to the end of an array.

arrayprepend(array, value)

Prepends value to the beginning of an array.

arrayadd(array, value)

Appended value to the end only if it doesn't already exist in the array.

arrayresize(array,size,value=null)

Resizes an array to size elements

If the array is smaller than size it will be truncated. If the new size is larger, value will be used for the new elements.

arrayextend(array, array2)

Appends array2 to the end of array.

This is different from arrayappend in that the array is added to the end, not added as an element

a1 = [1,2,3]
a2 = [4,5,6]
arrayadd(a1,a2)

a2 is now [1,2,3,4,5,6]

a1 = [1,2,3]
a2 = [4,5,6]
arrayappend(a1,a2)

a2 is now [1,2,3,[4,5,6]]

arrayfind(array, value)

Returns the index of value in array

Indexes for arrays start at 0.

If the value can't be found, null is returned.

arrayremoveindex(array, index)

Removes index from an array.

If the 'index' is out of bounds, then nothing happens.

a = [1,2,3,4]
arrayremoveindex(a,1)

a is now [1,3,4]

arrayfindremove(array, value)

Removes value from an array.

Only the first occurrence of value is removed.

If a value was removed then 1 is returned, otherwise 0 is returned.

arrayinsertbefore(array, index, value)

Insert value into an array before index

If index is 0 the value is place at the beginning of the array

If index is larger than the size of the array, the value is appended.

arrayinsertafter(array, index, value)

Insert value into an array after index

If index is less than 0 the value is place at the beginning of the array

If index is larger than the size of the array, the value is appended.

arrayfirst(array)

Returns the first element of an array

If the size of the array is 0, then null is returned.

This is the same as doing a?[0]

arraylast(array)

Returns the last element of an array

If the size of the array is 0, then null is returned.

This is the same as doing a?[sizeof(a)-1]

arrayremovefirst(array)

Removes the first element of an array

If the size of the array is 0, nothing is removed.

arrayremovelast(array)

Removes the last element of an array

If the size of the array is 0, nothing is removed.

arrayshuffle(array)

Randomly shuffles an array

arrayfilter(array, function)

Returns a new array that has been filtered with function

a2 = arrayfilter(a1, function(index, value) {

    if (value == "dead") {
        return false
    } else {
        return true
    }
})

If the function returns true, the value is kept, otherwise it is discarded. The original array is not modified.

arrayapply(array, function)

Returns an array after applying function to each element

a1 = [ "Dolores", "Ray" ]
a2 = arrayfilter(a1, function(value) {
    return value+" is cool"
})

a2[0] is now "Delores is cool"

a2[1] is now "Ray is cool"

The original `array` is not modified.

arraycount(array) | arraycount(array,value)

Returns the number of non-null elements in the array

If the second form is used, it returns the number of elements that match value

a = [ "Frank", "Ted", "Bill", null, null ]
n = arraycount(a)

n now equals 3

n = arraycount(a, null)

n now equals 2

n = arraycount(a, "Frank")

n now equals 1

arraysort(array[,func=null]) | arrayrsort(array[,func=null)

Sorts an array in place

a = [3,2,1]
arraysort(a)

a now equals [1,2,3]

a = [3,2.9,1]
arraysort(a)

a now equals [1,2.9,3]

a = ["ccc", "bbb", "aaa"]
arraysort(a)

a now equals ["aaa", "bbb", "ccc"]

a = ["ccc", null, "aaa"]
arraysort(a)

a now equals [null, "aaa", "ccc"]

a = ["ccc", [7,8,9], 50]
arraysort(a)

If func is provided, it will be called for each object in the array and expected to return the value to sort by.

function my_key(t) {
    return t.name
}
a = [ { name = "c" }, { name = "a" }, { name = "b"} ]
arraysort(a, my_key)   // is now [ { name = "a" }, { name = "b" }, { name = "c"} ]
arrayrsort(a, my_key)  // is now [ { name = "c" }, { name = "b" }, { name = "a"} ]

Sorting arrays with different types is undefined behavior.

Arrays