Array

An array is a container that holds a list of values of a single type.

property Array<Int> intArray: [1, 2, 3]
property Array<Item> itemArray
property Array<CustomButton> buttons

Arrays can also be written using the following shorthand syntax. In both cases the declarations behave identically.

property Int[] intArray: [1, 2, 3]
property Item[] itemArray
property CustomButton[] buttons

Array can store value types, such as Int, String or Json values, or elements like Item and Rectangle.

Only compatible types can be stored in an array. It is possible to put different elements in an array if they all inherit from a common ancestor. The following works as all elements inherit from Item.

// Will work as all inherit from the named type of Item
property Array<Item> polyArray: [Item{}, Image{}, Rectangle{}]

// Will not work as Item does not inherit from Image
property Array<Image> polyArray: [Item{}, Image{}]

This will however mean type specific property access is not possible without a cast.

Item as root {
    property Array<Item> polyArray: [testItem, testRect]

    Item as testItem {}
    Rectangle as testRect {
        width: 200; height: 200
        color: #green
    }
}

on start {
    // Illegal access as type Item has no color  
    // property. This code will cause an error
    root.polyArray[1].color = #red
    
    // Valid after casting
    var i = root.polyArray[1] cast Rectangle
    i.color = #red
}

property Int lengthread only

The number of values in the array.

function clear()

This method clears all elements from the array, leaving it empty.

Rectangle as root {
    color: #white
    property Array<Int> intArray: [1, 2, 3, 4]
}

on start {
    System.log(root.intArray.length) // prints '4'
    root.intArray.clear()
    System.log(root.intArray.length) // prints '0'
}

function append(type value)

Item as root {
    property Array<Int> numberArray: [1, 2, 3]
}

on start {
    root.numberArray.append(42)
    for(var i = 0; i < root.numberArray.length; i++) {
        System.log(root.numberArray[i])
    }
    // prints '1, 2, 3, 42'
}

function prepend(type value)

Item as root {
    property Array<Int> numberArray: [1, 2, 3]
}

on start {
    root.numberArray.prepend(42)
    for(Int i=0; i < root.numberArray.length; i++) {
        System.log(root.numberArray[i])
    }
    // prints '42, 1, 2, 3'
}

function insert(Int index, type value)

This method is used to insert a value at a specific index. It is the companion method to removeAt(). An existing value at that index and all values after that will be moved one index place higher (to the right) to make room for the new value.

Note: The index starts at 0

Item as root {
    property Array<Int> numberArray: [1, 2, 3]
}

on start {
    root.numberArray.insert(1, 42)
    for(Int i=0; i < root.numberArray.length; i++) {
        System.log(root.numberArray[i])
    }
}

function removeAt(Int index)

This method is used to remove a value at a specific index. It is the companion method to insert(). All values after that will be moved one index place lower (to the left) to fill the room made by removing the old value.

Item as root {
    property Array<Int> numberArray: [1, 2, 3, 4]
}

on start {
    root.numberArray.removeAt(2)
    for(Int i=0; i < root.numberArray.length; i++) {
        System.log(root.numberArray[i])
    }
    // prints '1, 2, 4' 
}

function removeOne(type value)

This method removes the first occurrence of value in the array.

function removeFirst()

This method removes the first entry in the array.

function removeLast()

This method removes the last entry in the array.

function removeAll(type value)

This method removes the all occurrences of value in the array.

function indexOf(type value) → Int

Returns the index position of the first occurrence of the value in this array. Returns -1 if the value is not found.

optional Int fromIndex

Begin searching from the specified index, instead of the start of the array.

Item as root {
    property Array<Int> numberArray: [1, 2, 3, 4, 2]
    property Array<Item> itemArray: [testItem, exampleItem]
    Item as testItem {}
    Item as exampleItem {}
}

on start {
    // Prints 2 (index)
    System.log(root.numberArray.indexOf(3))
    // Prints 4 (index)
    System.log(root.numberArray.indexOf(2, fromIndex: 2))
    // Prints -1 (not found)
    System.log(root.numberArray.indexOf(42)) 
    // Prints 1 (index)
    System.log(root.itemArray.indexOf(exampleItem))
}

function lastIndexOf(type value) → Int

Returns the index position of the last occurrence of the value in this array. Returns -1 if the value is not found.

optional Int fromIndex

Begin searching from the specified index, instead of the end of the array.

Item as root {
    property Array<Int> numberArray: [1, 2, 3, 4, 2]
}

on start {
    // Prints 4 (index)
    System.log(root.numberArray.lastIndexOf(2))
}

function contains(type value) → Bool

This method searches the array for the passed ValueType. It returns true if one or more instances are found, or false if none are found.

Item as root {
    property Array<Int> numberArray: [1, 2, 3, 4]
}

on start {
    // Prints true
    System.log(root.numberArray.contains(2))
    // Prints false
    System.log(root.numberArray.contains(42))
}

function sort()

function sort(function(type, type)->Bool lessThan)

function sorted() → Array

function sorted(function(type, type)->Bool lessThan) → Array

Sorts the array content in ascending order.

The parameterless version sort is only defined for types that have a "natural" order and have the < operator defined. That is, Int, Float, String, Url, and DateTime.

To sort other types, or to define your own sort order, you provide a lessThan function callback. The lessThan function is called repeatedly for pairs of values in the array. Your implementation should return true if the first value is "less than" the second value and should appear before it in the array.

The sort() functions modify the existing array. The sorted() functions return a sorted copy of the array without modifying the original.

The following example sorts the array in descending order.

Int[] data = [4, 98, 19, 7, 12]
data.sort(function(Int lhs, Int rhs)->Bool {
    return lhs > rhs
})
// [98, 19, 12, 7, 4]

function reversed() → Array

Returns a copy of the array with its contents reversed. The original array is unmodified.