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.

Original Blitz arrays are one-dimensional. The Original language does not accept comma-separated dimensions in a Dim declaration or array access. Extended mode adds fixed-size square-bracket arrays with multiple dimensions; see Multidimensional Arrays.

Declaration

Dim arrayName[TypeTag](upperBound)

The 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". 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.

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 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 map%(0)

Function ResizeMap(lastIndex%)
    Dim map(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

Extended mode also supports fixed-size square-bracket arrays, including the language's multidimensional array form. Their bounds, storage contexts, indexing rules, and restrictions are documented separately in Multidimensional Arrays.