REDIM

A REDIM statement can re-dimension one dynamic(flexible) array or a comma separated list of arrays.

Syntax

REDIM [{_PRESERVE|_RETAIN}] [ SHARED ] ArrayName[typesuffix] ({max_element|low_element[ TO upper_element, ...]}) [ AS Type ]

Description

• Can change the number of elements in an array (the present array data is lost unless _PRESERVE or _RETAIN is used).
• The _PRESERVE option will preserve existing values when resizing an array:
  • In one-dimensional arrays all stored values are preserved unless the array was downsized, then the no longer existing elements are lost. If an array is upsized the new elements are zero, empty or filled with CHR$(0), depending on its type.
  • In QB64(PE) it will also move the element values upward or downward, if the lower bound was changed. Depending on the new index range, overflowing elements will be lost, new elements zero, empty or filled with CHR$(0), depending on its type.
  • In multi-demensional arrays the function is generally the same as for one-dimensional arrays, but only correctly performed on the last (right-most) dimension. When resizing any other dimension, then the values are messed up.
• The _RETAIN option will also preserve existing values when resizing an array, but different:
  • This will never move the element values upward or downward when resizing, but always holds the values fix to its respective index. When lower and/or upper bounds change, then the still existing indexes retain their values, non-existent are lost and new indexes are initialized as usual.
  • Regardless of the number of dimensions this will always work, doesn't matter which of the dimensions is changed.
• Array is the name of the array to be dimensioned or re-dimensioned.
• elements is the number of elements the array should hold. Use the optional TO elements2 to set a range.
• Always use the same array TYPE suffix (or AS type) or a new array type with the same name may be created.
• REDIM cannot change $STATIC arrays created with a DIM statement unless the $DYNAMIC Metacommand is used.
• To create a dynamic array use the $DYNAMIC metacommand or use REDIM rather than DIM when first creating the array.
• Use REDIM _PRESERVE to change the range or number of array elements without losing the remaining elements. Data may move up or down to accommodate those boundary changes.
• Use REDIM _RETAIN to change the range or number of array elements without losing the remaining elements, but without moving the values to accommodate those boundary changes.
• REDIM _PRESERVE or _RETAIN cannot change the number of array dimensions or type
• Dynamic arrays must be REDIMensioned if ERASE or CLEAR are used to clear the arrays as they no longer exist.
• Do not use negative array upper bound index values as OS access or "Out of Memory" errors will occur.

Availability

• 
  all
• 
  all
• 
• 
  yes
• 
  yes
• 
  yes

• The _PRESERVE option was implemented in QB64 v0.872
• The _RETAIN option was implemented in QB64-PE v4.5.0

Examples

Example 1

The $DYNAMIC Metacommand allows an array to be re-sized using DIM and REDIM.

'$DYNAMIC INPUT "Enter array size: ", size DIM Array(size) REDIM Array(2 * size) PRINT UBOUND(Array)

---

Example 2

Shows the difference between REDIM and REDIM _PRESERVE.

REDIM array(20) array(10) = 24 PRINT array(10) REDIM _PRESERVE array(30) PRINT array(10) REDIM array(15) PRINT array(10)

24 24 0

Explanation: REDIM without _PRESERVE erases the array data and cannot change the number of dimensions.

See also

• Arrays
• DIM, SHARED
• _PRESERVE, _RETAIN, ERASE
• $DYNAMIC, $STATIC

---

Navigation: Main Page with Articles and Tutorials Keyword Reference - Alphabetical Keyword Reference - By usage Report a broken link