Array Variable
Array variables are added by NVSE 4. Arrays are similar to form lists but allow for far more powerful capabilities with much easier scripting. Arrays are simple to use, provided you switch to using Let instead of the vanilla 'set .. to ..', and if eval instead of simply 'if'.
An introduction to arrays is available.
An in-depth series of tutorials on array variables is also available.
Contents
Arrays Compared to Form Lists
- Arrays may store any data type in any combination, form lists only base forms or references.
- Form lists must be created in the GECK, arrays are created dynamically within scripts by letting a variable to a wide range of function that return different types of array.
- Regular arrays (array lists) are organized identically to form lists, the first item is always at index 0, and the last at (total size - 1).
- Map and String map arrays allow organization by user specified keys for each item.
- Arrays may be easily looped through using Foreach or While
- Both arrays and form lists can be searched using various functions.
- Form lists require complicated scripting to sort or copy. Arrays may be easily copied and sorted using a single function from a range of possiblities.
- Entries in a form list must be assigned to a variable via a function before they can be manipulated. Within NVSE expressions, or if using the Script Compiler Override, array entries may be manipulated directly using square brackets ([ ]).
- Arrays contents can be printed to the console with a single function for easy debugging, either from within a script or from the in game console.
Simple Example
Regular array, all keys are consecutive integers from 0:
array_var aBeatles ref rActor let aBeatles := Ar_List JohnREF, PaulREF, GeorgeREF, RingoREF let rActor := aBeatles[0] ; * rActor == JohnREF if eval aBeatles[2] == GeorgeREF ; element 2 (third) is GeorgeREF endif let aBeatles[1] := SunnyREF ; * change element 1 (second) to SunnyREF ; aBeatles array now contains: JohnREF, SunnyREF, GeorgeREF, RingoREF
Map array, keys may be any unique float:
array_var MagicNumberToString string_var my_string let MagicNumberToString := Ar_Construct "map" let MagicNumberToString[2] := "Upper body" let MagicNumberToString[5] := "Weapon" ; MagicNumberToString contains: 2::"Upper body", 5::"Weapon" let my_string := MagicNumberToString[5] ; * my_string == "Weapon"
String map array, all keys are unique strings:
array_var StringToMagicNumber int MyInt let StringToMagicNumber := Ar_Construct "stringmap" let StringToMagicNumber["Upper body"] := 2 let StringToMagicNumber["Weapon"] := 5 ; StringToMagicNumber contains: "Upper body"::2, "Weapon"::5 let MyInt := StringToMagicNumber["Weapon"] ; * MyInt == 5
Checking if an Array is Initialized
If an array hasn't been set to anything, or if it has been set to Ar_Null, it is considered unitialized. In this state, the array's value is zero. Therefore, one can tell if an array is initialized like so:
array_var aTest if aTest ;"if eval aTest" would do the same. DoCode endif
Or, using Ar_Size, which returns -1 if the array is uninitialized:
array_var aTest int iSize let iSize := ar_Size aTest if iSize > 0 ;just in case, an array with 0 elements is also ignored. DoCode endif
Array Functions
- Creation: Ar_Construct, Ar_List, Ar_Map, Ar_Range
- Modification: Ar_Append, Ar_Insert, Ar_InsertRange, Ar_Resize, Ar_Erase, Ar_Cat
- Sorting: Ar_Sort, Ar_SortAlpha, Ar_CustomSort, Ar_SortEditor
- Copying: Ar_Copy, Ar_DeepCopy
- Searching: Ar_Find, Ar_HasKey, Ar_First, Ar_Last, Ar_Next, Ar_Prev, Ar_Keys
- Debugging: Ar_Dump, Ar_DumpID
- More: Array Functions
