Arrays

Caliper Script supports arrays of any number of elements, including arrays of values with mixed types. You can explicitly declare arrays with a dim (dimension) statement:

dim x[20]

The dimension must be an integer, but can be the result of an integer expression:

n = 25

dim z[n], zz[z.length]

You can pass zero as the dimension without causing an error; null is returned:

dim arr[0]

//arr = null

You can also declare arrays implicitly using braces:

x = {"Boston", "Troy", "Redlands"} // x[1] equals "Boston"

A string variable can be treated as an array, with each character being an element in the array:

s = "abcde"
x = s[3]	// x is now "c"
s[5] = "p"	// s is now "abcdp"
s[6] = "q"	// error: out of string bounds (1-5)

Arrays can have elements of different types:

dim x[3]

x[1] = 4

x[2] = 3.14159

x[3] = "Element Number 3"

y = {"Hello", 42, 3.14159}

Array elements can be arrays, allowing the creation of multi-dimensional arrays:

dim x[2]

x[1] = {"Boston", "Troy", "Redlands"}

x[2] = {10, 6.5, 3}

You can dimension a multi-dimensional array with a dim statement:

dim a[4,2]

This makes an array of 4 elements, each of which is an array of 2 elements. You can have up to 15 dimensions.

You can also declare multi-dimensional arrays implicitly using braces:

x = {{"Boston", "Troy", "Redlands"}, {10, 6.5, 3}}

An array of variables can be placed on the left-hand side of an assignment statement, where the right-hand side evaluates to an array. The values in the array elements on the right-hand side will be assigned to the variables in the corresponding positions in the array on the left-hand side. While it is best if both sides are the same array size, it is not required, and some left-hand elements can be null. Here are some examples:

{width, height} = GetWindowSize(window) // the function returns an array with two elements

{ , height} = GetWindowSize(window)     // only interested in the second element

{a, b} = {"x", "y", "z"}                // the third element on the right is ignored

{a, b, } = {"x", "y", "z"}              // a better way to do the previous assignment

{a, b} = {"x"} // assigns null to b

Use square brackets to reference elements of arrays.

Use this syntax...	To reference...
x[1]	The first element of array x
x[2][3]	The third element of the sub-array that is the second element of x.

You can also access elements of an array with the following functions:

GISDK Function	Summary
ArrayElementToInteger()	Converts an array element to an integer
ArrayElementToReal()	Converts an array element to a real number
ArrayElementToString()	Converts an array element to a string

A dim statement initializes all elements of an array to nulls:

dim x[3]

// is the same as

x = {null, null, null}

Special care should be taken when assigning array elements, since arrays can be shared. This means that when an array is assigned from one variable to another, both variables point to the same array in memory. This is done to avoid copying potentially large amounts of memory, but may have surprising side effects, as in this example:

a = {"r", "s"}

b = a

b[1] = "test"       // now both b and a refer to the array {"test", "s"}

This also holds for subarrays in multi-dimensional arrays:

a = {{"x", "y"}, {"r,", "s"}}
x = a[1]	// now x = {"x", "y"}
x[1] = "w"	// now x = {"w", "y"} and a[1] = {"w", "y"} as well!

To avoid the effect of having array variables pointing to the same array, use CopyArray().

A set of GISDK functions is available for working with arrays see Working with Arrays

For more information, see...

Working with Arrays

Options Arrays and Dot Notation

How Arrays Work

Array Methods