<<    Index    >>	FutureBasic
Appendix B - Variables		appendix

In FutureBasic, a variable can be thought of as a named container for data. The "container" has a specific size and (usually) a specific address in memory. Also, each variable has a specific type which determines how FutureBasic interprets its contents (See Appendix C - Data Types and Data Representation). You can copy data into a variable by putting the variable on the left side of the "=" symbol in a let statement; or by explicitly modifying the contents at the variable's address (through statements like poke and BlockMove). Certain other FutureBasic statements and functions (such as swap and inc) may also modify a variable when you include the variable as a parameter. In FutureBasic, a variable can have any of the following forms:

• identifier[tiSuffix]
  A simple string or numeric variable, such as: myLong&, or theString$. tiSuffix is the optional type-identifier suffix, such as "$", "%", "&", etc. See the dim statement, and Appendix C - Data Types and Data Representation, for a complete list of type-identifier suffixes. Examples:
  myIntVar
xyz&`


• stringVar$[offset] (Note the square brackets are part of the variable)
  This variable consists of the single byte which is located at offset bytes past the beginning of the string variable stringVar$. (The $ is required) This variable's type is unsigned byte. This kind of variable is normally used to quickly retrieve or alter a single character in a string. The statement, "x=stringVar$[offset]" is equivalent to: "x=peek(@stringVar$+offset)". The statement, "stringVar$[offset]=x" is equivalent to: "poke@stringVar$+offset,x". Examples:
  firstname$[3]


• pointerVar
  A pointer variable. This is an identifier declared as a pointer type; it can be declared either as a "generic" pointer, or a pointer to some other specific type. Examples:
  myPtr
anotherPtr


• handleVar
  A handle variable. This is an identifier declared as a Handle type; it can be declared either as a "generic" handle, or a handle to some other specific type. Examples:
  myHandle
thisHdl


• recordName
The variable is an entire record declared using dim recordName as RecordType). Examples:
  myRec
iopb



• arrayName[tiSuffix](expr1 [,expr2...])
The variable is a specific element of an array. This can be an array of any type, but tiSuffix can only be used in numeric or string arrays. Note that an entire array is not considered to be a variable. Examples:
  firstName$(15)
recArray(3, x%)



• addressVar&.const1[.const2...]tiSuffix
The variable consists of the bytes located at a specific offset from the address given in addressVar&. The address of this variable is at (const1 + const2 + ...) bytes past the given address; the size and type of this variable are determined by tiSuffix. addressVar&must be a (signed or unsigned) long-integer variable, or a generic pointer variable. addressVar& must be a "simple" variable; it cannot be an array element nor a record field. Examples:
  recPtr&.myField%`
genericPtr.rectangle.right%


• handleVar&..const1[.const2...]tiSuffix
The variable consists of the bytes located at a specific offset from the beginning of the relocatable block referenced by handleVar&. The address of this variable is at (const1 + const2 + ...) bytes past the beginning of the block. The size and type of this variable are determined by tiSuffix. handleVar& must be a (signed or unsigned) long-integer variable, or a generic Handle variable. handleVar& must be a "simple" variable; it cannot be an array element nor a record field. Examples:
  recHdl&..thisField.thatField$
genericHandle..someField``

Variables involving fields of "records"
The fields of a "record" are defined inside a begin record...end record block. A field's declared data type can be any valid type; if a field is itself declared as another "record" type, then the field can have "subfields," which are just the fields of that secondary record.
A field can also be declared as an array (of any type). In this case, whenever the field's name is included as part of a variable specification, it must be followed by subscript(s) in parentheses. Thus, in each of the variable descriptions listed below, each field and subfield takes one of the following forms, depending on whether or not it's an array field:
For non-array fields:
field/subfield ::= fieldName[tiSuffix]
For array fields:
field/subfield ::= fieldName[tiSuffix](sub1 [,sub2...])
The type and size of each of the following variables is just the type and size of the last field or subfield specified.

• recordName.field[.subfield ...]
The variable is the specified field or subfield of the specified "record." Examples:
  myRec.myField%
stats.game(7).teamName$(1)


• recordPtr.field[.subfield ...]
The variable is the specified field or subfield of the "record" pointed to by recordPtr. The recordPtr must be declared as a pointer to a specific type of record. Examples:
  ptr1.myField
ptr2.arrayField$(3)


• recordHdl..field[.subfield ...]
  The variable is the specified field or subfield of the "record" referenced by recordHdl. The recordHdl must be declared as a handle to a specific type of record. Examples:
  Hdl1..book(3).title$
Hdl2..phoneNum


• arrayName(expr1[,expr2 ...]).field[.subfield ...]
This variable is the specified field or subfield of a specific element in an array of "records." Examples:
  HouseArray(42,6).streetName$
season(2).game(3).player(6)


• ptrArray(expr1[,expr2 ...]).field[.subfield ...]
This variable is the specified field or subfield in a "record" pointed to by an element in an array of pointers. The array must be declared as an array of pointers to a specific type of record. Examples:
  myPtrArray(n).field3&
ptrArray(6,2).miscInfo.chapter(7).title$


• handleArray(expr1[,expr2 ...])..field[.subfield ...]
This variable is the specified field or subfield in a "record" referenced by an element in an array of handles. The array must be declared as an array of handles to a specific type of record. Examples:
  myHndlArray(7,j)..map
myHndlArray(7,j)..map.quadrant(x,3).icon&

Limitations
Arrays are limited to about 2 gigabytes (each).
The .MAIN file of a project often allocates variables outside of local functions that are not global. These are treated as variables for a local function.