xref arrayName(maxSub1[,maxSub2 ...]) [as dataType]
xref statement declares an array, and associates the array with the memory pointed to by a particular pointer variable, called the "link variable." You can use
xref to cause any arbitrary block of memory to be treated as an array. This is especially useful when you need to dynamically create an array whose size can't be determined until runtime, or when you want to impose an array structure on data that was created outside of your FutureBasic program.
The link variable must be a simple (non-array, non-field) pointer variable which has the same name as the array (ignoring any type-identifier suffix). For example, if you specify the following:
xref diameter(3,7) as long
The compiler creates a long-integer variable called
diameter. When you run the program, you should set
diameter equal to some appropriate memory address (you do this after the
xref statement); FutureBasic then assumes that the
diameter() array begins at that address. When you examine elements in the array, they are retrieved from the memory pointed to by
diameter. When you alter elements in the array, the memory pointed to by
diameter is altered.
The first subscript is arbitrary
maxSub2 etc. values must be positive static integer expressions. However, since
xref does not actually allocate any memory, the declared subscripts are used somewhat differently than in a
dim statement. The second and subsequent subscripts (if any) determine the internal structure of the array, and they should exactly match the internal layout of the elements pointed to by the link variable. But the value of the first subscript (
maxSub1) is basically ignored, and may be arbitrarily set to any value greater than zero. When you actually reference the array elements, you can use subscript values that are larger than
maxSub1, as long as they reference valid elements within the block of memory pointed to by the link variable. However, whilst the first subscript (
maxSub1) is generally ignored, the value of
maxSub1 gets used for bounds testing when the Preferences setting for "Check Array Bounds" is enabled.
xref is a non-executable statement, so you can't change its effect by putting it inside a conditional-execution structure such as
long if...end if. However, you can conditionally include it or exclude it from the program by putting it inside a
...#endif block. The
xref statement should appear somewhere above the first line where the array is referenced.