Variable-length Arrays
Resizable homogeneous data structures.
Overview
Variable-length arrays are arrays that can, during program execution, either be resized to hold more or less elements, or have their dimension[s] use a different subscript range. The memory used by a variable-length array to store its elements is allocated at runtime, in the free store (the heap), as opposed to fixed-length arrays whose data is either allocated on the program stack or in the `.BSS` or `.DATA` sections of the executable, depending on whether they were defined with `Static`.
Declaration and definition
A variable-length array is declared with the `Extern` keyword, followed by a variable identifier, a parenthesized list of zero (0) or more subscript ranges and an element datatype. For an array to be declared variable-length, either an empty subscript range list can be used, or one or more of the subscript ranges must have non-constant values - that is, the ranges must be specified by variables or objects convertible to `Integer`.
`
Dim maxLowerBound As Integer = -5
Dim maxUpperBound As Integer = 10
'' Declares a two dimensional variable-length array of elements of type STRING..
Extern arrayOfStrings(maxLowerBound To maxUpperBound, 20) As String
'' Declares a one-dimensional variable-length array of elements of type BYTE..
Extern arrayOfBytes() As Byte
`
A variable-length array is defined with either the `Dim` or `ReDim` keywords, following the same form as declaration. The `ReDim` keyword always defines variable-length arrays, whether the subscript ranges are constant or not. Variable-length arrays cannot be defined with static storage using `Static`.
`
'' Defines one-dimensional variable-length arrays of type SHORT and INTEGER..
Dim arrayOfShorts() As Short
ReDim arrayOfIntegers(9) As Integer
`
Since the memory for variable-length arrays is allocated at runtime, when they are defined, the elements of variable-length arrays declared with `Extern` cannot be accessed until the array is defined. Similarly, variable-length arrays defined with empty subscript range lists have zero size - they hold zero elements - so they too must be resized before any elements can be accessed.
Resizing
Resizing a variable-length array refers to "redefining" the array with different values for its subscript range[s], allowing the array to grow or shrink. Elements outside the new subscript range[s] are erased; object elements will be destroyed. If the array is resized to a larger size, new elements are added initialized with a zero or null value; object elements are default-constructed. Variable-length arrays are resized using the `ReDim` keyword following the same form as definition.
`
'' Define an empty variable-length array of SINGLE elements..
Dim array() As Single
'' Resize the array to hold ten (10) SINGLE elements..
ReDim array(9) As Single
`
By default, element values of a variable-length array are lost when resized - the array will contain zero or more elements initialized to a zero or null value, or if the elements are objects, they will be default-constructed. To retain the previous element values during a resize, use the `Preserve` keyword.