_RETAIN
The _RETAIN REDIM action preserves the current contents of dynamic arrays, when resizing or changing indices.
Syntax
Description
- REDIM or the $DYNAMIC metacommand must be used when the array is first created to be able to resize and preserve.
- If _RETAIN or _PRESERVE is not used, the current contents of the array are cleared by REDIM.
- All element values of an array are preserved if the array size is increased.
- The remaining elements of the array are preserved if the array size is decreased.
- If the new index range is different from the original, values will not be moved to the new corresponding indices.
- REDIM _RETAIN cannot change the number of array dimensions, but can change the number of elements.
- Always use the same array TYPE suffix (AS type) or a new array type with the same name may be created.
Errors
- SUB or FUNCTION arrays created using REDIM require that they be recreated to be used after arrays are ERASEd.
- Warning: Do not use negative upper array index values as an "Out of Memory" error (or global Operating System errors) will occur.
- Use _RETAIN before SHARED or an "invalid variable name" error will occur.
Availability
-
none -
v4.5.0 -
-
yes -
yes -
yes
Examples
- Example 1
- Changing the upper and lower array bounds
REDIM a(5 TO 10) ' create array as dynamic using REDIM a(5) = 123 REDIM _RETAIN a(20 TO 40) PRINT a(20) |
Explanation a(20) is now 0 value because index 20 before _RETAIN not exists. That is difference between _RETAIN and _PRESERVE. The upper or lower bounds of arrays can be changed, but the type cannot. New array indices like a(40) are null(0) or empty strings. If the array element count is not reduced, all of the data will be preserved. |
- Example 2
- Resizing a 3D array while preserving the values of the elements
REDIM Example(100, 250, 220) AS LONG Example(65, 200, 150) = 1024 REDIM _RETAIN Example(200, 200, 155) AS LONG PRINT Example(65, 200, 150) |
Explanation Example(65, 200, 150) is still 1024, because this value is stored in this index before REDIM _RETAIN. _RETAIN preserves the values of existing array elements when an array is resized. It can be used to enlarge an array; in that case, newly created numeric elements are initialized to 0. Dynamic string elements are initialized as empty strings until a specific index is assigned a value, while fixed-length string elements are filled with CHR$(0). When an array is shrunk, only the elements whose indices remain within the new bounds are preserved. This means that if an array previously used index 1 to 10 and is then resized to index 1 to 8, index 9 and 10 are discarded. |
- Example 3
- Resizing a UDT array while preserving the values of the elements
TYPE T Text AS STRING B(20) AS LONG C AS INTEGER END TYPE REDIM Demo(5) AS T Demo(5).Text = "Hello World" Demo(2).B(1) = 1024 Demo(3).C = 32767 REDIM _RETAIN Demo(10) AS T PRINT "Array Demo now contains 10 indexes:"; UBOUND(Demo) PRINT Demo(5).Text PRINT Demo(2).B(1) PRINT Demo(3).C REDIM _RETAIN Demo(4) AS T PRINT "Array Demo now contains 4 indexes:"; UBOUND(Demo) IF UBOUND(Demo) > 4 THEN PRINT Demo(5).Text ELSE PRINT "Index 5 not exists!" PRINT Demo(2).B(1) PRINT Demo(3).C |
See also