GAMBAS BOOK 3.19.1

If you use the number of dimensions of an array as a criterion, you can differentiate between single- and multidimensional arrays.

An array is called

• one-dimensional if it was created using the syntax type[Dim1] or type[].
• derived one-dimensional if it was created using the syntax ObjectType[Dim1] or ObjectType[].
• real multidimensional or native multidimensional, if you want to use the syntax type[Dim1, Dim2,…, DimN] in the following cases (2 ≤ N ≤ 8) was created or
• derived multidimensional, if it has the syntax Type[][]….[] was created.

The number of dimensions of an array must be specified during compilation. You can specify the size of the dimension directly or by any numerical expression.

Examples

One-dimensional arrays:

Dim myArrayS As New String[3]
Dim myArrayF As New Float[]

Really multidimensional arrays:

Dim myArray As String[10, 5] ' → ERROR! New is missing
Dim a2DArrayB As New String[10, C_MAX * 5]
Dim a3DArray as New Integer[8, 8, 8]
Dim myArray4 As New String[10, 5]    *

An alternative to the last line is the following 2 lines:

Dim myArray4 As New String[]
myArray4 = New String[10, 5] **

In both cases (1*) and (2*), the two dimensions are determined statically and cannot be changed at runtime!

Derived one-dimensional arrays:

Dim aLabels As New Label[]
Dim aArrayComponents As New Components[]
Dim aClassArray As New CDS[] ' Array whose elements are CDS objects of the class CDS

Derived multidimensional array:

Dim aLabels As New Label[][]

Example 1 - Using a One-Dimensional Derived Array

The used array' aLabels' is on the one hand one-dimensional and on the other hand a derived array, because' Label' is a class.

[1] Public Sub btnShowLabels_Click()
[2]   Dim aLabels As New Label[]
[3]   Dim hControl As Control
[4]   Dim iCount As Integer
[5]
[6]   If aLabels <> ZERO And aLabels.Count = 0 Then
[7]      Message.Info("The array 'aLabels' exists - but is empty.")
[8]   Endif
[9]
[10]   For Each hControl In ME.Children
[11]     If Object.Type(hControl) = "Label" Then aLabels.Add(hControl)
[12]   Next ' hControl
[13]
[14]   For iCount = 0 To aLabels.Max
[15]     aLabels[iCount].Tag = Str(iCount)
[16]     Print "Label-Name = "; aLabels[iCount].Name;
[17]     Print " | Label-Text = "; aLabels[iCount].Text;
[18]     Print " | Label-Tag = "; aLabels[iCount].Tag
[19]   Next ' iCount
[20]
[21] End ' btnShowLabels_Click()

Output in the IDE console:

Label-Name = lblCArray     | Label-Text = LabelArrays | Label-Tag = 0
Label-Name = lblACaption   | Label-Text = Demonstration Class ARRAY | Label-Tag = 1
Label-Name = lblMultiArray | Label-Text = Label1 | Label-Tag = 2
Label-Name = lblBArray     | Label-Text = Class Array | Label-Tag = 3

Comments:

• In line 2 the array' aLabels' is created.
• The array' aLabels' exists as an array object - but is empty. With the method aLabels. resize (4) you could dynamically insert 4 empty elements. But this is unfavourable, because you don't know if and how many labels are in the (main) window.
• Therefore, lines 10 to 12 examine all (visible) components in the program window and only those components of the object type' Label' are added to the array' aLabels' using the add method. This Add method automatically calls the Resize () method before inserting an element into the array.
• The (enhanced) output of the contents of array' aLabels' is pushed in the FOR-NEXT control structure in lines 14 to 19 after the tag property for all labels has been set.

In connection with investigations on the dimensions of multidimensional arrays, the virtual class array. bounds performs well, as the following example shows:

[1] Dim k As Integer
[2] Dim a2DArray As New String[10, 5]
[3]
[4] ' Static display of dimensions
[5]   Print "Dimension = "; a2DArray.Dim ' Number of dimensions
[6]   Print "Dimension 1 (Number of lines)  = "; a2DArray.Bounds[0]
[7]   Print "Dimension 2 (Number of columns) = "; a2DArray.Bounds[1]
[8]
[9]   Print "Dimension = "; a2DArray.Dim
[10]   Print "DIM-Count = "; a2DArray.Bounds.Count ' Number of elements in the Bounds array
[11]
[12] ' Dynamic display of the limits of the individual dimensions
[13]   For k = 0 To a2DArray.Bounds.Count - 1
[14]     Print "Dimension "; k + 1; " = "; a2DArray.Bounds[k]
[15]   Next

Output in the IDE console:

Dimension = 2
Dimension 1 (Number of Lines)  = 10
Dimension 2 (Number of columns) = 5

Dimension = 2
DIM-Count = 2

Dimension 1 = 10
Dimension 2 = 5

Comments:

• It is shown that the two properties a2DArray.dim and a2DArray.bounds.count deliver the same results here –> lines 9 and 10.
• The a2DArray.Bounds.Count property specifies the number of elements in the Bounds array, representing the Bounds array dimension.
• The dynamic display of the dimensions in lines 13 to 15 is clearly preferable to the static display in lines 5 to 7.

Excursion - Supplementary remarks on multidimensional arrays:

• String[][] is an array of arrays. You get a two-dimensional array, which can be changed in all dimensions, i. e. you can attach elements in any dimension at runtime, or you can add elements in only one dimension. In a two-dimensional array with string[x, y], this will not work because the dimensions are statically fixed.
• An array is of type aType if the elements in the array are of type aType. String[] contains only strings, a string[][] will contain as elements string arrays of type String[], which in turn contain strings. You can have the interpreter derive an array class aType[] from any data type and from any class aType. If aType is a native data type, then aType[] is called a native array. Note: aType[] is again a class and you can derive the class “Array of aType arrays” with aType[][]. In this way you have the possibility to realize n-dimensional arrays. There is no limit for n and the extent of each dimension is not static.
• If you write aType[][], you have an array of arrays of type aType - whatever aType is for aType.aType[][] is thus a two-dimensional array of aType variables. You access one of these variables with MyaTypArray[i][j]. For example, if you want to interpret i and j as 2 integer keys depends on the way you use the myaTypArray[i][j] array in your application.
• Another way to declare n-dimensional arrays (1 ≤ n ≤ 8) is to use a “real” multidimensional array class. These arrays have the form aType[n1, n2,…, nN], where N (⇐ 8) is the number of dimensions and n1 is the extension of the first dimension, n2 is that of the second, etc.. . Note that these real multidimensional arrays are inferior to the derived multidimensional arrays in at least three points:

1. The number of dimensions is limited to 8.
2. The extent of each dimension is static.
3. They can only form matrices.

As far as point (3) is concerned, it is probably the most subtle of the three. Derived multidimensional arrays allow the creation of systems in which a dimension does not have to be equally extended in all dimensions - of which matrices are a special case - because that is exactly what has to apply.