Arrays

To store a series of data values of the same data type together under the same variable name, declare the variable as an array. Arrays are useful for collecting and processing lists of information. They must be explicitly defined with the DIM statement before they are used. The declaration must include the Array Size which is the maximum number of data elements the array will contain.

For example, the following statements declare an array of character strings holding five elements:

dim names[5] as C

dim names[1..5] as C ' version 6

dim names[0..4] as C ' version 6

It is possible to dim multiple array dimensions in one statement.

dim arr.row[1..10].col[1..5].edited as C

Note: The first element of an array can be 0 or 1.

This array can be used to collect and store a list of five names. The contents of the array elements are assigned like any other variable using the assignment operator ( = ). The number of the element in which you want to put the data must also be supplied. For example:

names[1] = "Henry"

names[2] = "Burt"

names[3] = "Ernie"

names[4] = "Linda"

names[5] = "Cheryl"

Multidimensional Arrays

In Alpha Five version 6 arrays can contain multiple dimensions. For example:

dim a[3,3,3] as C

Arrays of Pointers

You can define an array of pointers. For example:

dim ar[5] as P

ar[1].mom = "Irene"

ar[1].dad = "Abe"

ar[2].mom = "Arlene"

ar[2].dad = "Kyle"

? ar[1].mom

= "Irene"

? ar[1].dad

= "Abe"

? ar[2].mom

= "Arlene"

? ar[2].dad

= "Kyle"

ar.SORT("A","mom")

? ar[1].mom

= "Arlene"

? ar[1].dad

= "Kyle"

It is useful to visualize an array of pointers like this:

Element	Mom	Dad
ar[1]	Irene	Abe
ar[2]	Arlene	Kyle
ar[3]	Janet	Herb

The array might have more "columns". For example:

Element	Mom	Dad	Lastname	City	Kids
ar[1]	Irene	Abe	Jones	Boston	2
ar[2]	Arlene	Kyle	King	Miami	3
ar[3]	Janet	Herb	Smith	Fresno	1

In this example, ar[3].kids is 1. To sort the array on the "Kids" element, you would type:

ar.sort("","kids")

Nested Arrays

Alpha Five supports nested arrays. For example:

dim row[10] as P

for i = 1 to 10

dim row[i].col[10] as C

next i

row[1].col[1] = "c"

row[1].col[2] = "b"

row[1].col[3] = "d"

row[2].col[1] = "a"

row[2].col[2] = "x"

row[2].col[3] = "m"

'Sort the elements of the row[1].col array.

'i.e. elements are sorted into this order: b,c,d

row[1].col.sort()

Examining Arrays in the Interactive Window

If you are working with an array in the Interactive window, you can examine the contents of an array by typing ? arrayname in the Interactive window. For example:

dim Names[3] as C

Names[1] = "John"

Names[2] = "Fred"

Names[3] = "Tom"

? Names

= [1] = "John"

[2] = "Fred"

[3] = "Tom"

Automatically Inserting Elements into an Array

Alpha Five supports a special syntax that allows you to automatically insert elements at the end of an array without having to specify the array index. If necessary, Alpha Five will automatically resize the array to accommodate the new entry.

For example:

dim cities[1] as C

'add a new entry to the array by omitting the array index

cities[] = "boston"

? cities.SIZE()

= 1.000000

? cities

= [1] = "boston"

cities[] = "chicago"

? cities.size()

= 2.000000

? cities

= [1] = "boston"

[2] = "chicago"

If you are working with a property array, you can do this.

Dim a[1] as P

A[1].name = "Fred"

A[1].city = "Boston"

A[1].age = 23

A[].name = "Tom"

A[..].city = "NY"

A[..].age = 35

The a[].name = "Tom" adds array element number 2. A[..]. city = "NY" adds "NY" to the newly created array element (i.e. number 2). If you did not use the syntax a[..].city = "NY", but instead did a[].city = "NY" then your array would look like this:

	Name	City	Age
A[1]	Fred	Boston	23
A[2]	Tom	<undefined>
A[3]	<undefined>	NY

Passing Arrays to Functions

When you pass an array to a function, the receiving function defines the argument as a pointer.

Dim a[5] as C

a[1] = "a value"

my_function(a)

function as V (arr as P)

ui_msg_box("Array Value", arr[1])

end function