Syntax
xref arrayName( maxSub1 [ , maxSub2 ... ] ) [ as dataType ]
Description
The 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
The maxSub1, 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.
Note
xref is a non-executable statement, so you can't change its effect by putting it inside a conditional-execution structure such as if...end if. However, you can conditionally include it or exclude it from the program by putting it inside a #if...#endif block. The xref statement should appear somewhere above the first line where the array is referenced.
See also
dim; xref@
