FutureBasic Logo

<<    Index    >> FutureBasic

dim   statement

Syntax 1
[dim as] varType varName1 [= value1] [, varName2 [= value2] ...]

Syntax 2
dim varName as varType

dim is a non-executable statement that allows the compiler to determine how much storage space should be allocated for the declared variables, arrays and record fields, and identifies their data types. dim can also be used to affect the relative storage locations of the declared variables, arrays and fields. The basic syntax is the same for dims within a record and outside a record. There are some exceptions such as arrays inside records, see help for begin record.

A declaration can have any of the following forms:
Simple variables:

{varName | [maxLen] stringVar$}
varName as varType


varName as recordType


varName | [maxLen] stringVar$}(maxSub1[,maxSub2...])
varName (maxSub1 [,maxSub2...]) as varType
varName.constant (maxSub1 [,maxSub2...])


varName as {pointer to|^|@|.}{varType|recordType}


varName as {Handle to|^^|@@|..}{varType|recordType}

Memory alignment declarations:

  • maxLen, maxSub1, maxSub2 and statExpr are (non-negative) static integer expressions.
  • constant is a (non-negative) literal integer or a symbolic constant; but if a symbolic constant is used, its initial underscore character is omitted.
  • stringVar$ is a variable name that ends with a "$" type-identifier suffix.
  • varName is a variable name that may optionally end with a type-identifier suffix.
  • varType is a type name defined in a previous begin record statement or #define statement.
  • recordType is a type name defined in a previous begin record statement. If a dim statement appears within a begin globals...end globals block, then the scope of the declared variables and arrays is global. If it appears within the scope of a local function (but not within a begin globals...end globals block), then the scope of the declared variables and arrays is local to that function or procedure block. If dim appears outside of all local functions and procedure blocks (and outside of any begin globals...end globals block), then the scope of the declared variables and arrays is local to "main."

    Your program can use as many dim statements as you like. The following statement:
    dim as long a, b, c, d
    is equivalent to this pair of statements:
    dim as long a, b
    dim as long c, d

    Certain structures must always be declared in a dim statement, which must appear somewhere above the first line where the structure is used. These structures include:

    Storage space for FutureBasic's built-in types is allocated as follows:

    byte (`, ``), byte, char, Boolean
    1 byte
    short (%, %`), short, int, SInt16, UInt16
    2 bytes
    integer (&, &`), SInt32, UInt32
    4 bytes
    long (&, &`), long, NSInteger, NSUInteger
    8 bytes
    long long SInt64, UInt64
    8 bytes
    single (!), single 4 bytes
    double (#), double 8 bytes
    Str255 256 bytes
    pointer 8 bytes
    Handle 8 bytes

    (Note the storage space for variables can vary between CPU devices. When in doubt, use the sizeof function to make a definite determination of the size of the variable.)

    The storage space allocated for a string variable depends on the value of the maxLen parameter (which cannot exceed 255). If maxLen is omitted, then the most recent maxLen specified in the same dim statement is used. String variables declared using the as Str255 clause always have a maxLen value of 255.

    Once maxLen has been determined for a given string variable, the actual number of bytes allocated for the variable is:

    Your program should not assign a string longer than maxLen characters to a string variable. The storage space for a record variable equals the sum of the lengths of the record's fields, or the value of constant2 (in bytes).

    Storage space for an array is calculated as follows: If elSize is the size in bytes of a single array element, then the space allocated for the entire array is given by the following expression:
    array size = elSize * (maxSub1 + 1) * (maxSub2 + 1) * ...

    All the elements in an array are stored in contiguous locations in memory. If the array is multi-dimensional, then the rightmost dimensions change most rapidly as you step through the elements' locations in memory. For example, if you declare an array as follows:

    dim as short p(3, 2)

    Then the elements of p() are stored in this order in memory:


    Inline assignment
    When using the dim as syntax, variables can be declared and assigned in the same statement.
    dim as may be omitted since it's optional. Some examples are shown below.

    Simple variables:

    dim as long value = 12
    long value = 12

    Multiple simple variables:

    dim as CFStringRef s1 = @"One", s2 = @"Two", s3 = @"Three"
    CFStringRef s1 = @"One", s2 = @"Two", s3 = @"Three"

    A record's field values must be enclosed in braces

    dim as CGPoint pt = { 14, 13 }

    Subrecords must also be enclosed in braces
    begin record ItemPrice
    dim as floatbuy
    dim as floatsell
    end record
    begin record ItemInfo
    dim as longitemID
    dim as longqty
    dim as ItemPrice price
    dim as longorder
    end record

    dim as ItemInfo info = { 54321, 23, { 12.34, 17.53 }, 9 }

    Aliased variables
    Aliased variables are no longer supported. For example, the following syntax cannot be used:
    dim as int;0, hi as byte, lo as byte

    See also
    begin globals; begin record; blockvar; static