Arrays (Papyrus)

Description

Arrays are special kinds of variables that can hold more then one value of the same type. You select which value you want via a numerical index that ranges from zero to the length of the array, minus one.

Declaring Arrays

 float[] myFloatArray
 ObjectReference[] myObjectArray = new ObjectReference[10]

myFloatArray specifies an empty array of floats. It has a length of 0, and is equal to None. myObjectArray also starts that way, except it is an array of ObjectReference objects. It is then assigned a new array of ObjectReference objects, with 10 elements in it (all of which start with the default value of None)

Note that you cannot have an array of arrays, or a multi-dimensional array.

You can, of course, make an property that is an array. The editor will show a special UI for it that allows you to add, remove, and re-arrange the array items inside it.

Example:

 Weapon[] Property MyWeapons Auto

The new call must be done inside a function. You cannot use it on an object variable outside of a function. If you want a variable to start with an empty array, then you can make the array inside the OnInit event.

Function Parameters

To accept an array as a parameter to a function, use the same syntax as for declaring an array.

Example:

 Function MyArrayFunction(int[] myArray, bool someOtherParameter)
 EndFunction

Returning from Function

To return an array from a function, again, use the same syntax.

Example:

 int[] Function MyReturnArrayFunction()
   int[] someArray = new int[10]
   return someArray
 endFunction

Creating Arrays

To create an array, use the "new" keyword, followed by the array's element type, and the size of the array in brackets. The array size must be an integer between 1 and 128 - and cannot be a variable. In other words, the size of the array must be set at compile time. Every element in the array will be set to the element's default value, be that 0, false, "", or None.

Example:

 new bool[5]
 new Weapon[25]

Usually you'll be assigning these directly to new array variables, but if a function wants an array, you can make the new array in the function call, like so:

Example:

 MyArrayFunction(new int[20])

Getting/Setting Elements

To get a single value from an array, or to set it, use brackets with the index of the element you want between them after the variable name. The index can be an integer variable, raw integer, or the result of an expression. The range of valid values is from 0 (for the first element) to the length of the array, minus 1.

Example:

 myArray[20] = newValue
 someRandomValue = myArray[currentIndex]
 myArray[i * 2] = newValue

If the array elements are other scripts, you can access properties and functions in the same way.

Example:

 DoorArray[currentDoor].Lock()
 objectXPos = ObjectArray[currentObject].X

Note that, since arrays are passed and assigned by reference, that any modifications to an array's elements will be reflected in any other variables looking at that array.

Getting Length

You can easily get the length of any array by calling the length property on it. If you assign None to an array, the length will be 0.

Example:

 int ArrayLength = myArray.Length

Assigning/Passing Arrays

Assigning one array to another array, or passing an array to a function, is done just like any other variable. However, note that arrays are passed/assigned by reference, just like objects. In other words, if you assign one array to another, both are looking at the same array - and modifications made to one, will be reflected in the other.

Example:

 int[] Array1 = new int[5]
 int[] Array2 = Array1     ; Array1 and Array2 now look at the same array!
 Array1[0] = 10
 Debug.Trace(Array2[0])    ; Traces out "10", even though you modified the value on Array1

Casting Arrays

Arrays can only be cast to strings, or bools. If you cast an array to a string, it will put each element in the array inside brackets, seperated by commas. If the array is especially long, it may trim the string a little early and put an ellipsis on the end. If you cast an array to a bool, it will be true if the length is non-zero, and false if the length is zero. You cannot cast an array of one type to an array of a different type, even if the elements would successfully cast.

Example:

 Debug.Trace(MyArray)    ; Traces out "[element1, element2, element3]" or "[element1, element2, ...]" if the array is too large
 if (MyArray)
   Debug.Trace("Array has at least one element!")
 else
   Debug.Trace("Array has no elements!")
 endIf

Common Tasks

Doing Something to Every Element

Frequently you may want to do something to every element in an array. This is easily done by setting up a while loop with a counter, and then doing something to each element, like so:

Example:

 Function DisableAll(ObjectReference[] objects)
   int currentElement = 0
   while (currentElement < objects.Length)
     objects[currentElement].Disable()
     currentElement += 1
   endWhile
 EndFunction

Note that the while loop will go as long as the element is less than the length of the array. This is because the valid elements are zero to length minus one. If you were to make a while loop using "<=" you would error on the last element, because you would be trying to get an element one past the end of the array.