The DIM statement is used to declare a variable or a list of variables as a specified data type or to dimension $STATIC or $DYNAMIC Arrays.
Syntax
To declare variables:
DIM [SHARED] variable[{suffix AS [_UNSIGNED] type}] [, variable2…]] To declare arrays:
DIM [SHARED] array([lowest% TO] highest%])[{suffix AS [_UNSIGNED] type}] [, variable2…] QB64 Alternative Syntax:
DIM [SHARED] AS [_UNSIGNED] typevariable [, variable2…]
DIM [SHARED] AS [_UNSIGNED] typearray([lowest% TO] highest%]) [, array2(elements)…]
Description
- Sets the INTEGER range of elements (indices) of a STATIC array. If only one number is used, the LBOUND is 0 by default.
- When used before an array is dimensioned, OPTION BASE 1 can set the default LBOUND of arrays to 1.
- DIM SHARED shares variable values with sub-procedures without passing the value in a parameter.
- Use the AS keyword to define a variable or array type AS…
- QB64 variable types:
- _BIT (or use variable suffix `). An AS multiplier can be used for multiple bits. Ex:
DIM *variable* AS _BIT * 8 - _BYTE (or use variable suffix %%)
- _INTEGER64 (or use variable suffix &&)
- _FLOAT (or use variable suffix ##)
- _OFFSET (or use variable suffix %&)
- DIM AS _MEM (the _MEM type has no type suffix).
- _BIT (or use variable suffix `). An AS multiplier can be used for multiple bits. Ex:
- Note: When a variable has not been defined or has no type suffix, the type defaults to SINGLE.
- When using the AS type variable-list syntax, type symbols cannot be used.
- When the $DYNAMIC metacommand or REDIM is used, array element sizes are changeable (not $STATIC).
- Use REDIM instead of DIM to dimension arrays as dynamic without the $DYNAMIC metacommand.
- Use REDIM _PRESERVE in QB64 to retain previous array values when changing the size of an array.
- REDIM _PRESERVE cannot change the number of array dimensions. An ERROR Codes will occur.
- $DYNAMIC arrays MUST be REDIMensioned if ERASE or CLEAR are used, as the arrays are completely removed.
- All numerical variable types except SINGLE, DOUBLE and _FLOAT can be dimensioned as _UNSIGNED (suffix ~) or positive only.
- NOTE: Many QBasic keyword variable names can be used with a STRING suffix ($). You cannot use them without the suffix, use a numerical suffix or use DIM, REDIM, _DEFINE, BYVAL or TYPE variable AS statements. Although possible, it’s recommended to avoid using reserved names.
- Warning: Do not use negative array upper bound index values, or OS access or “Out of Memory” ERROR Codes will occur.
Example(s)
Defines Qt variable as a one byte fixed length string.
DIM Qt AS STRING * 1
Dimensions and types an array.
DIM Image(2000) AS INTEGER
Dimensions array with an INTEGER type suffix.
DIM Image%(2000)
Dimensions a range of Arrays elements as SHARED integers.
DIM SHARED Image(1 TO 1000) AS INTEGER
Dimensions variable as an Arrays of 8 elements of the type UNSIGNED BIT.
DIM bit(8) AS _UNSIGNED _BIT
QB64 is more flexible than QBasic when it comes to “Duplicate Definition” errors. The following code does not error:
x = 1 'x is a SINGLE variable
PRINT x
DIM x AS LONG
PRINT x
Explanation: The SINGLE variable can be differentiated from the LONG x variable by using suffixes like x! or x& in later code.
The following code will create a “Name already in use” status error in QB64 when the variable types are the same.
x = 1 'x is a SINGLE variable
PRINT x
DIM x AS SINGLE
PRINT x
Explanation: QB64 gives an error because the creation of the new variable would make referring to the existing one impossible.
Using QB64’s alternative syntax to declare multiple variables/arrays of the same type.
DIM AS LONG w, h, id, weight, index 'all of these variables are created as type LONG
DIM AS SINGLE x, y, z 'all of these variables are created as type SINGLE