Arrays in Xojo

In Xojo you can store data in arrays. An array is a data structure with one or more dimensions, where you can store various data types. Arrays itself are objects, that hold the data as well as metadata like dimensions and allocation size.

Create an array

When you declare an array variable, Xojo will reserve the memory for the variable (or property) and create the underlaying array object.

Var test1() As Integer

Internally this calls the CreateArray function in the framework and passes the size of 0 and one dimension. But if you assign nil, then the CreateArray call doesn't happen.

Var test2() As Integer = Nil

This will only allocate the variable, but not create a new array.

Var test1() As Integer Var test3() As Integer = test1

With the assignment to a second variable, we now have two variables pointing both to the same array (object). Like if you have two keys to one locker. When you pass the array to a method, it gets another reference, so the array is not copied. If the method then modifies the array, you see the changes through your references in the variables.

Dimensions

You can have arrays with a lot of dimensions:

Var test1(3) As Integer Var test2(3,4) As Integer Var test3(3,4,5) As Integer

Just pass as much as upper limits as you need. The first array test1 has 4 entries with index 0 to 3. The second array test2 has 20 entries and uses two dimensions.

You can always change the size of an array, but not the number of dimensions:

Var test3(3,4,5) As Integer test3.ResizeTo 4,5,6

You can query the size of an array by calling Count() and passing the index. To know how many dimensions you have, you can use LastRowIndex with -1 as index. Or better you could do that ten years ago, before it broke. Once you know the dimension count, you can loop and ask each dimension for the number of entries:

Var test3(3,4,5) As Integer Var DimensionCount As Integer = 3 Var size As Integer = 1 For i As Integer = 1 To DimensionCount Var d As Integer = test3.Count(i) size = size * d Next // 4*5*6 => 120

If you multiply the count with the size of the data type, you may get the full byte size. Integer on 64-bit systems is 8 bytes, so the array is 120 * 8 bytes = 960 bytes. To help with dimension count, we add GetArrayDimensionMBS function to MBS Plugin for the next version.

Add, Insert or Remove

For your convenience Xojo has methods to add, insert or remove values in one dimensional arrays. You can pass a value to add it to the end of the array. Xojo automatically resizes the array and stores the new value. When you insert the value at an index, Xojo moves entries to make room and inserts the new value. And remove just removes the entry with an array.

Internally all arrays have an allocation size. Appending one value to a full array will trigger a new bigger allocation. Old values are moved to the new memory and your new value is appended. When you start with an empty array, Xojo may start with zero elements. When you append the first time, you get room for 16 elements. When you append the 17th one, the array is resized to double the number of elements to 32.

In a multi dimensional array, you can add a new row by resizing it to the new size:

Var pixels(10,6) As Integer Var oldWidth As Integer = pixels.LastIndex(1) Var oldHeight As Integer = pixels.LastIndex(2) Var newHeight As Integer = oldHeight + 1 pixels.ResizeTo oldWidth, newHeight

Array inside an array

Of course you can store array objects in other data structures like dictionaries or once again an array. Like here we store an integer array into a variable array and get it back:

Var a() As Integer a.Add 123 Var v() As Variant // store array inside array v.Add a // and pull back Var x() As Integer = v(0)

After this code, the an and x variable both point to the same object as well as v(0).

Array function

For your convenience Xojo has an array function. It creates an array and determinate the parameters you pass. Sometimes this can lead to surprises when a value or constant somewhere can change the array type. As you see adding a boolean to an integer array makes it a variant array:

Var ia() As Integer = Array(2, 3, 4) Var da() As Double = Array(2, 3, 4.5) Var ba() As Boolean = Array(True, True, False) Var va() As Variant = Array(2, False)

MBS functions

Now you may ask what MBS has to offer?

We solve a few unique problems. Like when you have an array of some objects, but you don’t know upfront what type of objects to cast the array to.

You may have a variant somewhere containing an array. To cast it properly to a variant() array, we have the GetVariantArrayMBS function. For an array of Dictionary objects, you could use GetVariantAsDictionaryArrayMBS( instead. If you need the upper bound, you can use the GetVariantArrayUboundMBS function. Use GetVariantArrayValueMBS to get a value. This allows you to query the content of an array without casting it to the array of the right data type.

Var test() As Dictionary test.add New Dictionary // now pass around and get it into a variant, e.g. with RowTag() in a ListBox Var v As Variant = test // now query count without casting to array // this doesn't compile! -> Var a() As Variant = v Var u As Integer = GetVariantArrayUboundMBS(v) Var d As Integer = GetArrayDimensionMBS(v) Var firstElement As Variant = GetVariantArrayValueMBS(v, 0) Break

We hope our array functions help you.

ByRef

You may know that Xojo has ByVal or ByRef to pass parameters to methods. Arrays are passed as ByVal by default just like all other parameters. That means the pointer to the array is passed. The array is not copied.

If you copy ByRef, you pass a pointer to the original variable. While ByVal allows you to change the content of the array. The changes are seen from the calling method as both refer to the same array. Now with ByRef, the called method can do the same, but also replace the entier array with a new one.

It's a common beginner mistake to use ByRef for arrays everywhere. You usually never need it. But let's make a sample to show you how we could use it:

Var test1() As String test1.Add "test" getKeys test1 MessageBox test1(0) // shows hello

Sub getKeys(byref keys() as string) Var NewKeys() As String NewKeys.Add "hello" // replace array. This puts NewKeys into the test1 passed here byRef as keys keys = NewKeys End Sub

Enjoy using arrays in Xojo!