List

Lingo Lists

Lingo lists can be used to store and organize data. Other languages use arrays for this. When counting items in a list, Director starts at 1 (not 0 as in some other languages).

Lists are objects. If you pass a list as a parameter to a handler and the handler modifies the list, the calling handler will subsequently see the modified list:

on ModifyList(aList)
  aList.setAt(3, #surprise)
end ModifyList

on TestList()
  vList = []
  ModifyList(vList) -- contents of vList will be modified
  return vList
end TestList

put TestList()
-- [0, 0, #surprise]

See Passing by Value, Passing by Reference for more information on how objects behave.

Creating a list

vLinearList = list()
vLinearList = list(#one, #two, #three)

vLinearList = []
vLinearList = [1, 2, 3]

vPropertyList = [:]
vPropertyList = proplist()
vPropertyList = propList(#one, 1, #two, 2, #three, 3)
vPropertyList = [#one: 1, #two: 2, #three: 3]

vNewList = vExistingList.duplicate()
Copies the existing list to a new memory address. Subsequent operations on vNewList will not affect vExistingList.

Methods

Adding items to a list

• sortedLinearList.add(value)
  Adds item in proper order
• unsortedLinearList.addAt(index, value)
  Adds item at given position
• unsortedLinearList.append(value)
  Adds item at the end

• propList.addProp(property, value)
  Adds item at the end if the list is unsorted, or at its proper position if the list is sorted

Modifying items in a list

• list.setAt(index, value)
  Sets value at given index
• propertyList.setaProp(property, value)
  Sets value of the first occurence of the given property, or adds the property with the given value if it does not already exist.
• list.setProp(property, value)
  Sets value of the first occurence of the given property. If the property does not exist, a Script error will occur.

There is no built in way to change the property name of any property in a propList. This handler will allow you to do that, given the property list itself, the old name that is being removed, and the new name that is being brought in:

--renames a property in a proplist based on the old propname

--@vList - proplist

--@vOldProp - string or symbol - old name that is being replaced

--@vNewProp - string or symbol - new name that is replacing the old one

on setPropName vList,vOldProp,vNewProp

 newList=[:]
 repeat with iProp=1 to vList.count
   thisProp=vList.getPropAt(iProp)
   if thisProp=vOldProp then
     newList.addProp(vNewProp,vList[iProp])
   else
     newList.addProp(thisProp,vList[iProp])
   end if
 end repeat
 return newList

end

Retrieving data from the list

• list.getAt(index)
  
• list.getLast()
  Returns the last value in the list or VOID if the list is empty (Note: getLast() is faster than using getAt(n), where n is the number of items in the list)
• list.getOne(value)
  Returns the index (linear list) or property (property list) associated with the first occurrence of the given value
• list.getPos(index)
  Returns the index associated with the first occurrence of the given value
• propertyList.getProp(property)
  Returns the value of the first occurrence of the given property. If no such property exists, a Script error will occur.
• propertyList.getaProp(property)
  Returns the value of the first occurrence of the given property. Returns VOID if no such property exists.
• propertyList.getPropAt(index)
  Returns the property at the given index

• list.findPos(property or value)
  Returns 0 or the integer index of the first occurrence of the given value (linear list) or property (property list)
• sortedPropertyList.findPosNear(property)
  Returns the integer index of the first occurrence of the given property, or of the following item if the given property does not appear in the list. May return a value one greater than the number of items in the list.

Deleting list items

• list.deleteAll()
  Deletes all items from the list (faster than creating a new list)
• list.deleteAt(index)
  Deletes the item at the given index
• list.deleteOne(value)
  Deletes the first item with the given value
• propList.deleteProp(property)
  Deletes the first property with the given name
• list.deleteProp(index)
  Deletes the item at the given index (Identical to list.deleteAt(index))

Modifying the order of items

• list.sort()
  Sorts the list alphabetically and numerically

Dot and Bracket Syntax

• list[index or property] = value
  Sets value at given index or first occurrence of given property
• propertyList.propertyName = value
  Sets the value of the first occurrence of the property propertyName. This property must exist or a Script error will occur.
• propertyList[#propertyName] = value
  Sets the value of the first occurrence of the property propertyName. If the property does not exist, it will be added to the list.

Retrieving information about the list

• list.count()
  Returns the number of items in the list
• list.ilk()
  Returns #list or #propList
• listP(list)
  Returns 1 for both linear and property lists. list.listP() causes a Script error
• list.min()
  Returns the minimum value in the list
• list.max()
  Returns the maximum value in the list

Caution: .count and .ilk can be used as properties rather than functions but you must use parentheses with min() and max(). Without parentheses, the entire list is returned:

put [1, 2, 3].max

-- [1, 2, 3]

Properties

• list.count
  Returns either the number of items in the list, or the value of the first property named #count, if such a property exists.
• list.ilk
  Returns #list or #propList
• list.listP
  Returns 1 if the variable list is a list or a proplist. Can also be used as a function, but only with the syntax listP(list). The version list.listP() quoted in the official documentation will cause an error.

Operations

You can use arithmetic operations on lists. Here are some examples:

put [1, 2, 3] + 100
-- [101, 102, 103]

put [1, 2, 3] + [100]
-- [101]

put [100] + [1, 2, 3]
-- [101]

put [1, 2, 3] + [100, 200, 300, 400]
-- [101, 202, 303]

put [1, 2, 3] * [100, 200, 300, 400]
-- [100, 400, 900]

put [100, 200, 300, 400] * [1, 2, 3]
-- [100, 400, 900]

put [100, 200, 300, 400] / [1, "2", 3.0]
-- [100, 100.0000, 100.0000]

Points, rects and colors are extensions of the list type, so similar operations can be performed with these ilks, so long as the operands are given in the correct order:

put point(10, 20) + [90, 100]
-- point(100, 120)

put [90, 100] + point(10, 20)
-- [100, 120]

put [1, 2, 3] + rgb(100, 10, 1)
-- [color( 101, 11, 2 ), color( 102, 12, 3 ), color( 103, 13, 4 )]

put  rgb(100, 10, 1) + [1, 2, 3]
-- 0

put  rgb(100, 10, 1) * 25
-- color( 255, 250, 25 )

put 25 * rgb(100, 10, 1)
-- color( 255, 250, 25 )

JavaScript Arrays

See Also

Macromedia TechNote