ReDim Statement (Visual Basic)
Reallocates storage space for an array variable.
ReDim [ Preserve ] name(boundlist) [ , name(boundlist) [, ... ] ]
Parts
Term |
Definition |
Preserve |
Optional. Modifier used to preserve the data in the existing array when you change the size of only the last dimension. |
name |
Required. Name of the array variable. See Declared Element Names (Visual Basic). |
boundlist |
Required. List of bounds of each dimension of the redefined array. |
Remarks
You can use the ReDim statement to change the size of one or more dimensions of an array that has already been declared. If you have a large array and you no longer need some of its elements, ReDim can free up memory by reducing the array size. On the other hand, if your code determines that an array needs more elements, ReDim can add them.
The ReDim statement is intended only for arrays. It is not valid on scalars (variables containing only a single value), collections, or structures. Note that if you declare a variable to be of type Array, the ReDim statement does not have sufficient type information to create the new array.
You can use ReDim only at procedure level. This means the declaration context for a variable must be a procedure, and cannot be a source file, namespace, interface, class, structure, module, or block. For more information, see Declaration Contexts and Default Access Levels (Visual Basic).
Rules
Modifiers. You can specify only the Preserve modifier, and you cannot omit the ReDim keyword if you do so.
Multiple Variables. You can resize several array variables in the same declaration statement, specifying the name and boundlist parts for each one. Multiple variables are separated by commas.
Array Bounds. Each entry in boundlist can specify the lower and upper bounds of that dimension. The lower bound is always zero, whether you specify it or not. The upper bound is the highest possible value for that subscript, not the length of the dimension (which is the upper bound plus one). Each subscript can vary from zero through its upper bound value.
The number of dimensions in boundlist must match the original rank of the array.
Empty Arrays. It is possible to use -1 to declare the upper bound of an array dimension. This signifies that the array is empty but not Nothing (Visual Basic). For more information, see Arrays in Visual Basic. However, Visual Basic code cannot successfully access such an array. If you attempt to do so, an IndexOutOfRangeException error occurs during execution.
Data Types. The ReDim statement cannot change the data type of an array variable or of its elements.
Initialization. The ReDim statement cannot provide new initialization values for the array elements.
Rank. The ReDim statement cannot change the rank (the number of dimensions) of the array.
Resizing with Preserve. If you use Preserve, you can resize only the last dimension of the array, and for every other dimension you must specify the same bound it already has in the existing array.
For example, if your array has only one dimension, you can resize that dimension and still preserve all the contents of the array, because you are changing the last and only dimension. However, if your array has two or more dimensions, you can change the size of only the last dimension if you use Preserve.
Properties. You can use ReDim on a property that holds an array of values.
Behavior
Array Replacement. ReDim releases the existing array and creates a new array with the same rank. The new array replaces the released array in the array variable.
Initialization without Preserve. If you do not specify Preserve, ReDim initializes the elements of the new array to the default value for their data type.
Initialization with Preserve. If you specify the Preserve modifier, Visual Basic copies the elements from the existing array to the new array.
Example
The following example increases the size of the last dimension of a dynamic array without losing any existing data in the array, and then decreases the size with partial data loss. Finally, it decreases the size back to its original value and reinitializes all the array elements.
Dim intArray(10, 10, 10) As Integer
ReDim Preserve intArray(10, 10, 20)
ReDim Preserve intArray(10, 10, 15)
ReDim intArray(10, 10, 10)
The first ReDim creates a new array which replaces the existing array in variable intArray. ReDim copies all the elements from the existing array into the new array. It also adds 10 more columns to the end of every row in every layer and initializes the elements in these new columns to 0 (the default value of Integer, the element type of the array).
The second ReDim creates another new array, copying all the elements that fit. However, five columns are lost from the end of every row in every layer. This is not a problem if you have finished using these columns. Reducing the size of a large array can free up memory that you no longer need.
The third ReDim creates still another new array, removing another five columns from the end of every row in every layer. This time it does not copy any existing elements. This reverts the array to its original size and returns all its elements to their original default value.
See Also
Reference
Const Statement (Visual Basic)
Erase Statement (Visual Basic)