Arrays

From Xojo Documentation

Revision as of 20:46, 1 December 2020 by PLefebvre (talk | contribs) (Fixed method signatures in tooltips)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)


Concept

Arrays are an indexed collection of data for a specific data type. Arrays themselves are not a data type, but any data type can be defined as an array using the Var statement or as a property.

Methods
Add IndexOf ResizeTo
AddAt LastIndex Shuffle
Array Pop Sort
Count RemoveAll SortWith
FirstIndex RemoveAt

Usage

Var arrayName() As dataType

Var arrayName(size [,size2,...sizeN]) As dataType

Var arrayName(), arrayNameN() As dataType [= Array(value1, value2, ..., valueN)]

Part Type Description
arrayName Variable name The name of the array.
size Integer (Optional) The size of the array. Size must be integer literals or integer constants.

If you do not specify a size, then array starts as empty. You can add elements using the Add method.

sizeN Integer (Optional) The size of the next dimension of the array if you are creating a multi-dimensional array.

You pass as many size parameters as dimensions in the array. The size parameters must be integer literals or integer constants.

dataType Data type or class The data type or class of the array.
value1...valueN values Values that match the dataType to add to the array.

Notes

Arrays can have a maximum index value of 2,147,483,646 for both 32-bit and 64-bit apps. In addition, although the methods Count, FirstIndex, IndexOf and LastIndex all indicates they return an Integer, they technically return an Int32 (even with 64-bit app). If you are creating Extension methods on Integer you should keep this in mind as you may also want to create Int32 extension methods as well.

Arrays are treated as objects so be aware that assigning an array to another variable or passing an array as a parameter does not make a copy of the array. Instead you get a new variable that points to the original array so any changes you make to the "2nd" array also affects the first array. If you need an actual copy of the array you will have to manually copy its values using a loop.

Arrays are often created by specifying the size of the array when you create it. Because arrays all start at position 0, an array has one more element than the number you use as the size. For example, this creates an array with 5 elements, which you can then access using the index:

Var aNames(4) As String
aNames(0) = "Bob"
aNames(1) = "Bill"
aNames(2) = "Ben"
aNames(3) = "Brad"
aNames(4) = "Bart"

One way to avoid having to remember that arrays start at zero is to use the FirstIndex and LastIndex methods.

Constants can be used when declaring the size of an array:

Const kBound As Integer = 4
Var aNames(kBound)

You can also create empty arrays that do not specify a size. An empty array has a size of -1. At run-time, your code can add elements to it or you can choose to make it a specific size by using Arrays.ResizeTo. These are the two ways to create an empty array:

Var aFirstNames() As String
Var aLastNames(-1) As String

If you try to access an element of an array that does not exist, you will get an OutOfBoundsException. Here are some examples that would raise the exception:

aNames(5) = "Tom" // this exceeds the upper bound of aNames
aFirstName(1) = "Bill" // aFirstName is still empty

Use the methods Add and AddAt to add additional elements to arrays. These methods are the only ways to add elements to empty arrays, but they can also be used to extend the size of any single-dimension array.

Iterating Through an Array

If you need to access each element of an array but don't need to know the index of that element, you can use an iterator:

Var people() As String = Array("John", "Sally", "Fred", "Nancy")
For Each name As String In People
MessageBox(name)
Next

You can also cycle through an array by index:

Var people() As String = Array("John", "Sally", "Fred", "Nancy")
For index As Integer = 0 To people.LastIndex
Var name As String = people(index)
MessageBox(name)
Next

Note: There is no real advantage to caching the array's last index in a variable to use in a loop. Over millions of iterations, it will only save a few milliseconds.

Multi-Dimensional Arrays

A multi-dimensional array has elements in 2 or more dimensions. A table would be an example of a 2-dimensional array because it has columns and rows.

Most of the array methods are not supported for multi-dimensional arrays.

You declare multi-dimensional arrays by specifying the size for each dimension:

// A 5x5 table
Var table(4, 4) As Integer
table(1, 3) = 42

Remove All Elements

The fast way to remove all elements from an array is to use Arrays.RemoveAll:

Var myArray() As Integer
For i As Integer = 1 To 1000
myArray.Add(i)
Next
myArray.RemoveAll
// myArray is now empty

Objects in Arrays

Arrays of objects work like other arrays except you'll have to deal with possible Nil values just as you would with objects that are not in an array.

If the array index is valid and its value is Nil and you try to use the value, then you get a NilObjectException, just as you would if you try to use any non-array value that is Nil.

If an array index is not valid then that’s an OutOfBoundsException and is not related to anything being Nil.

See Also

Var, For Each...Next, ParamArray, Arrays.ResizeTo commands; Dictionary class; UserGuide:Collections_of_Data topic