Intro to Arrays

Introduction to Arrays in LiveCode

We already know about LiveCode "containers" for storing data. A container can be a field, a variable, the message box, even a button. A LiveCode container can hold any type of data, including text, numerals, and booleans. Containers, especially variables, are fundamental, powerful and useful tools in any programming language.

As you know, putting data into containers is easy—just use the put command:

  put "Crazy go nuts!" into fld "wildWords"
  put true into itIsRaining

Once the container has the data in it you can access it simply by referring to the container.


  put true into itIsRaining
  if itIsRaining then
    put "umbrella" into hand
  end if

Variables are great as far as they go, but sometimes you may need to store not just one, but many pieces of separate but related information. For that job you can use a special type of variable called an array.

What's an array?

An array is a variable that holds multiple pieces of data, each linked to a name that is used to retrieve that specific piece of information. If you think of a variable as a physical container, like a box with a name, you can think of an array variable as a box with multiple compartments inside it, each with its own name. Each compartment is called an element, and each compartment has its own name, or key.

variable

array
Creating an array variable is similar to creating a regular variable. # this is a traditional variable put "groceries" into myBox
Instead of just naming the variable, as you've done up until now, you name the variable, then give the element's name, enclosed in brackets, like this: # these are array variables put "eggs" into myBox["breakableStuff"] put "milk" into myBox["coldStuff"] put "flour" into myBox["staple"] put 20 into myBox["dollars"] put false into myBox["needToothpaste"]

There is no restriction on the type of data that can go into an array variable. Each element or compartment can hold a string, numeral or boolean, for instance. The keys, or compartment names, can be strings, as in the example above, or numerals, as below:


  put "Hello." into greetings[1]
  put "Hi." into greetings[2]
  put "What up" into greetings[3]

Once your data is stored in an array, you can retrieve it by referring to the variable name and the key:

  put myBox["coldStuff"] into refrigerator
  put greetings[2] into fld "userGreeting"

You can also add to existing data in array elements using the before or after keywords:

  put "whole wheat " before myBox["staple"]
  put ", dawg!" after greetings[3]

Getting rid of data in an array

You may want to delete the contents of an element of an array, or even delete the element altogether. Delete the contents using a familiar command:

  put empty into myBox["coldStuff"]

If you want to delete both the contents and the element itself, use the delete variable command:


  delete variable greetings[1]
  delete variable myBox["staples"]

Finally, you can destroy an array altogether just by referring to it as a regular variable (so be careful how you refer to array variables!).

  put empty into greetings # makes 'greetings' into a regular variable with nothing in it  
  put "Hello world." into greetings # now 'greetings' is a regular variable with a string in it

Getting the Names of Array Elements

What if you create an array, but you forget the names, or keys, of the elements? Just use the keys function, which returns a list of all of the element names in an array. Returning to the example above:

  put "eggs" into myBox["breakableStuff"]
  put "milk" into myBox["coldStuff"]
  put "flour" into myBox["staple"]
  put 20 into myBox["dollars"]
  put false into myBox["needToothpaste"]
  put the keys of myBox into fld "arrayElements"

This statement would produce the following list in field "arrayElements":

dollars
staple
breakableStuff
coldStuff
needToothpaste

What if you wanted to list all of the contents of the array elements, rather than the key names? You can use the repeat for each element form of the repeat structure to loop through all of the elements in an array like this:

repeat for each element thisElement in myBox
    put thisElement & return after fld "basketContents"
end repeat

This would produce the following output in field "basketContents":

20  
flour
eggs
milk
false

More Information from the LiveCode User Guide:

You can use the split and combine commands as fast ways to convert a text list to an array and an array to a list.

Transforming a List of Data into an Array

The split command separates the parts of a variable into elements of an array. You can specify what character in the list you want the data to be split by. The data will be converted into a set of elements named according to where it is split. For example:

put "A apple,B bottle,C cradle" into myVariable split myVariable by comma and space

Will turn my variable into an array with the following structure:

KEY

VALUE

A apple

B bottle

C cradle

For more details, see the split command in the LiveCode Dictionary.

Combining the Elements of an Array into a List

The combine command combines the elements of the array into a single variable. After the command is finished executing, the variable specified by array is no longer an array.

For example:

combine myArray using return

Will combine the contents of each element of the original array so that they appear on a separate line, like this:
apple
bottle
cradle
If you want to include the key (the name) of the element in the list, include a second parameter:

combine myArray using return and comma

This will combine the contents of the original array so that they appear on separate lines, with the contents following the key on each line:
A,apple
B,bottle
C,cradle
For more information, see the combine command in the LiveCode Dictionary.

KEY	VALUE
A	apple
B	bottle
C	cradle

Saving Arrays

Since arrays are variables they are lost when the stack closes. Even arrays in global variables are only in existence during the current session. Once you quit LiveCode they are lost. There are several ways to preserve the contents of an array between sessions. All of them involve saving the array contents in some other form in another place, then recreating them when you restart the stack.

External File – Plain Text. One way to save an array is to use the combine command above and then save the resultant text to an external text file.
```
combine myArray using return and tab
put myArray into URL "file:/path/to/folder/savedArray.txt"
```
Upon restarting the stack you would read the text file in and use the split command to recreate the array.
```
put URL "file:/path/to/folder/savedArray.txt" into myArray
split myArray by return and tab
```
Advantages of this method:
- Resultant external file is human-readable;
- Resultant file is plain text and can be read and edited by other applications.
Disadvantages of this method:
- Might require tricky scripting to reconstitute complex multidimensional arrays.
External File – Array Encoded. A variant of the previous method is to use the arrayEncode function to convert an array into a specially encoded string that can be saved to an external file.
```
put arrayEncode(myArray) into URL "binfile:/path/to/folder/savedArray.txt"
```
Then upon restarting the stack read in the file to a variable and use the arrayDecode function to convert the string back into array format.
```
put URL "binfile:/path/to/folder/savedArray.txt" into tSavedArray
put arrayDecode(tSavedArray) into myArray
```
Advantages of this method:
- Simple and quick to save using arrayEncode();
- Simple to reconstitute by using arrayDecode();
- Complex multi-dimensional arrays can be reliably saved and reconstituted.
Disadvantages of this method:
- Resultant external file is not human-readable;
- Encoding is LiveCode-specific, can't be decoded by other applications.
Save as Part of the Stack – Custom Property. Finally, you can also save an array in the stack itself. As of LiveCode v. 3.0, you can save arrays in custom properties. Since custom properties are part of the stack file, they are saved when the stack is saved. All you have to do is make sure you save the array before you exit the stack:
```
global gDictArray

on closeStack
  set the dictionaryArray of this stack to gDictArray
end closeStack
```
Then load it back into your array variable when you open the stack:
```
global gDictArray

on openStack
  put the dictionaryArray of this stack into gDictArray
end openStack
```
Advantages of this method:
- Simple and quick;
- Since array is part of stack, no chance of “losing” the external file if you move the stack.
Disadvantages of this method:
- No way to inspect contents of array in the property inspector; you must read it into a variable to get access to its contents (in LC v. 7 and older; this is fixed in LC v. 8);
- If a stack is made into a standalone application you cannot modify the saved contents of the array.

Practice creating and using arrays by completing the Array Exercise.

Back BYU LiveCode Lessons Gateway