Arrays

2013-03-03T01:15:26Z

DoubleMcLovin: /* Comparing Arrays */

[[Category:Tutorials]]
== Initial notes ==

This is a small tutorial on how to use arrays in AutoIt.

We will try to target those people learning a programming language for the first time. So, be prepared for some spoon feeding.

The code assumes you use the SciTE editor. There is a minimal version of SciTE included in the latest stable release of AutoIt (version 3.2.0.1 and above). To understand how arrays and associated functions work, it is imperative that you try and play with the samples that we provide here. Make sure you understand how each step works before you go on to the next one.

We also recommend reading the [[UnitTesting]] wiki page and follow the guide lines you find there. (ok the page is not finished, but it will hopefully be when it is needed). It will make your life a lot easier later on when you have forgot how something is suppose to work. Try to adopt the samples you find in this article to a unit testing framework.

== What is an array ==
An array is an identifier containing elements or variables (if you like), referenced by the identifier and an index. Now we could have said a variable containing variables referenced by the variable and an index but I think that makes even less sense to most of us.

This sounds complex. So, why should you learn about arrays? The short answer is that data structures are fundamental to programming.

== Declaring Arrays in AutoIt ==
You declare an array in the same manner as you would declare any variable in AutoIt. But when you know it is an array, you add information on how many elements you want to have in the array. This information is provided by adding brackets after the identifier and a number indicating how many elements you want the array to hold.
<source lang=autoit>
Global $arr[4] ; Will make space for 4 elements.
Local $arr[1] ; Will make space for 1 element.
;NOTE! Avoid using Dim. Use Global or Local instead.
Dim $arr[3] ; Will make space for 3 elements.
</source>
Making space for 1 element may seem ridiculous, but further down the road we shall see how we can have arrays grow and shrink. So when we declare an array with 1 element, it is usually just a place holder.

In AutoIt, you can also declare an array as a normal variable and later get an array assigned to it from a function. Note about the "from a function" part: this can refer to a user-defined function or an AutoIt internal built-in function. The point is, a variable does not need to hold an array before the array is assigned to it.
<source lang=autoit>
Local $arr = StringSplit("This is my string. I want to split it in sentences.", ".")
</source>
Now to make really certain we have an array from StringSplit, we should check it with the IsArray($variable) built-in function.
<source lang=autoit>
If IsArray($arr) Then
; DO work on the array
EndIf
</source>

== Assigning Data to Array Elements ==
When we declare the array we make some room in memory for future data. We want to assign some data to the items in the array. Now here is the catch. The array always starts at index 0. So, the first element in the array will be accessed by 0, the second element in the array is accessed at by 1 and so on.
<source lang=autoit>
Local $arr[3] ; Make room for three elements
;Assign some data
$arr[0]="Element 1"
$arr[1]="Element 2"
$arr[2]="Element 3"
</source>

You can also assign all the data in one smack like this:
<source lang=autoit>
Local $arr[3] = ["element 1", "element 2", "element 3"]
</source>

This 0-based indexing is quite common in most computer languages, but it can be a source of headaches to programmers until it becomes second nature to them. For example, every time you want to loop through a range of elements and the range includes the last element, you have to subtract one from the number of items your array is holding, to get the index of the last item. I.E., An array with 3 elements has a last index of 2.

So if you don't take 0-based indexing into consideration in your code, you may ask for something outside the memory area set aside for the array. When you do, you get an error message (Array variable has incorrect number of subscripts or subscript dimension range exceeded) and your script will cease execution.

== Accessing Data in Arrays ==
Let's walk all elements in the previous sample:
<source lang=autoit>
Local $arr[3] = ["element 1", "element 2", "element 3"]
For $i = 0 to 3 - 1 ; We have an array with three elements but the last index is two.
ConsoleWrite($arr[$i] & @LF)
Next
</source>
=== Determine array size with UBound ===
The "3 - 1" construct used in the last sample looked strange. It is not a good idea to hard-code size like that. So lets improve our sample a little.
<source lang=autoit>
Local $iMax = 3
Local $arr[$iMax] = ["Element 1", "Element 2", "Element 3"]
For $i = 0 to $iMax - 1
ConsoleWrite($arr[$i] & @LF)
Next
</source>
Now that's a bit cleaner. It's also a lot easier to increase or decrease the size of the array. 
But say you don't know the size of the array upfront because it may come in a variable size when created dynamically. 
<source lang=autoit>
Local $iMax
Local $data="Element 1|Element 2|Element 3"
; The string in data will be split into an array everywhere | is encountered
Local $arr = StringSplit($data, "|")
If IsArray($arr) Then
$iMax = UBound($arr); get array size
ConsoleWrite("Items in the array: " & $iMax & @LF)
For $i = 0 to $iMax - 1; subtract 1 form size to prevent out of bounds error
ConsoleWrite($arr[$i] & @LF)
Next
EndIf
</source>
When you run the above code you will see that $iMax is 4 and not 3 as you might have expected. The reason for this is that the developer of the StringSplit() function thought it was a good idea to use the first item (item 0) to keep a count of valid items in the array. This makes sense in many situations as you now have an array containing data with an index starting at 1. So our sample code can now be rewritten like this.
<source lang=autoit>
Local $iMax
Local $data="Element 1|Element 2|Element 3"
; The string in data will be split into an array everywhere | is encountered
Local $arr = StringSplit($data, "|")
If IsArray($arr) Then
For $i = 1 to $arr[0]
ConsoleWrite($arr[$i] & @LF)
Next
EndIf
</source>
There is another good reason for keeping the count in $arr[0]. When you start to use arrays extensively, you will encounter situations where you have to create an array without knowing how many of the elements you will use. Resizing the array is a relatively expensive operation (in CPU cycles) in most languages.

Now consider our example if our initial array has reserved space for 10 items but we end up only using 3. In this case iterating the array using UBound will force us to check for empty elements. While iterating with $arr[0] needs no other change than maintaining the correct count in $arr[0].
<source lang=autoit>
Local $iMax=10
;NOTE: We have added the count in the first element
Local $arr[$iMax] = [3, "Element 1", "Element 2", "Element 3"]
;NOTE: We use the count in $arr[0] to indicate the last item and we start from index=1
For $i = 1 to $arr[0]
ConsoleWrite($arr[$i] & @LF)
Next
</source>

== Changing array sizes with ReDim ==
As arrays are critical to algorithm implementations, and in AutoIt even more so as there is no other means of grouping data, we have to understand how to let it grow and shrink. This is where the keyword ReDim comes into the picture.

Let's make an example. We want our array to hold data lines but we don't know how many items we need. We make a guess, in this case 5. Now, we use that array to hold data we get from a loop with a random number of iterations. If the array is too small it should automatically be increased. Before we dump the array to output, we should adjust it to the exact size it is supposed to be.
<syntaxhighlight lang="autoit">
Local $iMax=5
;NOTE: We have added the count in the first element
Local $arr[$iMax] = [0] ;Initiate the array and place a counter in the first element.
;Generate a random number between 0 and 20
Local $iRandom = Random(0, 20, 1)
For $i = 1 to $iRandom
; Check that the array is big enough
If UBound($arr) = $i Then
; Resize the array when $i is equal to the element count in the array to prevent subscript error
ReDim $arr[$arr[0] + $iMax]
EndIf
$arr[$i] = "Item " & $i; safely add data to new index element
$arr[0] = $i; update the index count for future reference
Next
;Adjust the array size. This time it is probably downward to the size of
;$arr[0] + 1 (remember the first item is $arr[0])
ReDim $arr[$arr[0]+1]
;Now dump the results
For $i = 1 to $arr[0]
ConsoleWrite("$arr[" & $i & "]:=" & $arr[$i] & @LF)
Next
; Visually check that the values are sound
ConsoleWrite( "Ubound($arr):=" & UBound($arr) & ", $arr[0]:=" & $arr[0] & ", $iRandom:=" & $iRandom & @LF)
</syntaxhighlight>
Note how the array now has first been adjusted to a multiple of $iMax and in the last part adjusted down to a size matching the data items.

== Multi dimensional arrays ==
Now what is a good explanation of an multi-dimensional array?
It could be a table where you access one item in the table at a time.
<syntaxhighlight lang="autoit">
Local $arr[3][3] = [[1, 2, 3], [2, 3, 4], [3, 4, 5]]
For $i = 0 to UBound( $arr, 1) - 1
For $j = 0 to UBound($arr, 2) - 1
ConsoleWrite("$arr[" & $i & "][" & $j & "]:=" & $arr[$i][$j] & @LF)
Next
ConsoleWrite(@LF)
Next
</syntaxhighlight>
You can add a number of dimensions not to exceed 64 as stated in the help file section "AutoIt>Appendix>AutoIt3 limits/Defaults".
Drop me a note if you encounter any circumstances where it might be simpler to add dimensions rather than using other techniques.

Here is a 4 dimensional sample. You tell me how that initializer is for readability.
<syntaxhighlight lang="autoit"> ; NOTE: The following is supposed to be all on one line
; but we use the "_" character to split it into multiple lines for readability
Local $arr[3][3][3][3] = [ _
[[[1, 2, 3],[2, 3, 4],[3, 4, 5]], [[1, 2, 3],[2, 3, 4],[3, 4, 5]], [[1, 2, 3],[2, 3, 4],[3, 4, 5]]], _
[[[1, 2, 3],[2, 3, 4],[3, 4, 5]], [[1, 2, 3],[2, 3, 4],[3, 4, 5]], [[1, 2, 3],[2, 3, 4],[3, 4, 5]]], _
[[[1, 2, 3],[2, 3, 4],[3, 4, 5]], [[1, 2, 3],[2, 3, 4],[3, 4, 5]], [[1, 2, 3],[2, 3, 4],[3, 4, 5]]] _
]

For $i = 0 To UBound($arr, 1) - 1
For $j = 0 To UBound($arr, 2) - 1
For $k = 0 To UBound($arr, 3) - 1
For $l = 0 To UBound($arr, 4) - 1
ConsoleWrite("$arr[" & $i & "][" & $j & "][" & $k & "][" & $l & "]:=" & $arr[$i][$j][$k][$l] & @LF)
Next
Next
Next
ConsoleWrite(@LF)
Next</syntaxhighlight>

== Arrays in arrays ==
You may save an array in an array element (item). The thing is, there is no way to directly access that array stored in the element. You have to go through a variable to get access to the embedded array which may make your code overly complicated and difficult to debug.

Remember that there may be issues if you pass an array containing arrays into a function and the embedded array is changed inside that function. So, to conclude this, try not to embed arrays within arrays unless you absolutely need to and are prepared to do rigorous testing to make sure your code will always work as expected.

That said, here is an example.
<syntaxhighlight lang="autoit">Local $arr[3]
Local $a1[3] = [2, "a1-1","a1-2"]
Local $a2[3] = [2, "a2-1","a2-2"]
$arr[1] = $a1
$arr[2] = $a2
$arr[0] = 2
Local $dumy

For $i = 1 to $arr[0]
$dumy = $arr[$i]
If IsArray($dumy) Then
For $j = 1 to $dumy[0]
ConsoleWrite("$i:=" & $i & ", $dumy[" & $j & "]:=" & $dumy[$j] & @LF)
Next
Else
ConsoleWrite("!>Oops!, What happened? Expected an array!" & @LF)
EndIf
Next</syntaxhighlight>

== Passing arrays to a function ==
There is no hocus pocus about this. Only a few rules.

* You can not declare the variable to hold the array in the function declaration as an array. So, users could pass on a variable. So you have to check that the variable holds an array before you do array specific operations on it.
* You don't have to, but you should, specify the variable to hold the array as ByRef.

Now, during the tutorial you have probably noticed that there is a lot of code that is equal in each sample. I'm especially thinking about the code we have used to output the array content. Let's make life easier and create a debug function
<syntaxhighlight lang="autoit">
Func dbgArray(ByRef $arr, $msg="")
If $msg <> "" Then
ConsoleWrite("*** " & $msg & " ***" & @LF)
EndIf
Local $i
For $i = 0 to UBound($arr) - 1
ConsoleWrite("$arr[" & $i & "]:=" & $arr[$i] & @LF)
Next
ConsoleWrite( "Ubound($arr)=:=" & UBound($arr) & ", $arr[0]:=" & $arr[0] & @LF)
EndFunc
</syntaxhighlight>

And let's make a little function to fill our arrays with something. Note how the ArrayFiller makes sure it works on an array.
<syntaxhighlight lang="autoit">
Func ArrayFiller(ByRef $arr)
If IsArray($arr) Then
ReDim $arr[3] ;Notice we might discard content in this operation
Else
Local $foo[3]
$arr = $foo
EndIf
;Fill the array
$arr[0] = 2
$arr[1] = "Fill 1"
$arr[2] = "Fill 2"
EndFunc
</syntaxhighlight>
And finally some code using the new functions
<syntaxhighlight lang="autoit">
Local $arr1[1]
ArrayFiller($arr1)
dbgArray($arr1)
</syntaxhighlight>

This code is a test on what happens when we pass a regular variable.
<syntaxhighlight lang="autoit">
Local $arr2
ArrayFiller($arr2)
dbgArray($arr2)
</syntaxhighlight>

== Passing arrays from a function ==
As you could observe, in the previous samples, an array will be passed back and forth with the ByRef keyword infront of the variable holding the array in the function declaration.

We could also have used the Return keyword in a function.
Lets re-work the ArrayFiller function to do this rather than using a variable ByRef.
<syntaxhighlight lang="autoit">
Func ArrayFiller2()
Local $arr = [3, "Fill 1", "Fill 2"]
Return $arr
EndFunc
</syntaxhighlight>

And now we can use the function like this
<syntaxhighlight lang="autoit">
Local $foo = ArrayFiller2()
dbgArray($foo)
</syntaxhighlight>

== Forum FAQ about arrays ==
Feel free to add questions and answers you have encountered in the forum.

===Accessing Arrays===
Obviously one can assign arrays to variables:
<syntaxhighlight lang="autoit">
$NewArray = $OldArray
</syntaxhighlight>
One can also assign single array elements:
<syntaxhighlight lang="autoit">
$Array[1] = "Element 1"
</syntaxhighlight>
Or
<syntaxhighlight lang="autoit">
$Content = $Array[1]
</syntaxhighlight>

===Comparing Arrays===
'''You can not, however, compare complete arrays:''' 
<syntaxhighlight lang="autoit">
Local $Array1[3] = [1, 2, 3]
Local $Array2[3] = [1, 2, 3]
Local $Array3[4] = [1, 2, 3, 4]

If $Array1 == $Array2 Then ConsoleWrite("1.) $Array1 is equal to $Array2! which might be correct in some sense." & @LF); while they contain the same data, the comparison does not work.
If $Array1 == $Array3 Then ConsoleWrite("2.) $Array1 is equal to $Array3! which is incorrect." & @LF); even though they're different in size, it's incorrectly determined that they're equal.
</syntaxhighlight>

I have the impression that such comparisons compare the memory address of the arrays instead of the array elements values. And the addresses are always different for different arrays.
 
You have to instead, compare all elements one after the other. It might be a good idea to first compare array sizes if that can vary for both the compared arrays!

===Array UDF: array.au3===
AutoIt features a large list of User-Defined Functions (UDF), among is a module supplying extra array functions. You can find a reference on those functions in AutoIt's Help file as the last main chapter named 'User Defined Functions Reference'.

== Links ==

AutoIt Wiki - User contributions [en]

Arrays