dim statement

	<< Index >>	FutureBasic
dim		statement

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

Syntax 2
dim varName as varType

Description
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

Records:

varName as recordType
varName.constant

Arrays:

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

Pointers:

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

Handles

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

Memory alignment declarations:

{%|&|&&|&&&|.constant}

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:

Arrays (unless declared in an xref or xref@ statement)
Record variables
Variables of user-defined types
Pointer variables and Handle variables

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:

maxLen + 1 bytes, if maxLen is odd;
maxLen + 2 bytes, if maxLen is even;

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:


    p(0,0)

    p(0,1)

    p(0,2)

    p(1,0)

    p(1,1)

    p(1,2)

    p(2,0)

    p(2,1)

    p(2,2)

    p(3,0)

    p(3,1)

    p(3,2)

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
Optionally:
long value = 12

Multiple simple variables:
dim as CFStringRef s1 = @"One", s2 = @"Two", s3 = @"Three"
Optionally:
CFStringRef s1 = @"One", s2 = @"Two", s3 = @"Three"

Records:
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 float buy

dim as float sell

end record

begin record ItemInfo

dim as long itemID

dim as long qty

dim as ItemPrice price

dim as long order

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

`begin record ItemPrice`
	dim as float	`buy`
	dim as float	`sell`
end record

begin record `ItemInfo`
	dim as long	`itemID`
	dim as long	`qty`
	dim as `ItemPrice`	`price`
	dim as long	`order`
end record