array<T> class built-in

Dynamic array of elements of type T

A reference type, so assigning a handle shares the same array, while the = operator copies the elements. Elements are accessed by zero-based index, see array::length for the number of elements. Can be created from an initialization list, e.g. array<int> a = {1, 2, 3};, and T[] is a shorter way to write array<T>. Elements of object types must have a default constructor.

Constructors

array<T>()
Creates an empty array
array<T>(uint length) explicit
Creates an array with the given number of default-initialized elements
array<T>(uint length, const T&in value)
Creates an array with the given number of copies of a value

Funcdefs

funcdef bool less(const T&in if_handle_then_const a, const T&in if_handle_then_const b)
Comparison callback for array::sort()

Functions

bool empty() const C++
Returns true if the array has no elements, same as array::isEmpty()
int find(const T&in if_handle_then_const value) const
Finds the first element equal to a value
int find(uint startAt, const T&in if_handle_then_const value) const
Finds the first element equal to a value, starting at the given index
int findByRef(const T&in if_handle_then_const value) const
Finds the first element that is the given object
int findByRef(uint startAt, const T&in if_handle_then_const value) const
Finds the first element that is the given object, starting at the given index
void insertAt(uint index, const T&in value)
Inserts an element at the given index
void insertAt(uint index, const array<T>& arr)
Inserts all elements of another array at the given index
void insertLast(const T&in value)
Appends an element to the end of the array
bool isEmpty() const C++
Returns true if the array has no elements
void removeAt(uint index)
Removes the element at the given index
void removeLast()
Removes the last element
void removeRange(uint start, uint count)
Removes a range of elements
void reserve(uint length)
Preallocates memory for the given number of elements
void resize(uint length)
Changes the number of elements
void reverse() C++
Reverses the order of the elements
void sort(const less&in less, uint startAt = 0, uint count = uint(-1))
Sorts elements using a custom comparison function
void sortAsc()
Sorts the elements in ascending order
void sortAsc(uint startAt, uint count)
Sorts a range of elements in ascending order
void sortDesc()
Sorts the elements in descending order
void sortDesc(uint startAt, uint count)
Sorts a range of elements in descending order

Operators

array<T>& opAssign(const array<T>&in) =
Replaces the content with copies of the elements of another array
bool opEquals(const array<T>&in) const ==
Returns whether both arrays have equal elements
T& opIndex(uint index) []
Accesses the element at the given index
const T& opIndex(uint index) const []
Reads the element at the given index

Properties

uint length
Number of elements in the array

Constructor documentation

array::array<T>()

Creates an empty array

Used by {a, b, c} syntax, the elements are taken in the listed order.

array::array<T>(uint length) explicit

Creates an array with the given number of default-initialized elements

Parameters
length Number of elements

Elements of object types are created with their default constructor.

array::array<T>(uint length, const T&in value)

Creates an array with the given number of copies of a value

Parameters
length Number of elements
value Value every element is set to

Funcdef documentation

funcdef bool array::less(const T&in if_handle_then_const a, const T&in if_handle_then_const b)

Comparison callback for array::sort()

Parameters
a First element
b Second element
Returns true if a should be placed before b

Function documentation

int array::find(const T&in if_handle_then_const value) const

Finds the first element equal to a value

Parameters
value Value to look for
Returns Index of the first matching element, or -1 if not found

Elements of object types are compared with opEquals or opCmp, if the type has neither, a script exception is raised. Use array::findByRef() to look for a specific object instead.

int array::find(uint startAt, const T&in if_handle_then_const value) const

Finds the first element equal to a value, starting at the given index

Parameters
startAt Index where the search begins
value Value to look for
Returns Index of the first matching element, or -1 if not found

Elements of object types are compared with opEquals or opCmp, if the type has neither, a script exception is raised.

int array::findByRef(const T&in if_handle_then_const value) const

Finds the first element that is the given object

Parameters
value Object to look for
Returns Index of the first matching element, or -1 if not found

Compares object identity instead of value, so it works for any type and finds only the exact instance. For arrays of handles, pass a handle to the object to look for.

int array::findByRef(uint startAt, const T&in if_handle_then_const value) const

Finds the first element that is the given object, starting at the given index

Parameters
startAt Index where the search begins
value Object to look for
Returns Index of the first matching element, or -1 if not found

Compares object identity instead of value.

void array::insertAt(uint index, const T&in value)

Inserts an element at the given index

Parameters
index Position of the new element
value Value to insert

Elements from index onward move one position up. An index greater than array::length raises a script exception, an index equal to it appends.

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

Inserts all elements of another array at the given index

Parameters
index Position of the first inserted element
arr Array whose elements are copied in

An index greater than array::length raises a script exception. The array may also be inserted into itself.

void array::insertLast(const T&in value)

Appends an element to the end of the array

Parameters
value Value to append

void array::removeAt(uint index)

Removes the element at the given index

Parameters
index Index of the element to remove

Following elements move one position down. An index equal to or greater than array::length raises a script exception.

void array::removeLast()

Removes the last element

Raises a script exception if the array is empty.

void array::removeRange(uint start, uint count)

Removes a range of elements

Parameters
start Index of the first element to remove
count Number of elements to remove

A start greater than array::length raises a script exception. A count reaching past the end removes everything from start to the end.

void array::reserve(uint length)

Preallocates memory for the given number of elements

Parameters
length Number of elements to make room for

Doesn't change array::length, it only avoids repeated reallocation when many elements are added later. A value smaller than the current capacity does nothing.

void array::resize(uint length)

Changes the number of elements

Parameters
length New number of elements

Elements are removed from or added to the end, new elements are default-initialized.

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

Sorts elements using a custom comparison function

Parameters
less
startAt Index of the first element to sort
count Number of elements to sort, by default all up to the end

The first argument is a function matching array::less, that returns true if its first argument should come before the second one. The function must not modify the array. The range is cut at the end of the array, a startAt at or past the end raises a script exception. The order of elements that compare as equal isn't preserved.

void array::sortAsc()

Sorts the elements in ascending order

Elements of object types must implement opCmp, otherwise a script exception is raised. Null handles are placed first. Use array::sort() for a custom order.

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

Sorts a range of elements in ascending order

Parameters
startAt Index of the first element to sort
count Number of elements to sort

Elements of object types must implement opCmp. A range that doesn't fit into the array raises a script exception.

void array::sortDesc()

Sorts the elements in descending order

Elements of object types must implement opCmp, otherwise a script exception is raised.

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

Sorts a range of elements in descending order

Parameters
startAt Index of the first element to sort
count Number of elements to sort

Elements of object types must implement opCmp. A range that doesn't fit into the array raises a script exception.

Operator documentation

array<T>& array::opAssign(const array<T>&in) =

Replaces the content with copies of the elements of another array

The array is resized to match the other one. Handles are copied as handles, so they keep pointing to the same objects.

bool array::opEquals(const array<T>&in) const ==

Returns whether both arrays have equal elements

Arrays are equal if they have the same length and every pair of elements at the same index is equal. Elements of object types are compared with opEquals or opCmp.

T& array::opIndex(uint index) []

Accesses the element at the given index

Parameters
index Zero-based index of the element

An index equal to or greater than array::length raises a script exception.

const T& array::opIndex(uint index) const []

Reads the element at the given index

Parameters
index Zero-based index of the element

An index equal to or greater than array::length raises a script exception.

Property documentation

uint array::length

Number of elements in the array

Setting it resizes the array, the same as array::resize().