Click here to read a furthur explanation of multi-dimensional arrays
Click here to read details about arrays used in BlitzBASIC

Explanation of arrays

Arrays are special 'groups' of variables of the same type (%,#,$ etc.) that are related in some way.

Each array element can hold a value of some kind. What this value means is dependent on how you want to use it.

Arrays help the programmer save time by allowing him to not have to type a lot of redundant code. Let's say for example that you were writing a game that had a hundred characters in it. Each character has an X and Y position.
You could create 200 variables the long way to store each of the characters positions:

Player1X = ? 
Player1Y = ? 
Player2X = ? 
Player2Y = ? 
Player3X = ? 
Player3Y = ? 
etc... 

Or you could simply just create a 100 element array that holds both of those values (two-dimensional) for you:

Dim PlayerPos(100, 2)

The first value in the array PlayerPos(thisvalue, 2) is the number of characters in your game (you could think of them as rows).
The second value in the array PlayerPos(100, thisvalue) contains the X and Y positions for each character (you could think of them as columns).

This can basically be thought of as a grid or table like this:

Let's say you wanted to move character 46 to position 32,143. You would do so by doing this:

PlayerPos(46,1) = 32 ;the X value 
PlayerPos(46,2) = 143 ;the Y value 

How is this different than doing it the following 'standard' way?:

Player46X = 32
Player46Y = 143

Because by using the array, you don't have to know which character you are actually setting.  This will make more sense in the following example:

Let's say you have an array that holds the names of your 10 favorite films.  We need just a simple one-dimensional array to do this.

Dim fav_film$(10)
fav_film$(1) = "Alien"
fav_film$(2) = "Rocky"
fav_film$(3) = "Raiders of the lost ark"
fav_film$(4) = "The Wizard of Oz"
fav_film$(5) = "The Texas chainsaw massacre"
fav_film$(6) = "Titanic"
fav_film$(7) = "Goonies"
fav_film$(8) = "Return of the Jedi"
fav_film$(9) = "Never Ending Story"
fav_film$(10) = "Overboard"

You can then use an 'index' number to access any of the array variables (elements) you need, such as:

num = Input("Enter a number between 1 and 10")
Print "My number " + num + " favorite film is " + fav_film$(num)

Depending on what number the user typed in, the program displays the associated film.  Notice that this wouldn't be possible if we'd stored all the film names in separate variables.  We don't know which number the user is going to type in, so using an array makes sense.

Of course, if we really wanted to try it without an array, we would have had to write something like this:

fav_film1$ = "Alien"
fav_film2$ = "Rocky"
fav_film3$ = "Raiders of the lost ark"
fav_film4$ = "The Wizard of Oz"
fav_film5$ = "The Texas chainsaw massacre"
fav_film6$ = "Titanic"
fav_film7$ = "Goonies"
fav_film8$ = "Return of the Jedi"
fav_film9$ = "Never Ending Story"
fav_film10$ = "Overboard"

num = Input("Enter a number between 1 and 10")
If num = 1 Then Print "My number 1 favorite film is " + fav_film1$
If num = 2 Then Print "My number 2 favorite film is " + fav_film2$
If num = 3 Then Print "My number 3 favorite film is " + fav_film3$
If num = 4 Then Print "My number 4 favorite film is " + fav_film4$
If num = 5 Then Print "My number 5 favorite film is " + fav_film5$
If num = 6 Then Print "My number 6 favorite film is " + fav_film6$
If num = 7 Then Print "My number 7 favorite film is " + fav_film7$
If num = 8 Then Print "My number 8 favorite film is " + fav_film8$
If num = 9 Then Print "My number 9 favorite film is " + fav_film9$
If num = 10 Then Print "My number 10 favorite film is " + fav_film10$

As you can see, you have to write an 'If num = ? Then Print...' line for every single film!

Take a look at the difference:

Using an array:

num = Input("Enter a number between 1 and 10")
Print "My number " + num + " favorite film is " + fav_film$(num)

Not using an array:

num = Input("Enter a number between 1 and 10")
If num = 1 Then Print "My number " + num + " favorite film is " + fav_film1$
If num = 2 Then Print "My number " + num + " favorite film is " + fav_film2$
If num = 3 Then Print "My number " + num + " favorite film is " + fav_film3$
If num = 4 Then Print "My number " + num + " favorite film is " + fav_film4$
If num = 5 Then Print "My number " + num + " favorite film is " + fav_film5$
If num = 6 Then Print "My number " + num + " favorite film is " + fav_film6$
If num = 7 Then Print "My number " + num + " favorite film is " + fav_film7$
If num = 8 Then Print "My number " + num + " favorite film is " + fav_film8$
If num = 9 Then Print "My number " + num + " favorite film is " + fav_film9$
If num = 10 Then Print "My number " + num + " favorite film is " + fav_film10$

Notice how much more code you are required to write?  Just think if there were a hundred films...

Multi-Dimensional Arrays

So how do multi-dimensional arrays work?

A standard one-dimensional array can basically be thought of as a line of variables that can each hold a value.

A two-dimensional array can be thought of as 'rows' of lines of variables (or rows of one-dimensional arrays).

If you had a two-dimensional array, you could think of your array as a chess board.

dim chess$(7,7)

 
This will give you 0-7 across and 0-7 down (64 square in total) (Blitz arrays are zero-based, meaning that they start from 0, not 1).
So you can reference a point and see what's there or set what's there.

chess$(5,5) = "Black Knight"
chess$(1,2) = "White Queen"
print chess$(3,3)

Then you can take it even further and stack several chess boards on top of one another. This would be a 3-dimensional array.

dim chess$(7,7,2)

This has stacked 3 chess boards on top of each other. You can now reference any square on any board.
The following code sets position 5,2 on chess board 1

chess$(5,2,1) = "White Bishop"
print chess$(5,2,1)

And this sets position 2,1 on chess board 0...

chess$(2,1,0) = "Black Pawn"

Are you ready to take it even further...

Well, lets have our stacked chess boards spanning across different rooms... (4 dimensional array)

dim chess$(7,7,2,9)

Are you getting the idea?

We now have 10 (0-9) rooms we are playing our 3 stacked chess games in. We can reference any square on any chess board in any room...

chess$(5,1,2,7) = "Black Rook"

So, in room 7, on board 2, at position 5,1 on that board there is now a black rook...

Expand it further... Lets add any building...

dim chess$(7,7,2,9,4)

We now have x,y on the board, board number, room number, and building number which we can instantly reference...

chess$(1,2,2,8,3) = "White Pawn"

So the piece at 1,2 on board 2 in room 8 of building 3 is a White pawn.

As you can see, arrays and multi-dimensional arrays are very useful and actually aren't that confusing.

A note about Blitz arrays

Note that Blitz arrays do start at zero, so a line like this:

Dim Array(0)

is a perfectly acceptable line of code (and would contain 1 array element).

A line like this:

Dim Array(0, 0, 0)

is also a perfectly acceptable line (and would actually still contain only 1 array element (1 x 1 x 1 = 1) even though there are three dimensions).

A line like this:

Dim Array(1)

would contain 2 elements (0 and 1).

And a line like this:

Dim Array(1, 1, 1)

would contain 8 elements (2 x 2 x 2 = 8).