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 "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.
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.
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 put "Hi." into greetings put "What up" into greetings
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 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
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 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
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
You can use the
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
splitcommand 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
splitcommand in the LiveCode Dictionary.
Combining the Elements of an Array into a List
combinecommand 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.
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
combinecommand in the LiveCode Dictionary.
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.
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
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
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
Practice creating and using arrays by completing the Array Exercise.