Arrays

Arrays are created using the new ArrDimension function or by dynamic array assignment.. 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.

Embedded Arrays and Embedded Maps

Arrays and maps can have other arrays and maps as elements. Arrays that are present as elements in other arrays are called either embedded or nested arrays in this help file. Embedded arrays can be used to represent more complex relationships in data but should be used with discretion as they can have a negative impact on overall script performance when over used.

The contents of embedded array elements are accessed using multiple sets of square brackets following the array variable name.

For Example:

a[0] = 42

b[0] = a

x = b[0][0]

Up to 8 bracket sets are supported behind an array variable name. This helps limit array nesting to 8 arrays deep but nesting beyond one level is not recommended because of potential detrimental effects on script performance.

The WIL interpreter imposes several other restrictions on arrays having other arrays as elements. A partial list of those restrictions follows:

Only ArraySearch function options 1 or 2 can be used to search arrays with embedded arrays. The embedded arrays are not search.
The ArraySort function cannot be use to sort arrays containing other arrays.
The ArrayInsert function can insert an array into a single element of an array but arrays can not be used to initialize an entire row or column.
The ArrayFilePut and ArrayFilePutCSV can not be used to write arrays containing embedded arrays to a file.
The ArrayItemize, ArrayToStr, and ArrayLocate functions ignore embedded arrays and their elements.