R-2: VARIABLE HANDLING COMMANDS 

To keep track of numbers and text program variables are required. These variables
are assigned a name and given a type which dictates the sort of information they are
able to contain. Blitz supports 5 standard numeric types and the string type which
is used to store text type information.

Variable "arrays" are used to store a large collection of values all of one type,
these arrays are similar to normal variables except they must be dimensioned (the
number of elements defined) before they are used.

Blitz offers many extensions to these BASIC features. NewTypes may be defined which
are a collection of several standard types. a single NewType variable can contain an
assortment of numeric and string information similar to structures in C.

List arrays offer the programmer more control over standard arrays, they are also
much easyer to manipulate. Blitz contains many commands for operating on LINKed
lists of data.


Let Var=Expression 

Let is an optional command used t<> assign a value to a variable. Let must always be
followed by a variable name and an expression. Normally, an equals sign ('=') is
placed between the variable name and the expression. If the equals sign is omitted,
then an operator (eg: '+', '*') must appear between the variable name and the
expression. In this case, the specified variable will be altered by the specified
operator and expression.


Exchange Var,Var 

Exchange will 'swap' the values contained in the 2 specified variables. Exchange may
only be used with 2 variables of the same type.


MaxLen StringVar=Expression 

MaxLen sets aside a block c>f memory for a string variable to grow into. This is
normally only necessary in the case of special Blitz commands which require this
space to be present before execution. Currently, only 2 Blitz commands require the
use of MaxLen:FileRequest$ and Fields.


DEFTYPE .Typename [Var[,Var...]] 

DEFTYPE may be used to declare a list of variables as being of a particular type. In
this case, Var parameters must be supplied.

DEFTYPE may also be used to select a default variable type for future 'unknown'
variables. Unknown variables are variables created with no Typename specifier. In
this case, no Var parameters are supplied.


NEWTYPE.Typename 

NEWTYPE is used to create a custom variable type. NEWTYPE must be followed by a list
of entry names separated by colons (':') and/or newlines. NEWTYPEs are terminated
using End NEWTYPE.


SizeOf.Typename[,Entrypath] 

SizeOf allows you to determine the amount of memory, in bytes, a particular variable
type takes up. SizeOf may also be followed by an optional Entrypath, in which case
the offset from the start of the type to the specified entry is returned.


Dim Arrayname [List] (Dimensionl[,Dimension2...]) 

Dim is used to initialize a BASIC array. Blitz supports 2 array types - simple
arrays, and list arrays. The optional List parameter, if present, denotes a list
array. Simple arrays are identical to standard BASIC arrays, and may be of any
number dimensions. List arrays may be of only 1 dimension.


ResetList Arraynam() 

ResetList is used in conjunction with a list array to prepare the list array for
NextItem processing. After executing a ResetList, the next Nextitem executed will
set the list array's 'current element' pointer to the list array's very first


ClearList Arraynam() 

ClearList is used in conjunction with list arrays to completely 'empty' out the
specified list array. List arrays are automatically emptied when they are Dimmed.


AddFirst (Arrayname()) 

The AddFirst function allows you to insert an array list item at the beginning of an
array list. AddFirst returns a true/false value reflecting whether or not there was
enough room in the array list to add an element. If an array element was available,
AddFirst returns a true value (-1), and sets the list array's 'current item' pointer
to the item added. If no array element was available, AddFirst returns false (0).


AddLast (Arrayname()) 

The AddLast function allows you to insert an array list item at the end of an array
list. AddLast returns a true/false value reflecting whether or not there was enough
room in the array list to add an element. If an array element was available, AddLast
returns a true value (-1 ), and sets the list array's 'current item' pointer to the
item added. If no array element was available, AddLast returns false (0).


Additem (Arrayname()) 

The AddItem function allows you to insert an array list item after the list array's
'current' item. AddItem returns a true/false value reflecting whether or not there
was enough room in the array list to add an element. If an array element was
available, Additem returns a true value (-1), and sets the list array's 'current
item' pointer to the item added. If no array element was available, Additem returns
false (0).


KillItem ArrayName() 

KillItem is used to delete the specified list array's current item. After executing
KillItem, the list array's 'current item' pointer will be set to the item before the
item deleted.


Previtem (Arrayname()) 

Previtem will set the specified list array's 'current item' pointer to the item
before the list array's old current item. This allows for 'backwards' processing of
a list array. Previtem returns a true/false value reflecting whether or not there
actually was a previous item. If a previous item was available, PrevItem will return
true (-1 ). Otherwise, PrevItem will return false (0).


Nextitem (Arrayname()) 

Nextitem will set the specified list array's 'current item' pointer to the item
after the list array's old current item. This allows for 'forwards' processing of a
list array. Nextitem returns a true/false value reflecting whether or not there
actually was a next item available or not. If an item was available, Nextitem will
return true (-1 ). Otherwise, Nextitem will return false (0).


Firstitem (Arrayname()) 

Executing Firstitem will set the specified list array's 'current item' pointer to
the very first item in the list array. If there are no items in the list array,
Firstitem will return false (0) otherwise, Firstitem will return true (-1).


Lastitem (Arrayname()) 

Executing Lastitem will set the specified list array's 'current item' pointer to the
very last item in the list array. If there are no items in the list array, Lastitem
will return false (0), otherwise Lastitem will return true (-1).


Pushitem Arrayname() 

Executing Pushitem causes the specified list array's 'current item' pointer to be
pushed onto an internal stack. This pointer may be later recalled by executing
Popitem. The internal item pointer stack is set for up to 8 'pushes'.

Popitem Arrayname() 

Popitem 'pops' or 'recalls' a previously pushed current item pointer for the
specified list array. Arrayname() must match the arrayname of the most recently
executed Pushitem.


ItemStackSize Max Items 

ItemStackSize determines how many 'list' items may be pushed (using the Pushltem
command), before items must be 'Pop'ped off again. For example, executing
ItemStackSize 1000 will allow you to push up to 1000 list items before you run out
of item stack space.


SortList Arrayname() 

The SortList command is used to rearrange the order of elements in a Blitz LINKed
list. The order in which the items are sorted depends on the first field of the
LINKed list type which must be a single integer word. Sorting criteria will be
extended in future releases.


Sort Arrayname()

Sort will cause the specified array to be sorted.

The direction of the sort may be specified using either the SortUp or SortDown
commands. The default direction used for sorting is ascending - ie: array elements
are sorted into a 'low to high' order.


SortUp 

SortUp may be used to force the Sort command to sort arrays into ascending order.
This means that, after being sorted, an array's contents will be ordered in a 'low
to high' manner.


SortDown 

SortDown may be used to force the Sort command to sort arrays into descending order.
This means that, after being sorted, an array's contents will be ordered in a 'high
to low' manner.