Wiki source for KeyPgRedim


Show raw source

{{fbdoc item="title" value="REDIM"}}----
Defines or resizes a variable-length array

{{fbdoc item="syntax"}}
Declaring a Dynamic Array:
##**Redim** [ [[KeyPgShared|Shared]] ] //symbolname//([//subscript// [, ...]]) As [[DataType|datatype]] [, ...]##
##**Redim** [ [[KeyPgShared|Shared]] ] As [[DataType|datatype]] //symbolname//([//subscript// [, ...]]) [, ...]##

Resizing a Dynamic Array:
##**Redim** [ [[KeyPgPreserve|Preserve]] ] //symbolname//([//subscript// [, ...]]) [, ...]##

{{fbdoc item="param"}}
##[[KeyPgShared|Shared]]##
Specifies shared (file-scope) access to the array throughout the module.
##[[KeyPgPreserve|Preserve]]##
When used with an existing array, the contents of the array will be preserved during the resize. Note that in some cases ##[[KeyPgPreserve|Preserve]]## will not preserve data at its original index, see below.
##//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.

{{fbdoc item="desc"}}
##**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 ##[[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.

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** [[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 (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 ##[[KeyPgDim|Dim]]##:
- This includes the fixed-size arrays contained in UDTs (user-defined ##[[KeyPgType|Type]]##s).
- 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.
- ##**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 ##[[KeyPgThis|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 ##[[KeyPgThis|This]]## reference would be readjusted (by means of ##@This = @array(...)##) immediately after executing ##**Redim**## in the body of this member procedure.
- ##**Redim**## can be used with a complex array expression (especially if the array expression itself contains parentheses):
- But then the array expression must be enclosed in parentheses in order to solve the parsing ambiguity.

{{fbdoc item="ex"}}
{{fbdoc item="filename" value="examples/manual/array/redim.bas"}}%%(freebasic)
'' 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
%%

{{fbdoc item="filename" value="examples/manual/array/redim2d.bas"}}%%(freebasic)
'' 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

%%

{{fbdoc item="filename" value="examples/manual/array/redim3.bas"}}%%(freebasic)
'' 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)
%%
{{fbdoc item="diff"}}
- ##[[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.

{{fbdoc item="see"}}
- ##[[KeyPgCommon|Common]]##
- ##[[KeyPgDim|Dim]]##
- ##[[KeyPgErase|Erase]]##
- ##[[KeyPgExtern|Extern]]##
- ##[[KeyPgLbound|Lbound]]##
- ##[[KeyPgPreserve|Preserve]]##
- ##[[KeyPgShared|Shared]]##
- ##[[KeyPgStatic|Static]]##
- ##[[KeyPgUbound|Ubound]]##
- ##[[KeyPgVar|Var]]##

{{fbdoc item="back" value="CatPgArray|Array Functions"}}
Valid XHTML :: Valid CSS: :: Powered by WikkaWiki



sf.net phatcode