Array Variable

From GECK
(Redirected from Array)
Jump to: navigation, search

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.

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

See Also