Arrays 101: All you need to know about them!

[TheDcoder]

Hello Guys! I wanted to share all my knowledge on arrays! Hope may enjoy the article , Lets start!

Declaring arrays!

Declaring arrays is a little different than other variables: 

; Rules to follow while declaring arrays:
;
; Rule #1: You must have a declarative keyword like Dim/Global/Local before the declaration unless the array is assigned a value from a functions return (Ex: StringSplit)
; Rule #2: You must declare the number of dimensions but not necessarily the size of the dimension if you are gonna assign the values at the time of declaration.
#include <Array.au3>

Local $aEmptyArray[0] ; Creates an Array with 0 elements (aka an Empty Array).

Local $aArrayWithData[1] = ["Data"]

_ArrayDisplay($aEmptyArray)
_ArrayDisplay($aArrayWithData)

That's it

Resizing Arrays

Its easy! Just like declaring an empty array! ReDim is our friend here:

#include <Array.au3>

Local $aArrayWithData[1] = ["Data1"]

ReDim $aArrayWithData[2] ; Change the number of elements in the array, I have added an extra element!

$aArrayWithData[1] = "Data2"

_ArrayDisplay($aArrayWithData)

Just make sure that you don't use ReDim too often (especially don't use it in loops!), it can slow down you program.

Best practice of using "Enum"

You might be wondering what they might be... Do you know the Const keyword which you use after Global/Local keyword? Global/Local are declarative keywords which are used to declare variables, of course, you would know that already by now , If you check the documentation for Global/Local there is a optional parameter called Const which willl allow you to "create a constant rather than a variable"... Enum is similar to Const, it declares Integers (ONLY Integers):

Global Enum $ZERO, $ONE, $TWO, $THREE, $FOUR, $FIVE, $SIX, $SEVEN, $EIGHT, $NINE ; And so on...

; $ZERO will evaluate to 0
; $ONE will evaluate to 1
; You get the idea :P

; Enum is very useful to declare Constants each containing a number (starting from 0)

This script will demonstrate the usefulness and neatness of Enums :

; We will create an array which will contain details of the OS

Global Enum $ARCH, $TYPE, $LANG, $VERSION, $BUILD, $SERVICE_PACK

Global $aOS[6] = [@OSArch, @OSType, @OSLang, @OSVersion, @OSBuild, @OSServicePack]

; Now, if you want to access anything related to the OS, you would do this:

ConsoleWrite(@CRLF)
ConsoleWrite('+>' & "Architecture: " & $aOS[$ARCH] & @CRLF)
ConsoleWrite('+>' & "Type: " & $aOS[$TYPE] & @CRLF)
ConsoleWrite('+>' & "Langauge: " & $aOS[$LANG] & @CRLF)
ConsoleWrite('+>' & "Version: " & $aOS[$VERSION] & @CRLF)
ConsoleWrite('+>' & "Build: " & $aOS[$BUILD] & @CRLF)
ConsoleWrite('+>' & "Service Pack: " & $aOS[$SERVICE_PACK] & @CRLF)
ConsoleWrite(@CRLF)

; Isn't it cool? XD

You can use this in your UDF(s) or Program(s), it will look very neat!

Looping through an Array

Looping through an array is very easy! . There are 2 ways to loop an array in AutoIt!

Simple Way:

; This is a very basic way to loop through an array

; In this way we use a For...In...Next Loop!

Global $aArray[2] = ["Foo", "Bar"] ; Create an array

; This loop will loop 2 times because our $aArray contains 2 elements.
For $vElement In $aArray ; $vElement will contain the value of the elements in the $aArray... one element at a time.
    ConsoleWrite($vElement & @CRLF) ; Prints the element out to the console
Next

; And that's it!

Advanced Way:

; This is an advanced way to loop through an array

; In this way we use a For...To...Next Loop!

Global $aArray[4] = ["Foo", "Bar", "Baz", "Quack"] ; Create an array

; This loop will loop 2 times because our $aArray contains 2 elements.
For $i = 0 To UBound($aArray) - 1 ; $i is automatically created and is set to zero, UBound($aArray) returns the no. of elements in the $aArray.
    ConsoleWrite($aArray[$i] & @CRLF) ; Prints the element out to the console.
Next ; This is the advanced way, we use $i to access the elements!

; With the advanced method you can also use the Step keyword to increase the offset in each "step" of the loop:

; This will only print every 2nd element starting from 0
ConsoleWrite(@CRLF & "Every 2nd element: " & @CRLF)
For $i = 0 To UBound($aArray) - 1 Step 2
   ConsoleWrite($aArray[$i] & @CRLF)
Next

; This will print the elements in reverse order!
ConsoleWrite(@CRLF & "In reverse: " & @CRLF)
For $i = UBound($aArray) - 1 To 0 Step -1
   ConsoleWrite($aArray[$i] & @CRLF)
Next

; And that ends this section!

For some reason, many people use the advance way more than the simple way . For more examples of loops see this post by @FrancescoDiMuro!

Interpreting Multi-Dimensional Arrays

Yeah, its the most brain squeezing problem for newbies, Imagining an 3D Array... I will explain it in a very simple way for ya, so stop straining you brain now! . This way will work for any array regardless of its dimensions...

Ok, Lets start... You can imagine an array as a (data) mine of information:

; Note that: 
; Dimension = Level (except the ground level :P)
; Element in a Dimension = Path

; Level 2 ----------\
; Level 1 -------\  |
; Level 0 ----\  |  |
;             v  v  v
Local $aArray[2][2][2]
;     \-----/
;        |
;        v
; Ground Level


; As you can see that $aArray is the Ground Level
; All the elements start after the ground level, i.e from level 0
; Level 0 Contains 2 different paths
; Level 1 Contains 4 different paths
; Level 2 Contains 8 different paths

; When you want too fill some data in the data mine,
; You can do that like this:

$aArray[0][0][0] = 1
$aArray[0][0][1] = 2
$aArray[0][1][0] = 3
$aArray[0][1][1] = 4
$aArray[1][0][0] = 5
$aArray[1][0][1] = 6
$aArray[1][1][0] = 7
$aArray[1][1][1] = 8

; Don't get confused with the 0s & 1s, Its just tracing the path!

; Try to trace the path of a number with the help of the image! Its super easy! :D

I hope you might have understand how an array looks, Mapping your way through is the key in Multi-Dimensional arrays, You take the help of notepad if you want! Don't be shy!

Frequently Asked Questions (FAQs) & Their answers

Q #1. What are Arrays?
A. An Array is an datatype of an variable (AutoIt has many datatypes of variables like "strings", "integers" etc. Array is one of them). An Array can store information in a orderly manner. An Array consist of elements, each element can be considered as a variable (and yes, each element has its own datatype!). AutoIt can handle 16,777,216 elements in an Array, If you have an Array with 16,777,217 elements then AutoIt crashes.

Q #2. Help! I get an error while declaring an Array!?
A. You tried to declare an array like this:

$aArray[1] = ["Data"]

That is not the right way, Array is a special datatype, since its elements can be considered as individual variables you must have an declarative keyword like Dim/Global/Local before the declaration, So this would work:

Local $aArray[1] = ["Data"]

Q #3. How can I calculate the no. of elements in an array?
A. The UBound function is your answer, Its what exactly does! If you have an multi-dimensional Array you can calculate the total no. of elements in that dimension by specifying the dimension in the second parameter of UBound

Q #4. Why is my For...Next loop throwing an error while processing an Array?
A.  You might have done something like this:

#include <MsgBoxConstants.au3>

Local $aArray[10] = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
Local $iMyNumber = 0

For $i = 0 To UBound($aArray) ; Concentrate here!
    $iMyNumber += $aArray[$i]
Next

MsgBox($MB_OK, "Sum of all Numbers!", $iMyNumber)

Did you notice the mistake? UBound returns the no. of elements in an array with the index starting from 1! That's right, you need to remove 1 from the total no. of elements in order to process the array because the index of an array starts with 0! So append a simple - 1 to the statment:

#include <MsgBoxConstants.au3>

Local $aArray[10] = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
Local $iMyNumber = 0

For $i = 0 To UBound($aArray) - 1
    $iMyNumber += $aArray[$i]
Next

MsgBox($MB_OK, "Sum of all Numbers!", $iMyNumber)

Q #5. Can an Array contain an Array? How do I access an Array within an Array?
A. Yes! It is possible that an Array can contain another Array! Here is an example of an Array within an Array:

; An Array can contain another Array in one of its elements

; Let me show you an example of what I mean ;)

#include <Array.au3>

Global $aArray[2]
$aArray[0] = "Foo"

Global $aChildArray[1] = ["Bar"]

$aArray[1] = $aChildArray

_ArrayDisplay($aArray) ; Did you see that!? The 2nd element is an {Array} :O
; But how do we access it???

; You almost guessed it, like this: 
; Just envolope the element which contains the {Array} (as shown in _ArrayDisplay) with brackets (or parentheses)! :D
ConsoleWrite(($aArray[1])[0]) ; NOTE the brackets () around $aArray[1]!!! They are required or you would get an syntax error!

; So this: $aArray[1][0] wont work!

 

More FAQs coming soon!

Edited December 15, 2018 by TheDcoder
Add example of using Step in loops and link to Franceso's post

[JohnOne]

Rule #1: You must have an declarative keyword like Dim/Global/Local before the declaration.

Not if you are returning it from a fuction.

$aArray = StringSplit("123", "");

 

[guinness]

0 => $MB_OK

[iamtheky]

wouldnt an empty array be

Local $aEmptyArray[0]

as your current example is a 1D array with a single element, and that single element is an empty string.

 

#include<array.au3>

Local $aEmptyArray[1]
_ArrayDisplay($aEmptyArray) ;array with 1 entry
msgbox(0, '' , $aEmptyArray[0]) ;empty string

Local $aEmptyArray[0]
_ArrayDisplay($aEmptyArray) ;array with 0 entries
msgbox(0, '' , $aEmptyArray[0]) ;nothing because the array is empty

 

Edited October 17, 2015 by boththose

[TheDcoder]

Thanks all for reminders, I will correct them now

[kcvinu]

@TheDcoder , This could be useful when you have .NET in your PC. 

Local $aAlist = ObjCreate("System.Collections.ArrayList")

$aAlist.Add ("Test")
$aAlist.Add("Sample")

 

[TheDcoder]

@kcvinu Oh , It seems that you created an object which acts as an array... As I am like fresh out of the school in objects, I can't use your example efficiently enough , Also it would confuse any newbies reading ... Anyways lets stick to the native AutoIt way

 

P.S _ArrayAdd would be the same as the "Add" method

[kcvinu]

Basically i don't like to use ReDim. So this is my first choice.  _ArrayAdd uses ReDim. But this is not.

[TheDcoder]

I understand, did you compare the speed of "Add" method and _ArrayAdd? I would like to see the result

[kcvinu]

@TheDcoder here is the result. For a small array with 10 element, _ArrayAdd is the faster method.  This is the result

ArrayAdd Time = 0.46618648011839 ms
ArrayList Time = 2.82040846777807 ms

But for a large array with 2225 elements, ArrayList is faster.This is the result

ArrayAdd Time = 1449.32797699147 ms
ArrayList Time = 48.0397075617342 ms

Edited October 18, 2015 by kcvinu

[TheDcoder]

Nice! , Why won't you try to make an alternative to ReDim using the "Add" method? Perhaps a snippet would do the magic!

[guinness]

Basically i don't like to use ReDim. So this is my first choice.  _ArrayAdd uses ReDim. But this is not.

ArrayList is a horrible choice, because it's not a generic collection and therefore you have a lot of boxing and unboxing to do during execution. Anyhow, you are aware that under the hood, List and ArrayList are basically arrays that hold the length and current index position? They essentially use Array.Copy() when a new item is added which is outside the current length of the array. If people didn't realise, that's all ReDim is, a syntactic sugary array copying method!

[kcvinu]

@guinness , i didn't know that the under the hood secrets. But why did the speed varies when working with the large arrays ?

[TheDcoder]

@kcvinu AutoIt is slower than NET, I think NET has a constant work load with arrays, where as AutoIt has a constant work load with elements of an array...

So more elements = more slower in AutoIt

Edited October 18, 2015 by TheDcoder

[guinness]

Well the code is open source, see >> https://github.com/dotnet/corefx/blob/c02d33b18398199f6acc17d375dab154e9a1df66/src/System.Collections.NonGeneric/src/System/Collections/ArrayList.cs OR http://referencesource.microsoft.com/#mscorlib/system/collections/arraylist.cs,9df2bbf8d237742e 

[kcvinu]

ha ha..those links are filled with C# code. I hate {} s

Edit : But i have downloaded it for leater reading and conversion

 

Edited October 18, 2015 by kcvinu

[TheDcoder]

I updated the first post!

[guinness]

ha ha..those links are filled with C# code. I hate {} s

 

Well then you pretty much hate every popular language out there.

@TheDcoder, maybe you could answer this question...why does the index value start from zero and not one?

Edited October 18, 2015 by guinness

[kcvinu]

Well then you pretty much hate every popular language out there.

Yes. And now i am fighting with myself to learn javascript. When i look into a piece of code, my mind is tempting to close the page and go to any other off side rule languages.

[JohnOne]

Rule #1: You must have an declarative keyword like Dim/Global/Local before the declaration (Note that a function can still return an array to an undeclared variable, therefore creating an array without a declarative keyword)

The Variable is declared as soon as you type it in.

Here is a suggestion

"You must have a declarative keyword like Dim/Global/Local before the declaration unless the array is assigned a value from a functions return."