Array

Array Class Reference

Basic usage

const var a = [];         // Declare an array
a[0] = 12;                // Set the element at position 0 to 12
a[1] = "Hello";           // Set the element at position 1 to "Hello"
Console.print(a.length);  // Print the length (in this case 2)
a.clear();                // Deletes all items from the array

If you have used another programming language before, this might look pretty familiar. Be aware that you can add / delete items from the array despite having it declared as const var . The "constness" just refers to the assignment, so you can't reassign this variable to another value.

Iterating over an array

Basically there are two ways of iterating (= going over each element in the array):

Range-based Loop	Index-based Loop
for(element in array)	for(i = 0; i < array.length; i++)
This is the preferred method, because it has a clearer syntax (and is faster). As long as you don't need to know the index of the element, it's recommended to use this method.	If you need the index of the current item in the loop (eg. because you iterate over multiple arrays at once), use this loop.

The index based loop construct is the only place where you can define anonymous variables (so that for(i = 0... doesn't throw a compile error).

Ownership & lifetime

An array is reference counted, which means that if you assign an array to another variable, it will use the same array.

const var a = [1, 5, 6];
const var b = a;

a[0] = 10;           // set the first element of a
Console.print(b[0]); // the first element of b will also be 10

Class methods

clear

Clears the array.

Array.clear()

This is a quick operation (the allocated storage space will not be freed), so you can use it in a realtime callback.

concat

Concatenates (joins) two or more arrays

Array.concat(var argumentList)

contains

Searches for the element in the array.

Array.contains(var elementToLookFor)

find

Returns the value of the first element that passes the function test.

Array.find(var testFunction, var optionalThisObject)

indexOf

Searches the array and returns the first index.

Array.indexOf(var elementToLookFor, int startOffset, int typeStrictness)

Return the index of the first occurence or -1 if the item can't be found.

const var a = [1, 5, 5];
a.indexOf(5); // will return 1
a.indexOf("5"); // will also return 1, the search is not type-strict.

insert

Inserts the given arguments at the firstIndex.

Array.insert(int firstIndex, var argumentList)

isArray

Checks if the given variable is an array.

Array.isArray(var variableToTest)

join

Joins the array into a string with the given separator.

Array.join(var separatorString)

This method is useful when you want to change the item list of some UI controls, for example a Combobox .

const var list = ["item1", "item2", "item3"];     // Creates a list of all available samplemaps
const var box = Content.addComboBox("box", 0, 0); // Creates a combobox
box.set("items", list.join("\n"));                // sets the list as items

The opposite of this method is String.split()

map

Creates a new array from calling a function for every array element.

Array.map(var testFunction, var optionalThisObject)

pop

Removes and returns the last element.

Array.pop()

push

Adds the given element at the end and returns the size.

Array.push(var elementToInsert)

If you know that you are going to add multiple elements, you can call Array.reserve() to preallocate the amount of elements and improve performance:

const var a = [];

// Uncomment this to see the performance improvement:
//a.reserve(100);

Console.start();
for(i = 0; i < 100; i++)
{
    a.push(5);
}
Console.stop()

pushIfNotAlreadyThere

Adds the given element at the end and returns the size.

Array.pushIfNotAlreadyThere(var elementToInsert)

remove

Removes all instances of the given element.

Array.remove(var elementToRemove)

removeElement

Removes the element at the given position.

Array.removeElement(int index)

reserve

Reserves the space needed for the given amount of elements.

Array.reserve(int numElements)

If you are going to populate this array in a realtime callback, you need to make sure that there is enough storage allocated in order to avoid reallocation. This method can be used to preallocate slots that can be filled later.

Be aware that this method will not change the Array.length property:

const var array = [];       // create a new array
array.reserve(128);         // allocate 128 items
Console.print(array.length) // will output 0;
array[64] = 190;            // this will not allocate
Console.print(array.length) // will print 65

This method will allocate enough memory to hold primitive values, but if you are going to store complex objects (arrays or objects), calling Array.reserve() will not prevent reallocation.

reverse

Reverses the order of the elements in the array.

Array.reverse()

sort

Sorts the array.

Array.sort()

This will sort the array using a sensible sort algorithm:

• Numbers will be sorted naturally,
• Strings will be sorted alphabetically
• Objects and arrays will not be sorted.

const var a = [1, 6, 4, 2, 1];
a.sort();

for(i in a)
    Console.print(i); 

// Result: 1, 1, 2, 4, 6

sortNatural

Sorts array of numbers, objects, or strings with "number in string" priority. Can also sort a combination of all types

Array.sortNatural()