REDIM

Revision [15454]

This is an old revision of KeyPgRedim made by FxMwikki on 2011-10-18 15:37:24.

Defines or resizes a variable-length array

Syntax:Redim [ KeyPgPreserve Preserve ] [ KeyPgShared Shared ] symbolname([subscript [, ...]]) As DataType datatype [, ...] Redim [ KeyPgPreserve Preserve ] [ KeyPgShared Shared ] As DataType datatype symbolname([subscript [, ...]]) [, ...]
Parameters:

KeyPgPreserve Preserve

When used with an existing array, the contents of the array will be preserved during the resize. Note that KeyPgPreserve Preserve will not work properly in all cases.

KeyPgShared Shared

Specifies shared (file-scope) access to the array throughout the module.

symbolname

A new or existing array id.

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 KeyPgOptionbase Base, if not specified.

DataType 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. Redim always produces variable-length arrays, so, unlike KeyPgDim 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 KeyPgInteger Integer or KeyPgDouble Double, the elements are initialized to zero (0). For user-defined types with a default constructor, that will be called.

NOTES:

Redim KeyPgPreserve Preserve may not work as expected in all cases:

KeyPgPreserve Preserve's current behavior is to keep the original data contiguous in memory, and only expand or truncate the size of the memory.
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.

Redim cannot be used on fixed-size arrays - i.e. arrays with constant bounds made with KeyPgDim Dim. This includes arrays contained in UDTs (user-defined KeyPgType Types), because currently only fixed-size arrays are supported in UDTs. This also includes fixed-length arrays passed as parameters in a function. FreeBASIC cannot prevent you trying this at compile-time, but the results at run-time will be undefined.

Using Redim within a member procedure with an array that contains an instance of the object class is undefined, and will [hopefully] result in horrible crashes.

Examples:

'' 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) As Integer

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             5
 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) As Integer

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) As Integer

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

Differences from QB:

KeyPgPreserve 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:

Back to Array Functions

REDIM - FreeBASIC Wiki Manual | FBWiki

Revision [15454]

REDIM