Arrays

Extended arrays may store :Long and :Double elements. See Long and Double.

An array is an indexed collection whose elements all have the same type. The Dim statement creates or resizes an array.

A Dim array can have several dimensions: give one upper bound for each, separated by commas, and one index for each when you use an element (see Multiple dimensions). Blitz also has fixed-size square-bracket arrays, declared like variables (Local slots[7], see Dim), which take a single dimension in Original mode; Extended mode allows several, see Multidimensional Arrays.

Declaration

Dim arrayName[TypeTag](upperBound[, upperBound...])

Each value in parentheses is an inclusive upper bound. Array indices begin at zero, so an upper bound of 10 creates eleven elements numbered 0 through 10.

An upper-bound expression is evaluated whenever Dim executes. It can therefore use values calculated at runtime:

tileCount% = 64
Dim tiles%(tileCount - 1)

Element types

An array may contain Integer, Float, String, or custom-Type values. If its type is omitted, the array contains Integers.

The named annotations in the Modern column require Dialect "modern", or Extended mode in a file with no Dialect line. See Basic Data Types for the equivalent type tags and annotations.

Reading and writing elements

Supply the element's index in parentheses. The same syntax reads an element in an expression or selects it as the destination of an assignment:

Dim scores%(4)

scores(0) = 100
scores(1) = scores(0) + 25
Print scores(1)

The index must be within the array's declared bounds.

Multiple dimensions

Give one upper bound per dimension to make a grid, such as a tile map, and one index per dimension to read or write an element:

Dim grid%(63, 47)    ; 64 columns by 48 rows

grid(10, 5) = 3
Print grid(10, 5)

The bounds are counted separately, so grid%(63, 47) holds 64 × 48 elements. The first Dim fixes how many dimensions the array has.

Custom-Type arrays

A custom-Type array stores object references. Its elements initially contain Null and must be assigned an instance before a Field is accessed:

Type Player
    Field name$
    Field health%
End Type

Dim players.Player(7)

players(0) = New Player
players(0)\name = "Ranger"
players(0)\health = 100

Array storage does not own the referenced instances. Resizing the array releases its stored references but does not call Delete on the objects. See Custom Types for object lifetime rules.

Resizing arrays

Executing Dim again for an existing array discards all of its current contents and creates new storage. The element type and the number of dimensions cannot change.

Dim values%(10)
values(0) = 100

Dim values(20)    ; 21 elements, all reset to zero

An array can be resized inside a Function, but it must first be declared with the same type in the main program:

Dim tiles%(0)

Function ResizeTiles(lastIndex%)
    Dim tiles(lastIndex)
End Function

New Integer and Float elements are zero, new String elements are empty, and new custom-Type elements are Null.

Extended fixed-size arrays

In Extended mode, fixed-size square-bracket arrays can have more than one dimension. Their bounds, storage contexts, indexing rules, and restrictions are documented separately in Multidimensional Arrays.