OLE types: ARRAY

An array is a variable consisting of any number of variables (elements) of the same type that are accessed by index. In QM, you can use safe arrays (described in this topic), pointer-based arrays, embedded arrays and string maps.

A variable of type ARRAY is an OLE-Automation-compatible dynamic (resizable) multi-dimensional (1 to 10 dimensions) safe array.

When declaring a variable of type ARRAY, you also must specify the type of elements. Syntax:

The array must have the element, or will be generated run-time error. There are several functions and other ways to add elements. Read about it later in this topic.

ARRAY(str) a ;;declare array of strings
a.create(10) ;;add 10 empty elements
a[0]="first element" ;;set first element
str s
s=a[0] ;;assign value of first element to a variable
out s

ARRAY(str) am.create(3 10) ;;2 dimensions, 3 elements in first dimension, 10 in second
int i j
for i 0 am.len(2) ;;enumerate dimension 2
	for j 0 am.len(1) ;;enumerate dimension 1
		am[j i].from(j " " i)
		out am[j i]

QM 2.2.1. To add one element to a 1-dimension array and assign a value, can be used empty []. In older QM versions, and with multidimensional arrays, instead use redim. Examples:

int i
ARRAY(int) ar
for(i 0 5) ar[ar.redim(-1)]=i ;;adds and sets 1 element; works in all QM versions
for(i 0 ar.len) out ar[i]

ARRAY(int) a
for(i 0 10) a[]=i ;;adds and sets 1 element
for(i 0 a.len) out a[i]

ARRAY(str) b
for(i 0 10) b[].from("element " i) ;;adds and sets 1 element
for(i 0 b.len) out b[i]

ARRAY(str) c
for(i 0 10)
	str& s=c[] ;;adds 1 element and gets reference to it
	s.from("element " i) ;;modifies the element
	s+" in array c" ;;modifies the element
for(i 0 c.len) out c[i]

To populate a string array with multiple values, you can assign a multiline string. You also can assingn array to a str variable. Examples:

ARRAY(str) a="zero[]one[]two"
int i
for(i 0 a.len) out "%i %s" i a[i]

str s=a
out s

ARRAY variables are freed automatically. If you need to explicitly remove all elements, assign 0 or use redim without arguments:

ARRAY can be used in user-defined types, but cannot be used in embedded arrays. Example:

type ABC int'x ARRAY(BSTR)'a

ARRAY can be passed to functions. When passing to an user-defined function, whole array is copied, unless it is passed by reference (address of ARRAY variable). Arrays are not copied when passing to other functions (not user-defined). COM functions usually accept SAFEARRAY*, which is the same as ARRAY, therefore ARRAY variable can be simply passed. Dll functions that accept arrays usually expect direct pointer to array data (not ARRAY or SAFEARRAY*). Then you can pass address of first element (e.g., &arr[0]).

A variable of type ARRAY actually is pointer (4 bytes) to array descriptor. The array descriptor (structure of type SAFEARRAY), along with other properties, holds the pointer to the actual data. All memory allocation is managed automatically.

ARRAY is compatible with Visual Basic dynamic array. However, elements of multidimensional array are stored differently than in C or Pascal arrays. For example, ARRAY(int) a.create(x y) creates array that by storage order is equivalent to C array declared as int a[y][x], that is, order of dimensions is reverse.

ARRAY type supports operator = (assign). When you assign one array to another, whole array is copied, including all associated data.

You can also assign string (str, lpstr or BSTR) to array of str or BSTR type. Result will be single-dimensional array of strings where each string is one line from source string. If you assign single-dimensional array of strings to str or BSTR variable, result will be string where every line is element of source array. If array is multidimensional, result will be string where all elements are joined.

Array also can be assigned to variable of type VARIANT. When VARIANT variable is destroyed, or type is changed, containing array is freed. If you use operator =, array is copied. If you use function attach on VARIANT variable, it stores array into that variable, and sets ARRAY variable to 0.

To declare a global variable or pointer to ARRAY, etc, use appropriate characters after the closing parenthese. Examples:

ARRAY(str) as  local array of str variables
ARRAY(int)+ ai  global array of int variables
ARRAY(VARIANT) av  local array of VARIANT variables. VARIANT can contain other data types, therefore we can say that array element types can be different.
ARRAY(RECT) ar  local array of RECT structures
ARRAY(RECT*) arp  local array of pointers to RECT structures
ARRAY(int)* pai = &ai  local pointer to array of int variables

Functions

The ARRAY type has several functions, described below. Here var is variable of type ARRAY. If a return type is not specified, the function returns var itself.

When ARRAY variable is just declared, it is 0, that is, does not have any data. This function creates and initializes array descriptor and data. n1, n2, etc are number of elements in each dimension. Array can have 1 to 10 dimensions. Lower bound of each dimension is 0. This function also can be used to resize array without preserving previous content. In this case, it destroys old array and creates new array. If used without arguments, only allocates array descriptor.

This function differs from create only that it allows setting lower bounds to a value other than 0. lb1, lb2, etc are lower bound (index of first element) of each dimension. It can be negative.

Resizes right-most dimension of array or creates 1-dimension array. Elements that exist in both old and new array are preserved. n is new number of elements. Negative n will add -n elements. If n is omitted, array and associated data is freed and var is set to 0. You can also free array by assigning 0 to it. lb is new lower bound. If lb is omitted, it stays unchanged (or 0 for new array). If array is growing, function returns index of first added element (rightmost dimension). If array is shrinking, the return value is undefined.

Locks array (increments lock count). If lock count is nonzero, array cannot be resized or destroyed (for example, by other threads or applications). Calls to lock can be nested. An equal number of calls to unlock are required. Failing to unlock causes memory leak.

Returns the lower bound (index of first element) in the specified or rightmost dimension. dim is 1-based dimension index.

Returns the upper bound (index of last element) in the specified or rightmost dimension.

sortfunction - name of an user-defined callback function. Required only if type of array elements is not str, lpstr, int, byte, word, double or long.

The callback function is used for custom sorting. It is called (multiple times) while sorting, and must compare two elements in the array. It must begin with

param - param of sort. Also can be declared as pointer or reference of any type. If it is pointer or reference, pass address of a variable of that type to sort as param.

 sorts multiline string
str s="zero[]one[]TWO[]THREE"
ARRAY(str) a=s
a.sort(2)
s=a
out s

1	Sort descending. By default sorts ascending. This flag also is applied when using sort function.
2	Case insensitive. Used when type of array elements is str or lpstr, except when using sort function.