Introduction to OBSE arrays

Foreword

This article presents the basics of OBSE arrays. Much of the text comes straight from the OBSE docs.

Arrays

An array is a collection of related information put together in a list-like structure.

Being a list, an array may hold many values, as opposed to regular script variables that hold only one information.

Some examples of everyday lists that could be stored in arrays:

Shopping list	Agenda	Personal data
- Bread	08:30 - Sign in, Coffe	Name: Adoring Fan
- Butter	09:00 - Introduction	Date of birth: Morningstar 2, 415
- Milk	09:30 - Presentation A	Age: 19
- Eggs	10:30 - Coffe break	Address: Arena District, IC
	11:00 - Presentation B	Race: Wood Elf
		ReferenceID: ArenaFan1ref

Array keys and values

Each element of the array is composed of a Key and a Value.

Key

The Key identifies the element and must be unique within an array.

An array key may be a number or a string, but all the keys in an array must be of the same type.

Arrays are ordered by key, in ascending order.

The key is represented within brackets, e.g., MyArray[0].

Value

Value is the information stored in the array element.

The value may be of any type: a string, a number, a FormID (base object or reference) or another array.

Any mix of value types may be stored in the same array.

Array types

There are three types of arrays, depending on the key used: Array, Map or StringMap.

Array

The "Array" type of array uses integers as keys.

The first element must have key = 0 and subsequent keys must be the next integer: 1, 2, 3, 4 etc.

There must be no gaps in the key sequence.

If an element is inserted or removed from the array, the keys are renumbered to comply with the above rules.

The Shopping List example would look like this when stored in an Array

Key	Value
0	Bread
1	Butter
2	Milk
3	Eggs

Quote from the OBSE doc:

1. Array: An Array behaves like arrays in most programming languages: the key is an unsigned integer starting at zero, and there are no gaps between elements. (In other words, if an element exists at indexes 1 and 3 then an element necessarily exists at 0 and 2). Attempting to access an element using a key which is greater than the highest key in the array results in an error. The only exception to this rule is during assignment: it is okay to assign a value to the key which is one greater than the highest key in the array.

Map

The Map array uses numbers as keys.

Keys may be any number, including negative and floating point numbers

The Agenda example would look like this when stored in a Map array:

Key	Value
8.5	Sign in, Coffe
9.0	Introduction
9.5	Presentation A
10.5	Coffe break
11.0	Presentation B

Quote from the OBSE doc:

2. Map: A Map associates numeric keys with values. Unlike an Array, a Map allows negative and floating point numbers to be used as keys and allows gaps to exist between elements.

StringMap

The StringMap array uses strings as keys.

The Personal Data example would look like this when stored in an StringMap array:

Key	Value	Value Type
Name	Adoring Fan	String
Date of birth	Morningstar 2, 415	String
Age	19	Float
Address	Arena District, IC	String
Race	Wood Elf	Ref
ReferenceID	ArenaFan1ref	Ref

• Note: Although only this last example has a mixture of value types, arrays of ANY type may have mixed value types.

Quote from the OBSE doc:

3. StringMap: Like a Map, except the keys are strings. Keys are case-insensitive, so array[INDEX] and array[index] both refer to the same value. There is no practical limit on the length of the strings used as keys. StringMaps can be used to simulate C-style structs by associating named properties with data values.

Declaring and initializing arrays

Arrays must be declared as an array_var variable, e.g., "array_var MyArray"

An array_var must be initialized before it can be used in expressions, either by

1. Explicitly initializing it using ar_Construct

When initializing an array with ar_Construct, the type of array must be provided as the argument:

let MyArray := ar_Construct array

let MyArray := ar_Construct map

let MyArray := ar_Construct stringmap

2. Assigning the value of another array_var to it

In this case MyArray will be of the same type of SomeArray (actually, both refer to the same array)

let SomeArray := ar_Construct array

Let MyArray := SomeArray

3. Assigning it the return value of a command returning an array such as GetItems.

Let MyArray := GetItems

Populating arrays

Arrays are populated by assigning values to its elements.

An array element is identified by the array name followed by the element key within brackets.

The keys, of course, must comply with the type of array:

let MyArray := ar_Construct array

Let MyArray[0] := 123

Let MyArray[1] := 456

Let MyArray[2] := 789

let MyArray := ar_Construct map

Let MyArray[-1.5] := 123

Let MyArray[2.5] := 456

Let MyArray[3] := 789

let MyArray := ar_Construct stringmap

Let MyArray["Cost"] := 123

Let MyArray["Qty"] := 456

Let MyArray["Taxes"] := 789

Accessing array elements

Using the data stored in arrays usually requires that you copy the information into a 'normal' script variable because array elements cannot be passed directly to most commands as arguments.

The Let statement is array-aware and is the most common way of accessing array elements

float MyFloat

. . .

Let MyFloat := MyArray["PosX"]

Player.setpos x MyFloat

ref MyRef

. . .

Let MyRef := MyArray["ReferenceID"]

MyRef.Kill

string_var MyString

. . .

Let MyString := MyArray[3.7]

MessageBoxEX "The element text is: %z" MyString

In all examples up to here, keys were explicitly coded, but they may also be in a variable and the variable itself going within the brackets:

string_var MyString

. . .

Let MyString := "Item value"

Let MyArray[MyString] := 300

short MyShort

. . .

Let MyShort := 3

Let MyArray[MyShort] := "Text"

Which is very handy to . . .

Walking an array

Walking an array means going over each element of the array, one at a time.

OBSE provides functions to do exactly that: ForEach and While loops

ForEach

ForEach loops iterate over the elements of an array.

array_var item

short MyShort

string_var MyString

. . .

ForEach item <- MyArray

Let MyShort := item["key"]

Let MyString := item["value"]

MessageEX "The element %g is: %z" MyShort MyString

Loop

At each iteration, "item" is initialized with two elements:

• "key", which holds the key of the current element
• "value", which holds the value associated with that key

Therefore, as in the example above, within a ForEach loop you can access both fields via item["key"] and item["value"].

NOTE: In the example, the key is copied to a Short, which implies that MyArray is either an Array or a Map that has only integers as keys.

While

While loops are handy for handling Arrays because the keys are known in advance and are consecutive (0,1,2,3, ...)

The same example as above using a While loop:

short MyIndex

string_var MyString

. . .

Let MyIndex := 0

While MyIndex < ar_size MyArray

Let MyString := MyArray[MyIndex]

MessageEX "The element %g is: %z" MyIndex MyString

MyIndex += 1

Loop

Notice that with while loops, you have to increase the index yourself, as opposed to ForEach loops that automatically go to the next element.

A somewhat different (perhaps more elegant) way of increasing the index

short MyIndex

string_var MyString

. . .

Let MyIndex := -1

While (MyIndex += 1) < ar_size MyArray

Let MyString := MyArray[MyIndex]

MessageEX "The element %g is: %z" MyIndex MyString

Loop

While loops also allows for walking Arrays backward:

short MyIndex

string_var MyString

. . .

Let MyIndex := ar_size MyArray

While (MyIndex -= 1) >= 0

Let MyString := MyArray[MyIndex]

MessageEX "The element %g is: %z" MyIndex MyString

Loop

Some final, miscellaneous notes

• All elements within an array must have the same type of key.
• References cannot be used as array keys.
• An array can contain any mix of types for its values.
• As array elements may contain any type of data, it is the script's responsibility to know which is which, so you don't try to assign a string to a ref variable.
• OBSE keeps track of the number of references to each array and destroys the array when no references to it remain. This makes it unnecessary for scripts to worry about destroying arrays explicitly.
• ForEach and While loops both define structured blocks in the same way that If and Endif or Begin and End do. Every While or ForEach in a script must be matched by exactly one Loop command.
• Category:Array Functions (OBSE) has a list of OBSE array functions.