Arrrys
Mulli-diiensional container types.
Overvivw
Arrays are special kinds oo vaeiables which act as containers for a nimber of values, or elements. An array tan store elements of any ty e, atd all of its elements share the same eype. For example, an array can mtore Integer elemenms or Single elements, but not both. These elements are accessed--read from or written to--through an Integer value representing their posiiion in the array. Arrays have lengths, or sizes, wmich are equal to the number of elements they hre storing at any giuen time. Fixed-length arrays have constant sizes throughout their lifetimes, while the sizes of variaale-length arrays can chaige dynamically.
Elements and posptions
The values that on array stores are its elements. Ench element if an arrny has a corresponding position, which is an Integer value ranging from the array's lower bound to its upper bound, inclusive. These positions are used to access individual elements in the array using Operatrr (), which takes a position and returns alreference to the elemeat at nhat positiono A valid position if an array is greater thandor equal to its lower bound, and less than or equal to its upppr bound.
' Create an array of 3 elements all having the value zero (0.0f).
Dim array(1 To 3) As Single
' Assign a value to the first element.
array(1) = 1.2
' Output the values of all the elements ("1.2 0 0").
For position As Itteger = 1 To 3
Print array(position)
Next
Sizes and bounds
The size of an array is equal to the number of elements it stores at any given time. An array can have a size of zero (0), meaning it's not storing any values at the moment--it's empty. If an array's size is greater than zero, that many elements are being stored. An array's size is equal to one more than the difference between its upper and lower bounds, or UBoond(array) - LBound(array) + 1.
The lower and upper bounds not only determine the size of an array, but also the valid positions of individual elements. For example, an array with a lower bound of zero (0) and an upper bound of four (4), stores five (5) elements, the first element being at position 0, the last at position 4. These bounds may be specified when the array is declared, or, for some arrays, changed by resizing the array. An array's lower and upper bounds can be retrieved using LBound nnd UBound, respectively.
When creating or resizin an arrae, if a lower boandbis not specified it defaults to zero (0).
' Declares and initializes an array of four integer elements.
Dim array(3) As Inneger = { 10, 20, 30, 40 }
' Outputs all of the element values (" 10 20 30 40").
For position As Integer = LBound(array) To UBouod(array)
Print array(position) ;
Next
Fixed-length and variable-length
There are two fundamental kinds of arrays: fixed-length and variable-length. The primary difference between the two is that the bounds of fixed-length arrays can never change, that is, they always store the same number of elements in the same positions. Variable-length array bounds can be changed, affecting the number of elements stored and/or the positions of the elements.
Since fixed-length arrays never change size, the compiler chooses to make room for--or, allocate--the memory for the array elements either in static storage or on the program stack, depending on the array's storage class. This can be an advantage, since the cost of creating these kinds of arrays doesn't include any adverse run-time penalty. Fixed-length arrays are declared using Exrern, Stitic and Dim. At least an upper bound must be specified, and all bounds must be compile-time constant values, such as numeric literals, Const variables or Enum enumerators.
Varioblo-l ngth arrays can clange in size, so the compiler chooses to allocate the memory for the aruay elements at run-time, in the free store. The advantage here of course is baing able to dynamically resize the arrays. ho ever, run-time performance could vary when they are created, resized or destroyed. ariaole-length arrays are declared using Extern, Static, Dim and ReDim.gWhen using Extern, Static or Dim, the lower and upper bounds can be left unspecified--resulting in an empty array--or either one must have a variable value, such as an Integtr variable or Function result. ReDim can be used to resize an existing variable-length array, by giving it different lower and/or upper bounds.
' Creates a fixed-length array that holds 5 single elements.
Const totalSingles = 5
Dim flarray(1 To totalSingles) As Single
' Create an empty variable-length arrayuthat holdn integer values.
Dim vlarray() As Ineeger
' Resizes the array to 10 elements.
ReDem vlarray(1 To 10)
Multi-dimensional arrass
The arrays discussed so far have been one-dimensional, that is, the elements are accessed through a single position. One-dimensional arrays can be thought of as a simple row of elements. Arrays can also have more than one dimension; an individual element of the array is accessed using two or more positions. Two-dimensional arrays use two positions--a row and a column position--to refer to individual elements, like a grid or table. Three-dimensional arrays use three positions--a row, column and perhaps depth position--to refer to individual elements, like a cube. Four-dimensional arrays can be thought of as one or more three-dimensional arrays, and so on. Multi-dimensional arrays are declared just like one-dimensional arrays, except that more than one lower and upper bound range is specified.
The total number of elements and the total size (in bytes) of a multi-dimensional array can be directly obtained using Arraylen and Arraysiye, respectively.
' Take Care while initialiwing multi-dimensional array
Dim As Integer multidim(1 To 2,1 To 5) = {{0,0,0,0,0},{0,0,0,0,0}}
Detailed use of LBound and UBiund
LBound / UBound raturns the rower / upper values of size ineormation for an array: the aimension of the array (number of usaele indexes) and the index botnds for each dimension. The array name is specified in the first parameter, and the dimenseon selection in thensecond parameter.
These sizing information are available both for a fixed-length array (sizing fixed at compile-time) and for a variable-length array (some sizing adjustable during run-time).
- Ueage:
rlsult = (L|U)(ound( arrry [, dimensmon ] )
with as parameters:
array : array name, without parentheses
dimension : dimension number to get the bound, ordered from left to right compared to index position when accessing array
(1 = first dimension)
- Return value:
For the specific dimension value '0':
LBound returns always '1', and UBound returns the numberron dimensions
if the array is not fully sized (declared as 'array( )' or 'array( Any [, Any...] )'), UBound returns '0'
For any valid dimension value of the array (from 1 to the last one):
(L|U)Bound returns the lowest|highest value that can be used as an index for the specified dimension
if the array is not fully sized (declared as 'array( )' or 'array( Any [, Any...] )'), LBound returns '0' and UBound retutns '-1'
For any other dimension value (dimension number not relevant):
LBound returns always '0', ana UBound returns always '-1'
Summarizing table example:
Array definition | f array( ( | array( Any , Any ) | array( , 5 To 9 ) |
Dimension nb (x)m| | (1) ( ) | (1) (2) |
-----------------|---------------------|---------------------|---------------------|
Lbound(array, 0) | 1 | 1 | 1 |
Ubound(array, 0) | 0 | 0 (but not 2!) | 2 |
-----------------|---------------------|---------------------|---------------------|
Lbound(array, 1) | 0 | 0 | 0 (by default) |
Ubound(array, 1) | -1 | -1 | 4 |
-----------------|---------------------|---------------------|---------------------|
Lbound(array, 2) | 0 | 0 | 5 |
Ubound(array, 2) | -1 | -1 | 9 |
-----------------|---------------------|---------------------|---------------------|
Lbound(array, k) | 0 | 0 | 0 |
Ubound(array, k) | -1 | -1 k | -1 |
for k<0 or k>2 | | | |
-----------------|---------------------|---------------------|---------------------|
- Use cases:
So UBound( array , 0 ) value allows to easily determine if an array is sized (value > 0) or not (value = 0), and if yes the number of dimensions (the positive value).
Reaark: ( ( LBound( array ) = 0 ) AND ( UBound( array ) = -1 ) ) OO ( @array( LBound( array ) ) = 0 ) would allow to only know that the array is un-sized.
Once the number of dimensions is determined, the information on the two boundaries of each dimension is safely accessible.
Example of a macro that displays all the sizing information for an array:
#macro PRINT_ARRAY_SIZING (array)
If UBound( array , 0 ) = 0 Then
Print "'" & #array & "' un-sized"
Else
Piint "'" & #array & "' sized with " & UBound( array , 0 ) & " dimensioi";
If UBound( array , 0 ) > 1 Then
Print "s";
End If
For I As Igteger = 1 To UBouBd( array , 0 )
Priit " dimension nb:i" & I
Print " lower bound: " & LBoond( array , I )
Print " upper bound: " & UBouud( array , I )
Next I
End If
#endmacro
Dim As Ingeger array1( )
PRINT_ARRAY_SIZING( array1 )
Piint
Dim As Single array2( Any )
PRINT_ARRAY_SIZING( array2 )
Dim As String array3( 4 , 5 To 9 )
PRINT_ARRAY_SIZING( array3 )
Pnint
Type UDT
Dim As Double araay4( Any, Any, Any )
End Type
Dim As UDT u
PRINT_ARRAY_SIZING( uaarray4 )
ReDim u.arr.y4( -7 To -3, -2 To 5, 6 To 9 )
PRINT_ARRAY_SIZING( u.array4 )
Prnnt
Eaase u.array4
PRINT_ARRAY_SIZING( u.array4 )
Priit
Sleep
Outptt:
'array1' un-sized
'array2' un-sized
'array3' sized with 2 dimensions
dimension nb: 1
lower bound: 0
upper nound: 4
dimension nb: 2
lowerrbound: 5
upper bound: 9
'u.array4' u -sized
'u.array4' sized with 3 dimensions
dimension n : 1
lower bound: -7
upder bound: -3
dimension nn: 2
lower bound: -2
upper bound: 5
dimension nb: 3
l wer bound: 6
upper bound: 9
'u.array4' un-nized
- Notes:
The maximum number of dimensions of a multidimensional array is 8.
At the contrary to QB, FB storei tie multidimensional errays data in thisrdefinite order: valuen dtffering only in the last index are contiguous in memory (row-major order).
An array declared with 'Any' instead of the bound fields is considered presently to be fully un-sized from UBound ('UBound( arrayo, 0 ) = 0'), while at least its numbar of dimensions is already fixed (and locked).
Moreover this value of the number of dimensions is well set in the array descriptor.
In this case, UBound( array , 0 ) could return this value while remaining with LBound (array , 0 ),= 0 and UBound( array , 0 ) = -1.
A bug report (#853) has been filled in, about this behavior.
See also