Arrays
Updated: Aug 27, 2009

Dimension Statements -- Arrays of Variables and Objects
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Arrays of variables and selected objects are created with the same DIM
statement syntax adding subscript ranges immediately after the user_symbol.

  DIM A(99) As LONG  'same as DIM A(0 TO 99) As LONG

creates a 0-based array A with 100 LONG items.

  DIM A(1 TO 100) As LONG

creates a 1-based array A with 100 LONG items.

  DIM A(99,99) AS LONG

creates a 0-based two-dimensional array A with 10,000 LONG items.

For STRING data, we define the length of each array item with *n syntax where
n is item length.

  DIM A(99) As STRING*64

IF the *n notation is omitted, item length defaults to 256 bytes.

STRING arrays may store text data or binary data.  With text data,

  A(i) = MyString  'stores MyString as item i

IF MyString.Length > array item size n, MyString is truncated to length n.

For binary data like a UDT,

  DIM A(99) As MYTYPE  'where MYTYPE is a UDT or Custom object.
  DIM u As MYTYPE
  u = A(i)  'get UDT i
  'code to read/write members of u
  A(i) = u  'put UDT i

or perhaps even easier:

  DIM A(99) As MYTYPE
  USE u as MYTYPE with @A+i*sizeof(MYTYPE)
  'code to read/write members of u which are A(i)
  END USE u

For UDT arrays, HotBasic does not write any constructor values in the TYPE/
OBJECT definition into the array elements.  To initialize UDT arrays, DIM an
instance u, as above, and manually copy u into each array element.

  FOR i = 0 to 99: A(i)=u: NEXT i

Since this is sequential access to the array, a faster method is:

  A.Postion = 0  'needed only if A() has already been accessed
  FOR i = 0 to 99: A.WriteUDT(u): NEXT i

INITARRAY is *not* needed at program startup for any array.  All arrays in
HotBasic are already initialized to zero at startup.  INITARRAY is a
convenient way to clear an array at run-time.

Array subscript range is -2147483648 to 2147483647.  Maximum array size is
about 4 gigabytes or available RAM.  One to five subscripts may be used to
access array elements.

The REDIM statement may be used to change the number or range of subscripts
or size of an array (Statements > Miscellaneous).

Arrays of Objects (+): FILE, FONT, MEMORY, RECT and 26 FORM objects: BUTTON,
CANVAS, CHECKBOX, COMBOBOX, DATETIME, EDIT, FILELISTBOX, FORM, GAUGE, GRID,
GROUPBOX, HEADER, IMAGE, LABEL, LISTBOX, LISTVIEW, PANEL, RADIOBUTTON,
RICHEDIT, RICHEDIT2, SCROLLBAR, SPLASH, TABCONTROL, TRACKBAR, TREEVIEW and
UPDOWN.

For MEMORY objects, if array size is increased with REDIM, the .Initialize
method should be used to "set up" the new elements.

For FORM objects,

(1) if array size is increased with REDIM, the REDIMEX statement is required
to create the additional objects and maintain proper coordination between
the application and operating system (Statements > Advanced Techniques)

(2) 64 4-byte slots in a run-time table are allocated at compile-time for
each array.  That is, the total number of table slots for such arrays is 64
x the number of FORM object arrays.

Example.  If one array has 120 objects and another has 8, this conforms to
the total slots allocated (120 + 8 = 2 * 64).  If you have two arrays of 80
elements each, then use the $GUIOBJ 32 Directive to add 32 more slots at
compile-time (80 + 80 = 2 * 64 + 32).

Please see the ARRAYREF family of keywords to read/write array elements by
pointer, useful in writing procedures which can act on any array.


+  Penthouse (Registered) version

Copyright 2003-2009 James J Keene PhD
Original Publication: Oct 9, 2003