REDIM statement

Purpose

Used at the procedure level to declare dynamic array variables and allocate, deallocate, or reallocate storage space.

Syntax

REDIM [PRESERVE] array[(subscripts)] [AS type] [AT address] [, ...]

Remarks

The REDIM statement allows dynamic arrays (including string arrays) to be erased and re-dimensioned.  It is really just a shortcut for the two-step process ERASE x(), followed by DIM x().  REDIM uses the same basic syntax as the DIM statement.

array is the name of the array, and subscripts is either a group of single integers (one per dimension of a particular array), or a group of ranges (REDIM arr1(5 TO 25, 1 TO 4, 3 TO 8)), separated by commas.

AS type

The AS type clause is optional, but recommended for the purposes of clarity.

AT address

The AT address clause indicates the array is to be an absolute array.  Absolute arrays are not reset by the REDIM statement, nor are they reset when the Sub/Function/Method/Property exits, but they can be reset with the RESET statement.  See the discussion in the DIM topic for more information on absolute arrays.

PRESERVE

The PRESERVE keyword tells the compiler to preserve the values of all existing elements in the array.  For example, if you REDIM PRESERVE an array with 10 elements to 20 elements, the first 10 elements will retain their original value.  The remaining 10 elements will be initialized to zero (or null/empty in the case of a string array).  If the array is resized to be smaller, the specified number of elements is preserved, and the remaining elements are discarded.  When PRESERVE is specified, you can resize only the upper boundary of the last (outer) dimension of the array.  Arrays of only one dimension can always be resized.

In a procedure, you can use REDIM to re-dimension an array that was passed as an argument.  That is, when the complete array was passed to the procedure:

CALL RemoveDuplicates( CustomerNames$() )

...

SUB RemoveDuplicates( a$() )

  ...

  REDIM PRESERVE a$(1 TO NewCount&)

END SUB

REDIM may also be used to alter the size of Static, Global, and Instance arrays.

When used with no subscript parameters, REDIM will erase all contents of an array and deallocate the memory used:

REDIM xyz&()  ' Equivalent to ERASE xyz&()

Restrictions

REDIM cannot change the number of dimensions that an array has.  When PRESERVE is specified, only the upper bound of the last (outer) dimension may be redefined.

When a REDIM statement is executed, the location of the array elements always moves in memory; however, the array's Descriptor location  (VARPTR(arrayname()) will remain fixed at the original location.  When using REDIM, your code must be sure to refresh any pointers that target the array data memory locations (STRPTR(arrayname(subscript)) for dynamic string arrays, and VARPTR(arrayname(subscript)) for all other array types).

While PowerBASIC supports lower boundary values that are non-zero, PowerBASIC generates the most efficient code if the lower boundary parameter is omitted (i.e., the array uses the default lower boundary of zero).

See also

ARRAYATTR, DIM, ERASE, RESET

Example

DIM MyData(40), Names$(100)

REDIM MyData(5 TO 50), Names$(10)