BYU Home pageBRIGHAM YOUNG UNIVERSITY
  Office of Digital Humanities
Back     BYU LiveCode Lessons Gateway

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.

labeled box

variable

labeled box with compartments

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.

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.

  1. 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
    
  2. 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 urlDecode(tSavedArray) into myArray
    
  3. 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.


Back     BYU LiveCode Lessons Gateway
Maintained by Devin Asay.
Copyright © 2005 Brigham Young University