Syntax:
[dim] dynamic arrayName(maxSub1[,maxSub2 ...]) [as dataType]
Description:
The dynamic syntax is an alternate version of dim that allows for arrays that can grow as needed. The constant expression used in the parenthesis should be the theoretical maximum that will ever be needed by the array. Since it is not possible for a dynamic array to have a value that is out of range, this value is used only to prevent the runtime from reporting out of range errors. Dynamic arrays may only be created and used as global arrays. Do not attempt to dimension them inside of a local fn.
Example:
// 1000 elements max
dynamic myIntArray(1000)
// 2 gig elements max
dynamic hugeEmployeeRecAry(_maxLong) as employeeRec
// 32,767 elements max
dynamic arrayOfRects(_maxInt) as Rect
The maxSub1 , maxSub2 etc. values must be positive static integer expressions. However, since dynamic does not actually allocate any memory, the declared subscripts are used somewhat differently than in a dim statement. The second and subsequent subscripts (if any) determine the internal structure of the array, and space for them will be fully allocated for each element dynamically referenced in the first subscript. But the value of the first subscript (maxSub1) is ignored, and may be arbitrarily set to any value greater than zero. You can actually reference array elements greater than maxSub1, so long as adequate RAM is available to allocate the memory required.
Auto Grow
When a dynamic array is dimensioned, the only thing set aside in memory is an eight byte record that tracks items used and space allocated. As soon as you insert information into the array, it begins to grow. You can set things up so that the array grows one element at a time. This has a slight advantage of saving a few bytes, but an overall disadvantage of taking longer to execute as the grow routines must be called much more often.
You can control this value by setting a global variable: gFBDynamicGrowInc&. The default value for this global variable is 10. If the value is left at 10, then the following actions would take place as information was placed in array elements:
// 1000 elements max
dynamic myIntArray(1000)
// Current handle size is zero
myIntArray(1) = 0
// Current size has jumped to 10 elements
// (0 through 9 at 2 bytes per element)
myIntArray(8) = 23
// Handle size does not change.
// There is already sufficient room
You may force the handle to grow to a maximum expected size. This keeps the runtime from invoking several operations to increase the size of the handle. It does not prevent the runtime from making additional checks to see that future additions fit in the allocated space and it does not prevent further resizing. When the size of a dynamic array is expanded, the newly created elements are set to zero.
You may determine how many elements are being used in a dynamic array using the following method:
dynamic 15 gTest$(100)
address& = @gTest
nextindex& = address&.AutoXREFCurr&
Note:
Dynamic arrays may only be global in nature and may not be dimensioned inside of a local fn.
WARNING:
Dynamic arrays may not be used to dimension an array of handles.
See Also:
compress dynamic; kill dynamic; read dynamic; write dynamic
