Arrays

Arrays are created using the new ArrDimension function. An array may have from 1 to 5 dimensions, and Arrays can now contain at least 10 million total elements, although this may be constrained by available memory. Array elements are referenced with their subscripts enclosed in square brackets. If an array has more than one dimension, the subscripts are separated with commas.

Eg:

arrayvar[1]

arrayvar[1, 1]

arrayvar[0, 5, 2]

Array subscripts are 0-based. I.e., the first element in an array is array[0].

Array elements can contain any type of WIL value: string, integer, float, etc. You can have different types of values within an array.

You may not pass an array as a parameter to a WIL function (except for functions which state they accept an array), or use it in any sort of operation.

For example:

Message("Value is", arrayvar) ; NOT legal

On the other hand, the following are all supported:

arrayvar[0] = 5

x = arrayvar[0]

Message("Value is", arrayvar[0])

arrayvar = 5 ; Redefines the array to integer type variable

x = arrayvar ; Creates a second variable that points to the array

You can pass arrays to user-defined functions, and you can return arrays with the Return command.

When you pass an array name (i.e., not an array element) as a parameter to a function, the array gets passed "by reference". That is, the function receives a pointer to the array, and is therefore able to make changes to it "in place". This is similar to passing a binary buffer handle to a function, where the function is then able to make wholesale changes to the binary buffer.

In contrast, passing an array element (i.e., with a subscript) to a function is like passing a regular string or integer parameter to a function -- it gets passed "by value". I.e., the function receives the value of the array element, but is not able to modify the array itself. By the same token, when you pass a string to a function like StrUpper:

newstring = StrUpper(oldstring)

The function does not modify the variable "oldstring" at all. If you want to modify the existing variable, you can assign to it the return value of the function, eg:

mystring = StrUpper(mystring)

array[2] = StrUpper(array[2])

Dynamic Arrays

Arrays may also be created dynamically by assigning a value to a previously undefined variable following the new variable's name.

For example:

a[5]= “Hello”

creates an array of 6 elements. The first 5 elements (indexes 0 to 4) are undefined, with the 6th element defined as the string “Hello”.

Existing arrays can be re-dimensioned by assigning a value to an array element that is beyond the upper bound of an existing dimension.

Eg:

a[6]= “World”

increases the size of the array by one element.

Dynamic array assignment is optimized for single dimension arrays. Re-dimensioning multi-dimension arrays is possible, but significantly slower than initially creating an array with the highest required array subscripts.

An existing non WIL array variable cannot be converted to an array by using array subscript syntax with the existing non array variable's name. Doing so will result in an "Expression continues past expected end" error.

Row Major Format

Multidimensional arrays in WinBatch use the 'Row Major' format. When you specify a subscript for a multidimensional array, you need to first specify the row index then the column index.

For Example:

arrMyArray[ row_index , column_index ]

In computing, row-major order describes the method used for storing multidimensional arrays in linear memory. In WinBatch, rows are identified by the first index of a two-dimensional array and columns by the second index. Array layout is critical for correctly passing arrays between programs written in different languages.

List of Array Functions: