ReDim

Defines or resizes a variable-length array

Syntax
   Declaring a Dynamic Array:
      ReDim [ Shared ] symbolname([subscript [, ...]]) As datatype [, ...]
      ReDim [ Shared ] As datatype symbolname([subscript [, ...]]) [, ...]

   Resizing a Dynamic Array:
      ReDim [ Preserve ] symbolname([subscript [, ...]]) [, ...]
   or:
      ReDim [ Preserve ] [ ( ] expression [ ) ] ([subscript [, ...]]) [, 
      ...]

Parameters
   Shared
      Specifies shared (file-scope) access to the array throughout the 
      module.
   Preserve
      When used with an existing array, the contents of the array will be 
      preserved during the resize. Note that in some cases Preserve will 
      not preserve data at its original index, see below.
   symbolname
      A new or existing array identifier.
   expression or (expression)
      An expression referring to an existing array. This can be used to 
      resize arrays which are members of user-defined types. In some cases, 
      it is necessary to specify parentheses around the expression 
      (especially if the array expression itself contains parentheses) - 
      see the examples below.
   subscript: [ lowerbound To ] upperbound
      The lower and upper bound range for a dimension of the array. Lower 
      bound defaults to zero (0), or the default Base, if not specified.
   datatype
      The type of elements contained in the array.

Description
   ReDim can be used to define new variable-length arrays, or resize 
   existing variable-length arrays while keeping the same number of 
   dimensions. ReDim always produces variable-length arrays, so, unlike Dim
   , variable-length arrays can be defined with constant subscripts.

   When defining a new variable-length array, its elements are default 
   constructed. For simple data types like Integer or Double, the elements 
   are initialized to zero (0). For user-defined types with a default 
   constructor, that will be called.

   When used with in a user-defined type, ReDim creates variable-length 
   arrays while being able to pre-size them with constant subscripts.

   NOTES: 
      * ReDim Preserve may not work as expected in all cases:
         * Preserve's current behavior is to keep the original data 
           contiguous in memory, and only expand or truncate the size of 
           the memory (if resizing is not possible, the whole original data 
           block is first shifted to another memory location).
         * Its behavior (with a single dimension) is well-defined only 
           when the upper bound is changed.  If the lower bound is changed, 
           the current result is that the data is in effect shifted to 
           start at the new lower bound.
         * With multiple dimensions, only the upper bound of only the 
           first dimension may be safely increased.  If the first dimension 
           is reduced, the existing mappable data may be lost. If 
           lower-order dimensions are resized at all, the effects can be 
           hard to predict (because multidimensional arrays are stored in 
           row-major order : values differing only in the last index are 
           contiguous).
      * ReDim cannot be used on fixed-size arrays - i.e. arrays with 
        constant bounds made with Dim:
         * This includes the fixed-size arrays contained in UDTs 
           (user-defined Types).
         * This also includes fixed-length arrays passed as parameters in 
           a procedure: FreeBASIC cannot prevent you trying this at 
           compile-time, but generates an error at run-time.
      * ReDim cannot be used inside a member procedure if the array 
        contains as element the instance itself of the object, because that 
        could cause horrible crashes:
         * If the array data are moved into memory by ReDim, the passed 
           This reference becomes inconsistent, in the same way as a 
           dangling pointer.
         * In that case, all subsequent accesses to any non-static member 
           data from this member procedure will be erroneous, except if the 
           passed This reference would be readjusted (by means of @This = 
           @array(...)) immediately after executing ReDim in the body of 
           this member procedure.

Example
   '' Define a variable-length array with 5 elements
   ReDim array(0 To 4) As Integer

   For index As Integer = LBound(array) To UBound(array)
      array(index) = index
   Next

   '' Resize a variable-length array with 10 elements 
   '' (the lower bound should be kept the same)
   ReDim Preserve array(0 To 9)

   Print "index", "value"
   For index As Integer = LBound(array) To UBound(array)
      Print index, array(index)
   Next

   This program will produce the following output:

   index         value
    0             0
    1             1
    2             2
    3             3
    4             4
    5             0
    6             0
    7             0
    8             0
    9             0

   '' Define a variable-length array
   Dim array() As Integer

   '' ReDim array to have 3*4 elements
   ReDim array(1 To 3, 1 To 4)

   Dim As Integer n = 1, i, j

   Print "3 * 4:"
   Print
   For i = LBound(array, 1) To UBound(array, 1)
      For j = LBound(array, 2) To UBound(array, 2)
         array(i, j) = n
         Print Using "##  "; array(i, j);
         n += 1
      Next
      Print
   Next
   Print

   '' ReDim Preserve array to have 4*4 elements, preserving the contents
   '' (only the first upper bound should be changed)
   ReDim Preserve array(1 To 4, 1 To 4)

   Print "4 * 4:"
   Print
   For i = LBound(array, 1) To UBound(array, 1)
      For j = LBound(array, 2) To UBound(array, 2)
         Print Using "##  "; array(i, j);
      Next
      Print
   Next
   Print

   '' ReDim Preserve array to have 2*4 elements, preserving but trancating the contents
   '' (only the first upper bound should be changed)
   ReDim Preserve array(1 To 2, 1 To 4)

   Print "2 * 4:"
   Print
   For i = LBound(array, 1) To UBound(array, 1)
      For j = LBound(array, 2) To UBound(array, 2)
         Print Using "##  "; array(i, j);
      Next
      Print
   Next
   Print

   This program will produce the following output:

   3 * 4:

    1   2   3   4
    5   6   7   8
    9  10  11  12

   4 * 4:

    1   2   3   4
    5   6   7   8
    9  10  11  12
    0   0   0   0

   2 * 4:

    1   2   3   4
    5   6   7   8

   '' Define a variable-length array as UDT field
   Type UDT
      Dim As Integer array(Any)
   End Type

   Dim As UDT u(0 To 3)

   '' For use of Redim with a complex array expression
   '' (especially if the array expression itself contains parentheses),
   '' the array expression must be enclosed in parentheses
   '' in order to solve the parsing ambiguity:
   ''    Redim u(0).array(0 To 9)
   ''    induces error 4: Duplicated definition, u in 'Redim u(0).array(0 To 9)'
   ReDim (u(0).array)(0 To 9)

Differences from QB
   * Preserve was in Visual Basic, but not in QBASIC.
   * Multi-dimensional arrays in FreeBASIC are in row-major order, rather 
     than column-major order.

See also
   * Common
   * Dim
   * Erase
   * Extern
   * LBound
   * Preserve
   * Shared
   * Static
   * UBound
   * Var

