Now you see some common manipulations you can do with lists. Any time you have a position-dependent list, you probably will want to work with a repeat loop (no, don't run away!). Others functions you can use with linear lists include:

append adds a value to the end of a list.

count tells how many items are in the list.

getAt gets the value at a particular location.

getPos is a lookup function that tells where a value is.

setAt sets the value at a particular location.

Repeat loop function
A repeat loop consists of a variable that changes value. Unlike a regular script's straight progression from line to line, a repeat loop goes back and repeats the code again and again, changing the variable each time (in this example, incrementing the variable by one).

Suppose you have a repeat loop like this:

repeat with x=1 to 7
put x
end repeat

Then you'll see this in the message window:

-- 1
-- 2
-- 3
-- 4
-- 5
-- 6
-- 7

Internally the code is executing something like this:

set x=1
put x
set x=2
put x
set x=3
put x
set x=4
put x
set x=5
put x
set x=6
put x
set x=7
put x

In fact, if you wanted to perform these tasks the hard way without a repeat loop, these are the steps you'd have to go through.

You can see how loops are great for doing repetitive tasks where it's the same task over and over, starting at one end (with the value of 1) and working up to the other (with the value of 7). You can also can change the starting and ending numbers, as well as the direction (so that you count down) if you like.

From the preceding examples, note that you can create a list by initializing it this way:

set waveNameList =["BEBOP","COUNTRY","JAZZ","DISCO","RAP","CLASSICL","BLUES"]
set wavePlayList =[FALSE, FALSE, FALSE, FALSE, FALSE, FALSE, FALSE]

You can also create an empty list by doing this:

set waveSpecialList =[]

Append function
Append lets you add to a list. If you want users to enter the name of the Wave files (say they're going to choose names and later evaluate them), you set up the list like this:

append waveNameList, theNameTheUserGaveMe
append wavePlayList, FALSE
append waveTimeList, theTimeWeGotSomehow
append waveReactionList, 0

This list shows the user entering a name (such as "NEWAGE"), which is stored in the variable theNameTheUserGaveMe . You can then add the name to the end of your name list.

Remember that you have four lists to keep up to date, with the same number of entries in each. Thus, whenever you make one list longer, you must make the rest of them longer too, to avoid errors.

So you add an entry of FALSE to wavePlayList , because the file hasn't played yet. The reaction list gets 0 tacked on to the end, because there's no reaction yet.

For the time of the Wave file for the third list, you'll have to look up the information somehow (either test the file, or have the user supply the information, for example).

It's important that no matter what information you're storing, if you add to or delete from a list, then you must perform the same action on all the related lists. Remember, these lists only work because they are position-dependent.

Count and getAt functions
Whenever you perform an action on a list, you'll probably use a repeat loop. Using a repeat loop requires that you know how big the list is. That's where the count function comes in handy. In this example, you'll use the count function to see how many items are in the list, and the getAt function to get the value at a particular place in the list.

For example, to print out the reactions in the message window:

set numEntries =count(waveNameList)
-- See how many there are
repeat with x=1 to numEntries
-- Go through the list
if (getAt(wavePlayList, x) = TRUE) then
-- Did they listen to it?
put getAt(waveNameList, x) -- Print out the name
put getAt(waveReactionList, x)
-- Print out the reaction number
end if
end repeat

Notice in the example how you go through one list and use it as a key for other lists. The example also shows that:

The count of the list's number of entries was based on the waveNameList . This list was used for consistency, because it was first in the list. But you could use any list, as long as you kept all lists the same size.

This example also evaluated whether a particular entry had been played. If you set an entry to TRUE (because the variable started out as FALSE ), then that means the user had listened to it. If the user listened to it, then you could print out the reaction.

When a played entry was found (because using getAt returned TRUE ), you could use the current X value to get the corresponding entries out of the name list and the reaction list.

setAt function
How did the getAt value get set to TRUE ? Here the setAt function is very helpful. For example, the user plays entry 4. For this example it doesn't matter where the number came from; maybe the user gave it to us. The variable whichOneToPlay holds the number of the selection (that is, 4).

After it's played, the listener is asked for a reaction. The reaction is saved in a variable called theirReaction , and then the lists are updated:

setAt(wavePlayList, whichOneToPlay , TRUE)
setAt( waveReactionList , whichOneToPlay , theirReaction )

The playlist for that entry ( whichOneToPlay ) is set to TRUE , because it's been played, and the reaction list for that entry ( whichOneToPlay ) is set to their reaction ( theirReaction ). Thus, entry "4" in the list becomes TRUE , no matter what it was before, and the corresponding entry ( 4 ) in the reaction list holds the listener's reaction.

getPos function
The getPos function is useful for finding the location of a particular value. For example, if the user wanted information on "DISCO", use getPos to see which entry "DISCO" was in, as follows:

set location =getPos(waveNameList, "DISCO")

If location = 0, the list wasn't found. (Maybe it was misspelled.) But if the result is anything but 0, that means that the list was found (its value gives the position of the item in the list). This example shows how to print out the stats for it:

set location =getPos(waveNameList, "DISCO")
put getAt(waveReactionList, location)

In most of these examples, once you find the position, you can plug it into the functions you want to perform on the rest of the lists. Here, for example, you find the location and then plug it into your function to get the matching value from the reaction list.

For information on the various list functions, see the Lingo Dictionary or the Director help file.