DIM

Source: https://www.freebasic.net/wiki/wikka.php?wakka=KeyPgDim Last revised: 2024-03-07

Declares a variable by name and reserves memory to accommodate it.

Syntax

Declaring variables:

Dim [Shared] name1 As DataType [, name2 As DataType, ...]
Dim [Shared] As DataType name1 [, name2, ...]

Arrays:

Dim name ( [lbound To] ubound [, ...] ) As DataType
Dim name ( Any [, Any...] ) As DataType
Dim name ( ) As DataType

Initializers:

Dim scalar_symbol As DataType = expression | Any
Dim array_symbol (arraybounds) As DataType = { expression [, ...] } | Any
Dim udt_symbol As DataType = ( expression [, ...] ) | Any

Description

Declares a variable by name and reserves memory to accommodate it. Variables must be declared before they can be used in the -lang fb dialect or when using Option Explicit in the other dialects. Only in the -lang qb and -lang fblite dialects variables may be used without first declaring them, in such a case they are called implicit variables.

Dim can be used to declare and assign variables of any of the supported data types, user defined types, or enumerations. Depending on where and how a variable or array is declared can change how it is allocated in memory. See Storage Classes. More than one variable may be declared in a single Dim statement by separating each variable declaration with a comma.

'' Variable declaration examples
'' One variable per DIM statement
Dim text As String
Dim x As Double

'' More than one variable declared, different data types
Dim k As Single, factor As Double, s As String

'' More than one variable declared, all same data types
Dim As Integer mx, my, mz ,mb

'' Variable having an initializer
Dim px As Double Ptr = @x

Explicit Variables with Implicit Data Types

In the -lang qb and -lang fblite dialects, even if the variable is declared explicitly, it will be given a default data type if the data type is not explicitly given either by name or by type suffix. The default data type is Single in the -lang qb dialect and Integer in the -lang fblite dialect. The default data type can be changed throughout a source listing by use of the Def### statements (for example, DefInt, DefStr, DefSng).

'' Compile with -lang qb
'$lang: "qb"

'' All variables beginning with A through N will default to the INTEGER data type
'' All other variables default to the SINGLE data type
DefInt I-N

Dim I, J, X, Y, T$, D As Double
'' I and J are INTEGERs
'' X and Y are SINGLEs
'' T$ is STRING
'' D is DOUBLE

Arrays

As with most BASIC dialects, FreeBASIC supports arrays with indexes ranging from a lower bound to an upper bound. In the syntaxes shown, lbound refers to the lower bound, or the smallest index. ubound refers to the upper bound, or the largest index. If a lower bound is not specified, it is assumed to be zero by default, unless Option Base is used.

Const upperbound = 10
'' Declare an array with indexes ranging from 0 to upperbound,
'' for a total of (upperbound + 1) indexes.
Dim array(upperbound) As Single

Multidimensional arrays can be declared as well, and are stored in this definite order: values differing only in the last index are contiguous (row-major order). The maximum number of dimensions of a multidimensional array is 8.

'' declare a three-dimensional array of single
'' precision floating-point numbers.
Dim array(1 To 2, 6, 3 To 5) As Single

Initializers

Arrays, variables, strings, and user defined types (UDTs) are initialized to zero (or False for Boolean) or null strings by default when they are created. To avoid the overhead of default variable initialization, the Any initializer can be used with Dim to tell the compiler to only reserve the place for the variable in memory but not initialize it, so the variable will contain garbage.

'' Declare an array of 2 by 5 elements and initialize
Dim array(1 To 2, 1 To 5) As Integer => {{1, 2, 3, 4, 5}, {1, 2, 3, 4, 5}}

'' declare a simple UDT
Type mytype
    var1 As Double
    var2 As Integer
End Type

'' declare a 3 element array and initialize the first 2 mytype elements
Dim myvar(0 To 2) As mytype => {(1.0, 1), (2.0, 2)}

Examples

Dim a As Byte
Dim b As Short
Dim c As Integer
Dim d As LongInt
Dim au As UByte
Dim bu As UShort
Dim cu As UInteger
Dim du As ULongInt
Dim e As Single
Dim f As Double
Dim g As Integer Ptr
Dim h As Byte Ptr
Dim s1 As String * 10   '' fixed length string
Dim s2 As String        '' variable length string
Dim s3 As ZString Ptr   '' zstring

s1 = "Hello World!"
s2 = "Hello World from FreeBASIC!"
s3 = Allocate( Len( s2 ) + 1 )
*s3 = s2

Print "Byte: "; Len(a)
Print "Short: "; Len(b)
Print "Integer: "; Len(c)
Print "Longint: "; Len(d)
Print "UByte: "; Len(au)
Print "UShort: "; Len(bu)
Print "UInteger: "; Len(cu)
Print "ULongint: "; Len(du)
Print "Single: "; Len(e)
Print "Double: "; Len(f)
Print "Integer Pointer: "; Len(g)
Print "Byte Pointer: "; Len(h)
Print "Fixed String: "; Len(s1)
Print "Variable String: "; Len(s2)
Print "ZString: "; Len(*s3)

Deallocate(s3)

Version

• Since fbc version 1.20.0, fixed-length strings of STRING*N type are initialized to space value (zero value previously).

Dialect Differences

• In the -lang qb and -lang fblite dialects, variables have procedure scope if the variable is defined inside a procedure, and for the entire module if the variable is defined with Dim Shared.
• In the -lang qb dialect, variables cannot be initialised. In the -lang fblite dialect, the variable is initialised with a default value at the start of the procedure/module, and assigned its initial value if/when the Dim statement is executed at runtime.
• In the -lang fb and -lang deprecated dialects, variables declared inside compound block statements have local working scopes, and are visible only within these blocks.

Differences from QB

• Variable Initializers are new to FreeBASIC.
• The alternate syntax Dim As DataType symbolname, [...] is new to FreeBASIC.
• Multidimensional arrays are stored in row-major order (QB used column-major order by default).
• Variable length arrays up to 2 GiB in size are possible in FreeBASIC.
• The ellipsis form for upper bounds is new to FreeBASIC.

See Also

• Var
• Redim
• Shared
• Static
• Erase
• LBound
• UBound