Legacy:Dynamic Array

Definition

An array is a series of variables stored together and references as one variable. You can also access individual elements of the array variable. It is often likened to a list – it could be a list of integers, a list of names, a list of strings, etcetera. You can even have arrays of structs and arrays of references.

A dynamic array is an array that can be lengthened or shortened to accomodate the number of elements in the array. Dynamic arrays support is implemented in UnrealScript starting with UnrealEngine2.

Dynamic arrays have advantages and disadvantages when compared to arrays with a fixed number of elements (for these, see Variable Syntax). Dynamic arrays cannot be replicated. However, they can be resized and they are faster than static arrays. Although this may seem strange, it's true - dynamic arrays can actually be accessed faster than static arrays. However, the difference is primarily academic, as both have an almost negligible access time.

Syntax

var/local array<type> ArrayName, ...;

The type can be any of the built-in or self-defined types (structs, enums, classes). After declaration the dynamic array is empty, i.e. the array's length is zero.

Note 1: UnrealEngine 2 does not bool support bool arrays. You can declare them, but they won't work. Use a byte array instead, it has the least memory usage per element. UnrealEngine 3 correctly supports bool arrays, though.

Note 2: Be careful when declaring a dynamic array of classes. The correct syntax for this is:

array<class<type> >

Note the space between the two closing angle brackets. If you don't put the space there, the parser will recognize it as the operator >> and report a syntax error.

To access a dynamic array use this syntax:

ArrayName[element number]

If you read an array element that doesn't exist because it's beyond the array's length, you'll get a null value (see below) and an "Accessed array out of bounds" warning is logged.

If you write to an array element that doesn't exist (yet) because the array is too short, the array will automatically increase its length. All new elements inserted between the former end of the array and the element you are writing to are initialized with their respective null element (zero, empty string or None, depending on the array's type). Note: Arrays of structs can only be extended that way when assigning an entire struct not only one property of the struct because only the first really assigns something to the array, while the second actually tries to access an object (not) stored in the array to modify one of its properties.

Note: You can't use a combination of dynamic and static arrays.
The declaration var array<string> StringArray[10]; will actually be compiled and used as a static array declared as var string StringArray[10];

Also declaring dynamic arrays of dynamic arrays won't work. Here you can use the same workaround as mentioned for static arrays in Variable Syntax.

Properties and Methods

Dynamic arrays behave a bit like objects. They have properties and methods to access and modify them.

UnrealEngine 2

UnrealEngine 2 provides the following properties and methods:

Length 

Returns the number of elements in the array, similar to ArrayCount(ArrayName) for static arrays. So, for example, if the array has no elements, ArrayName.Length will have a value of 0 (zero), if the array has 47 elements, ArrayName.Length will equal 47, and so on. You can assign a new length using the = operator. Increasing the length adds empty elements at the end of the array while preserving the existing elements. Decreasing the length removes only the last elements without changing the other ones.
Note: Only use the = operator to change the length! Don't pass the length property as an 'out' parameter to a function or operator. This specificly also includes operators like ++ or -=-.

Remove(position, number) 

Removes number elements from the array, starting at position. All elements before position and from position+number on are not changed, but the element indices change, i.e. the element formerly accessed through ArrayName[position+number] is accessed through ArrayName[position] after the removing.

Insert(position, number) 

Inserts number empty elements into the array at position. The indices of the following elements are increased by number in order to make room for the new elements.

UnrealEngine 3

In UnrealEngine 3, the following additional dynamic array methods are available:

Add(number) 

Adds number empty elements at the end of the array.

AddItem(value) 

Adds value as new element to the end of the array.

RemoveItem(value) 

Removes all occurances of value from the array. For example ar.RemoveItem(None); will remove all empty elements from the object array ar. To find out, how many elements were removed you need to compare the length of the array before and after this operation.

InsertItem(position, value) 

Inserts value as new element at index position.

Find(value) 

Does a linear search for value in the array and returns the first matching array index. If the value isn't found, the value INDEX_NONE (i.e. -1) is returned.

Find(property, value) 

This is a special version of the Find method for struct arrays. The property parameter is the name of the struct element value should be compared to. For example vectorArray.Find('X', 0.0) will return the first index with the X coordinate being zero. Again, a return value of INDEX_NONE signals that no matching element was found.

UnrealEngine 3 also allows dynamic arrays to be used as iterators in ForEach loops:

foreach arrayname(valuevariable)

foreach arrayname(valuevariable, indexvariable) 

The valuevariable needs to be of the same type as the array, the indexvariable must be of type int. Modifications to the value or index variables will not write through to the array or otherwise affect the iteration.
Note: The iteration will skip values if you use the Remove(i, n) or RemoveItem(v) methods on the array to remove any elements up to and including the current element. Even using the index version of the iterator and modifying the index variable according to the number of elements removed will not work. You will have to use an "oldskool" for loop to do this kind of work.

Dynamic Arrays as Config Variables

Dynamic arrays can be initialized from .ini files by adding the config keyword to their declaration. Given the following class...

class DynamicArrayTest extends Object
  config;
 
var config array<string> MyDynamicArray< SEMI >

...the corresponding .ini entries look as follows:

 [DynamicArrayTest.DynamicArrayTest]
 MyDynamicArray=first entry
 MyDynamicArray=second entry
 MyDynamicArray=third entry

Note the lack of array indices.

If you leave out the MyDynamicArray, like this:

 [DynamicArrayTest.DynamicArrayTest]

the result will be an empty MyDynamicArray, even if you have default values set in the class' defaultproperties block

Related Topics

• Variable Syntax
• Dynamic arrays in Legacy:Dynamic Array/UnrealEngine 1