Note: Arrays are only available in the scripts if the application registers the support for them. The syntax for using arrays may differ for the application you're working with so consult the application's manual for more details.

It is possible to declare array variables with the array identifier followed by the type of the elements within angle brackets.

Example:

  array<int> a, b, c;
  array<Foo@> d;

a, b, and c are now arrays of integers, and d is an array of handles to objects of the Foo type.

When declaring arrays it is possible to define the initial size of the array by passing the length as a parameter to the constructor. The elements can also be individually initialized by specifying an initialization list. Example:

  array<int> a;           // A zero-length array of integers
  array<int> b(3);        // An array of integers with 3 elements
  array<int> c(3, 1);     // An array of integers with 3 elements, all set to 1 by default
  array<int> d = {5,6,7}; // An array of integers with 3 elements with specific values

Multidimensional arrays are supported as arrays of arrays, for example:

  array<array<int>> a;                     // An empty array of arrays of integers
  array<array<int>> b = {{1,2},{3,4}}      // A 2 by 2 array with initialized values
  array<array<int>> c(10, array<int>(10)); // A 10 by 10 array of integers with uninitialized values

Each element in the array is accessed with the indexing operator. The indices are zero based, i.e. the range of valid indices are from 0 to length - 1.

  a[0] = some_value;

When the array stores handles the elements are assigned using the handle assignment.

  // Declare an array with initial length 1
  array<Foo@> arr(1);

  // Set the first element to point to a new instance of Foo
  @arr[0] = Foo();

Arrays can also be created and initialized within expressions as anonymous objects.

  // Call a function that expects an array of integers as input
  foo({1,2,3,4});

  // If the function has multiple overloads supporting different types with 
  // initialization lists it is necessary to explicitly inform the array type
  foo2(array<int> = {1,2,3,4});

Supporting array object

The array object supports a number of operators and has several class methods to facilitate the manipulation of strings.

The array object is a reference type even if the elements are not, so it's possible to use handles to the array object when passing it around to avoid costly copies.

Operators

= assignment

The assignment operator performs a shallow copy of the content.

[] index operator

The index operator returns the reference of an element allowing it to be inspected or modified. If the index is out of range, then an exception will be raised.

==, != equality

Performs a value comparison on each of the elements in the two arrays and returns true if all match the used operator.

Methods

uint length() const

Returns the length of the array.

void resize(uint)

Sets the new length of the array.

void reverse()

Reverses the order of the elements in the array.

void insertAt(uint index, const T& in value)
void insertAt(uint index, const array<T>& arr)

Inserts a new element, or another array of elements, into the array at the specified index.

void insertLast(const T& in)

Appends an element at the end of the array.

void removeAt(uint index)

Removes the element at the specified index.

void removeLast()

Removes the last element of the array.

void removeRange(uint start, uint count)

Removes count elements starting from start.

void sortAsc()
void sortAsc(uint startAt, uint count)

Sorts the elements in the array in ascending order. For object types, this will use the type's opCmp method.

The second variant will sort only the elements starting at index startAt and the following count elements.

void sortDesc()
void sortDesc(uint startAt, uint count)

These does the same thing as sortAsc except sorts the elements in descending order.

void sort(const less &in compareFunc, uint startAt = 0, uint count = uint(-1))

This method takes as input a callback function to use for comparing two elements when sorting the array.

The callback function should take as parameters two references of the same type of the array elements and it should return a bool. The return value should be true if the first argument should be placed before the second argument.

  array<int> arr = {3,2,1};
  arr.sort(function(a,b) { return a < b; });

The example shows how to use the sort method with a callback to an anonymous function.

Here's another example where the callback function is declared explicitly:

  bool lessForInt(const int &in a, const int &in b)
  {
    return a < b;
  }
  bool lessForHandle(const obj @ const &in a, const obj @ const &in b)
  {
    return a < b;
  }
  void sortArrayOfInts(array<int> @arr) { arr.sort(lessForInt); }
  void sortArrayOfHandles(array<obj@> @arr) { arr.sort(lessForHandle); }

int find(const T& in)
int find(uint startAt, const T& in)

These will return the index of the first element that has the same value as the wanted value.

For object types, this will use the type's opEquals or opCmp method to compare the value. For arrays of handles any null handle will be skipped.

If no match is found the methods will return a negative value.

int findByRef(const T& in)
int findByRef(uint startAt, const T& in)

These will search for a matching address. These are especially useful for arrays of handles where specific instances of objects are desired, and not just objects that happen to have equal value.

If no match is found the methods will return a negative value.

Script example

  int main()
  {
    array<int> arr = {1,2,3}; // 1,2,3
    arr.insertLast(0);        // 1,2,3,0
    arr.insertAt(2,4);        // 1,2,4,3,0
    arr.removeAt(1);          // 1,4,3,0

    arr.sortAsc();            // 0,1,3,4

    int sum = 0;
    for( uint n = 0; n < arr.length(); n++ )
      sum += arr[n];

    return sum;
  }