An array is a variable consisting of any number of variables (elements) of same type that are accessed by index. You can use safe arrays (read in this topic), pointer-based arrays, embedded arrays, string map and CSV.
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:
ARRAY(type) var
type - any type except ARRAY.
var - variable name.
To access an element, use syntax:
arr[i1 [i2 ...]]
arr - variable of type ARRAY.
i1 - element index in leftmost dimension (dimension 1).
i2 - element index in dimension 2, etc.
Error if the index is invalid (the element does not exist).
There are several functions and other ways to add elements. Read about it later in this topic.
Examples:
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]
To add one element to a 1-dimension array and assign a value, can be used empty []. Examples:
int 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) s+" in array c" for(i 0 c.len) out c[i] ARRAY(POINT) d for(i 0 10) POINT& p=d[] ;;adds 1 element and gets reference to it p.x=i; p.y=i*2 for(i 0 d.len) &p=d[i] out F"{p.x} {p.y}"
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 call redim without arguments:
a=0 or a.redim
Here var is variable of type ARRAY. If a return type is not specified, the function returns var itself.
var.create([n1] [n2 ...])
Creates and initializes array.
n1, n2, ... - number of elements in each dimension.
This function also can be used to resize array without preserving previous content.
If called without arguments, creates array descriptor but does not allocate memory for elements.
var.createlb(n1 lb1 [n2 lb2 ...])
Same as create, but allows you to specify lower bounds.
lb1, lb2, ... - lower bound (index of first element) of each dimension. Can be negative.
int var.redim([n] [lb])
Resizes rightmost dimension. If the array is not created, creates 1-dimension array.
n - new number of elements. Negative n will add -n elements.
lb - new lower bound. If lb is omitted, does not change it.
If array is growing, returns index of the first added element (rightmost dimension). If shrinking, the return value is undefined.
The function preserves elements that exist in both old and new arrays.
If called without arguments, frees the array and sets var to 0. Other way to free array - assign 0 (a=0).
int var.insert(index)
Inserts new empty element. If the array is not created, creates 1-dimension array.
index - element index. If it is index of last element + 1, adds to the end.
Returns index.
Supports multi-dimension arrays. Inserts in the rightmost dimension. For example, if the array has 2 dimensions, where the first used for columns and the second for rows, the function inserts new row.
Added in QM 2.3.2.
var.remove(index)
Deletes an element.
index - element index.
QM 2.3.2. Supports multi-dimension arrays. Removes from the rightmost dimension. For example, if the array has 2 dimensions, where the first used for columns and the second for rows, the function removes whole row.
Note: When removing elements in for loop, start from the end. Example:
ARRAY(str) a="a[]b[]c[]d[]e" int i; for(i a.len-1 -1 -1) if(i&1) a.remove(i) out a
int var.len([dim]) int var.lbound([dim]) int var.ubound([dim])
len returns the number of elements.
lbound returns index of the first element.
ubound returns index of the last element.
dim - 1-based dimension index. Default: rightmost dimension.
int var.ndim
Returns the number of dimensions.
var.sort([flags] [sortfunction] [param])
Sorts array elements.
1 | Sort descending. This flag also is applied when using sort function. |
2 | Case insensitive. |
4 | QM 2.3.2. Linguistic. Uses StrCmp to compare strings. |
8 | QM 2.3.2. Number, linguistic, case insensitive. Uses StrCmpLogicalW to compare strings. It compares numbers in strings as number values, not as strings. |
0x100 (flag) | QM 2.3.3. Date. Converts strings to DATE and compares. If cannot convert both strings, compares like without this flag. |
Flags 2, 4 and 8 used with str and lpstr arrays, when sortfunction not used. If without flags 4 and 8, uses StrCompare to compare strings.
sortfunction - name of a user-defined callback function. Required only if type of array elements is not str, lpstr, int, byte, word, double, long.
param - some value to pass to the sort function. Default: 0.
The callback function is used for custom sorting. It is called multiple times while sorting, and must compare two elements in the array.
A template is available in menu -> File -> New -> Templates.
The function must begin with:
function# param TYPE&a TYPE&b
param - param of sort.
TYPE - type of array elements.
a, b - two array elements.
The callback function must compare a and b, and return:
Example:
sorts multiline string str s="zero[]one[]TWO[]THREE" ARRAY(str) a=s a.sort(2) s=a out s
QM 2.3.2. Supports multi-dimension arrays. Sorts rightmost dimension.
When sorting multi-dimension array, compares first element for each indice of rightmost dimension. For example, if the array has 2 dimensions, where the first used for columns and the second for rows, the function compares the first element in each row. When using callback function, the function receives reference to that element. To compare other element, adjust references as in the example.
function# param str&a str&b initially a and b are elements in column 0 &a=&a+(2*sizeof(a)) &b=&b+(2*sizeof(b)) now a and b are elements in column 2 ...
var.shuffle
Shuffles (randomizes) array elements.
QM 2.3.2. Supports multi-dimension arrays. Shuffles rightmost dimension.
ARRAY functions are not thread-safe. Don't use a single variable in multiple threads simultaneously. It can damage data. If need to use in multiple threads, use lock.